Procedures and Functions
Functions and Procedures
Functions and Procedures are the steps that make up an Action. If you have not worked with Actions, read about them in them in the Customize your Actions Chapter.
Functions and Procedures are used by Actions to define custom installation logic of a Component or perform any type of Pre or Post Action. Using Actions, Functions and Procedures allows you to be as creative as needed to meet the unique needs of your implementation.
The difference between Functions and Procedures is a Procedure execute a process but does not return a value. A Function returns a value. DeployHub provides a Dashboard for customizing your Functions and Procedures including the creation of Parameters, and a Parameters Dialog box that is displayed at the Action level. The Parameters Dialog Box enables other Users to utilize your custom process, with an easy way to understand what Parameter options are available. In this way, you are able to create custom Functions and Procedures and share them across teams. The associated Parameters Dialog Box simplifies the use of your custom process.
Functions and Procedures can be:
| Function or Procedure Type | Description |
|---|---|
| DMScript in Database | A Function or Procedure is written in DMScript and stored in the DeployHub Database (a “Stored Procedure”). |
| Local Script | A Function or Procedure is written in any Scripting Language that can be executed by the operating system on which the DeployHub Deployment Engine is installed. Executes locally to the Deployment Engine. |
| Endpoint Script | A Function or Procedure is written in any Scripting Language that can be executed by the target Endpoint’s operating system. Executes on the target Endpoint. By Checking the “Copy to Remote” flag, the script can be held locally to the Deployment Engine and copied to the target Endpoint at the point of execution. |
The Functions and Procedures List View for Adding or Deleting
From the Functions and Procedures menu option to the left of the DeployHub main panel, you will be taken to a list of all available Functions and Procedures which you have access to based on the Domain. You can also use the Filter bar, represented by a funnel icon, to reorder your Functions and Procedures List View. You can filter on:
- Domain
- Name
- Type (Function or Procedure)
The Function or Procedure List View has the following Tabs.
| Tab | Description |
|---|---|
| Refresh | Refreshes the browser. |
| Add Procedure | Allows you to Add a new Procedure.
|
| Add Function | Allows you to Add a new Function with the types:
|
| Delete | Deletes the selected item. |
| Export | Allows you to Export an existing Function or Procedure. Used to transfer Functions and Procedures between DeployHub installations, and allows you to check them into a source repository. |
| Import | Takes a previously exported Function or Procedure and re-imports it. Will maintain the original Function or Procedure name regardless of the name of the import file (.re). To change the Name of the Function or Procedure, update the “action name="[new name]” inside the .re file that was exported. Duplicate names are allowed as long as they are defined using a different Domain. |
From the Functions and Procedures List View, double click on the Functions or Procedures to view to see all Details.
Using the Function or Procedure Dashboard for Viewing and Editing
The Dashboard view displays all information related to a specific Function or Procedure. The following details are common to all Types.
| Details | Description |
|---|---|
| Full Domain | The fully qualified Domain to which the Function or Procedure belongs. |
| Name | A unique Name that identifies the Function or Procedure |
| Summary | A brief description of what the Function or Procedure does. |
| Category | Categories are used to arrange Function or Procedure in an orderly manner. Assigning a Category to an Function or Procedure allows lists of Categories to be used throughout DeployHub. Clicking on an individual Category expands the list and shows all Function or Procedure that belong to that Category. You can add a new Category by simply adding it to the list using the entry field. Pre-defined Categories include: |
| Owner Type | User or Group |
| Owner | The User or Group name of the Function or Procedure’s owner. The default owner is the User who created the Function or Procedure. |
| Created | An auto generated date when the Function or Procedure was created (read-only). |
| Modified | An auto generated date when the Function or Procedure was last modified (read-only). |
| Object | Displays if the item is Function or Procedure. |
| Type | Displays the kind of the Function or Procedure created when added. |
| Display Name | An alternative Name if required. If not used defaults to the “Name”. |
Additional Details for Local Scripts
This type of Function or Procedure runs on the deployment engine and requires these additional details.
| Details | Description |
|---|---|
| Filepath | The filepath to the script to be executed, which includes the name of the script. |
| Command Line Interpreter | Your Function or Procedure will be written using a particular language such as Python. This field in the fully qualified path and name of your interpreter. DeployHub will need this to execute your process. |
| Result is Expr | Result is Expression is used for return values for Functions only. This will not be displayed for Procedures as they do not return a value. If this box is checked, the return value from the Function is interpreted as DMScript. For example, the “listservices” Function which returns a list of services on a Windows Endpoint returns the list into an array using this option. |
Additional Details for Endpoint Scripts
This type of Function or Procedure runs on the Endpoint and requires these additional details.
| Details | Description |
|---|---|
| Filepath | The filepath to the script to be executed, which includes the name of the script. |
| Command Line Interpreter | Your Function or Procedure will be written using a particular language such as Python. This field in the fully qualified path and name of your interpreter. DeployHub will need this to execute your process. |
| Allocate Terminal | If checked, this sets up a pseudo-terminal. This is for Unix/Linux targets only when operating over SFTP transfer protocol. It controls the behavior of executed programs if they operate differently with or without an allocated terminal. Note that any program running with this flag set and which calls isatty will receive a return code of true. |
| Result is Expr | Result is Expression is used for return values for Functions. If this box is checked, the return value from the Function is interpreted as DMScript. For example, the “listservices” Function which returns a list of services on a Windows Endpoint returns the list into an array using this option. |
| Copy to Remote | A checkbox that causes DeployHub to copy the script from the directory indicated by the filepath field on the deployment engine to the target Endpoint. The script is then executed there. |
Access
The Access Section allows Users within designated Groups to update the Function or Procedure in various ways. To add a Group to one of the access lists, drag and drop the Group from the Available Groups list onto desired access list. All Users who belong to a Group that appear in one of the Access lists will be granted access to the Function or Procedure in the following ways:
| Access | Description |
|---|---|
| View | Allows Users to see the Function or Procedure. If the User does not belong to a Group in the View Access list, the Function or Procedure will not appear in the List View. |
| Change | Allows User to change the Function or Procedure characteristics i.e. Name, Summary, etc. |
| Execute | Allows Users to execute this Function or Procedure. |
Audit Trail
The Audit Trail displays audit entries for any changes or deployments that impact this object. It includes any changes in the object including User date and time, and deployments with unique numbers.
You can Subscribe to or Comment on an Audit Entry.
-
Subscribe: Allows you to receive information about the selected deployment.
-
Comment: Add information by clicking on the ‘Comment’ link within a text entry field. There is a field above the list labeled “Say something about this Application” that can have comments placed into it, and files can be attached to the comment as well. Enter text into this field to activate the Add Message button. Click to save the comment.
-
Add Files to Comments: Click on the paperclip icon to add a file to the message. Once added and you made a comment, click “Add Message”. Click on the paperclip icon to retrieve these attachments. The icon opens the line in the list to display the name of the file. Choose the file to download it into the your default Download directory on your local computer.
Input Parameters – and Command Line Switches for your Custom Function or Procedures
When you create your Function or Procedure it will most likely need parameters. This section allows you to define the format of the parameters and display them in the Action blueprint designer. When your Function or Procedure is added to the Action blueprint designer, a Parameter Dialog Box will be automatically displayed prompting the user to enter the required values. A right mouse click on the same will open the Parameter Dialog Box. The Input Parameters, Command Line Switches and the Command Line Section work together to define how the command line call will be formatted. You will establish how your user will enter parameter values when they use your custom Function or Procedure through the use of the Parameter Dialog Box. For Functions and Procedures that are of the Type “DM Script in Database”, you will not see Command Line Switches Section or a Command Line Section. Instead you will be provided with an embedded editor for creating the DMScript that will be saved in the Database.
- The Input Parameters Section defines how the dialog box is laid out and how the flags will be passed to the command line.
- The Command Line Switches Section provides a table of parameter switches that can be used to construct the command line call.
- The Command Line Section builds out what your command line call will look like using drag and drop of the Input Parameters and Switches.
Input Parameters Section
This section has two purposes. First to define the fields that will be presented on the Parameters Dialog box as a checkbox or entry field. Secondly, it defines the parameters being passed to the command line by the Function or Procedure.
A list of parameters can be made available for the user of your Function or Procedure from the Actions blueprint designer. To create a new parameter, Use the +Add option. A new row in the table will be made available where you can then define the following parameter attributes:
| Attribute | Description |
|---|---|
| Name | The name of the input parameter. It can only have the characters A-Z, 0-8, and “_”. |
| Type | This defines if the input parameter can be entered as text, or as a checkbox. This field will be displayed on the dialog box used to edit the values for the Procedure or Function on the Action blueprint designer. |
| Format | This field defines what your Parameters Dialog Box will look like.
|
| Missing | This field provides a default if the above Format value is null. Like the Format value, it uses Entry and Checkbox types.
|
| Padding | This field is used for positional command line parameters where you need to provide quote, space, quote (" “) for a positional parameter that is not entered by the user. This prevents the command line from throwing and error. |
| Required | Indicates the argument is required for the Procedure/Function. Any parameter marked as being “Required” is highlighted and cannot be left blank. |
| Pos | This is used only when calling the Function or Procedure from DMScript. The Position orders the parameters when making the call in DMScript. |
Command Line Switches
The Section allows for the creation of “fixed” command line switches or other attributes that you wish to have present on the generated Command Line. These can be created by clicking on the plus +Add option to add a new switch. You must use Save to commit the new row to the table. When you add Parameters and Switches, they are placed in a “pallet” above the Command Line Section. To remove or update an item, check the item and use Delete or Edit options.
Each “Command Line Switch” can include variables which will be expanded when the Command Line is constructed and executed. These variables can be attributes stored against a DeployHub Object (such as Endpoint, Environment, Application, or Component) or can be Global Variables.
Command Line
You can drag and drop the items from the “pallet” of Switches in the correct order on your Command Line. The result displays how the Command Line has been constructed.
DMScript in Database Editor
The embedded editor includes:
- The Floppy Disk Icon is the “Save” button. This parses the DMScript for errors and, if none are found, saves the DMScript. If there any syntax errors, they are highlighted in the body of the text.
- The Binoculars Icon is the “Search” button. Clicking this icon opens a search/replace dialog.
- The Arrow Icon is a “go to line” button. Clicking the icon opens a dialog which allows a line number to be entered and moves the cursor to that line.
- The undo and redo Icons are for recent edits.
- Font Size Icon makes the text bigger or smaller as needed.
- The Paintbrush Icon switches the syntax icon on and off.
- The Eraser Icon resets the syntax highlighting and causes the editor to re-parse and re-highlight the entered text.
- The Paragraph Marker Icon switches on word wrapping.
Archiving Functions and Procedures
Automatic archives are created for all Functions or Procedures that are in use by an Action. If you change a Function or Procedure the archive will be displayed in the List View for reference. Every time the Function or Procedure is changed, it will be archived in the List View and appear with the name followed by an incremented number (’_archived_1’, ‘_archived_2’, etc.).
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.