Procedures and Functions are the steps making up an Action. They allow you to define the installation logic of a Component. Procedures do not return a value while Functions do. The Procedures and Functions tab is under the Flows Main Menu Item.

Adding and Deleting Custom Procedures and Functions

You can add and configure user-defined Functions or Procedures by going to the Flows menu and selecting the Functions and Procedures tab. This will display a list of Domains and Life Cycle Sub-Domains. Right click on the Domain where it is to be located and select either “New Procedure in this Domain” or “New Function in this Domain”.


A Procedure can be one of four types:


Procedure

Description

DMScript Procedure in Repository

A Procedure is written in DMScript  and stored in a file located in an external Repository.

DMScript Procedure in Database

A Procedure is written in DMScript and stored in the DeployHub Database (a "Stored Procedure").

Procedure Provided by Local External Script or Program

A 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.

Procedure Provided by Remote External Script or Program

A 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.


A Function can be one of four types:


Procedure

Description

DMScript Function in Repository

A Function is written in DMScript and stored in a file located in an external Repository.

DMScript Function in Database

A Function is written in DMScript and stored in the DeployHub Database (a "Stored Procedure").

Function Provided by Local External Script or Program

A Function 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.

Function Provided by Remote External Script or Program

A Function 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.


Selecting the Procedure/Function kind will show other fields relevant to that particular kind (for example "Copy to Remote" will only appear for kind "Remote External Script or Program". Fill in the fields and then click OK to create the new Procedure/Function.

Body Tab

For Procedures/Functions defined as being "DMScript in Database" an additional "Body" tab is presented which allows the "stored" DMScript to be viewed and edited. Clicking on the "Body" tab will show the DMScript associated with the Procedure/Function. This is presented with syntax highlighting (it is optional and is set on by default).

action name {

}


or


function name(arg1,arg2) {

}

NOTE: The DMScript "header" for the Procedure or Function is implicit from the Args tab and should not be entered. This means you should just edit the "Body" of the Script and not attempt to add either.


To Edit the DMScript body, click on the pencil icon in the top-right of the Body Tab. You’ll see  an edit area (into which text can be typed) and a menu bar with icons and drop-downs:


  • 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.


Enter or change the DMScript body in the main editor window. Double clicking on an opening or closing brace will highlight both the selected brace and its matching brace. Clicking OK will check the DMScript for syntax errors and – if none are found – will close the window. If any issues are found, the cursor is placed onto the line in error and the error message is shown on the line under the editor window. It is not possible to save DMScript with such syntax errors.

Args Tab – External Procedure/Function

A list of arguments can be made available for the Procedure/Function. To create a new Argument, go to the Flows menu, select a Procedure/Function in the tree structure, and click the Args tab. Select the Plus (+) icon to add a new argument to the table, or click the pencil icon to edit an Argument selected in the table. The content and layout of the Args Tab will differ depending on the type of Procedure/Function.

Type: External Procedure/Function

There are two sections to the Args tab for External Procedures or Functions (either local or remote). These sections allow you to construct a command line from the arguments passed to the Procedure/Function. The section titled ‘Inputs to this Function/Procedure’ contains the following fields:


Field

Description

Name

Name of the Argument. The Name must start with a letter and must only include A-Z, a-z, 0-9 and _ (underscore). No spaces or dashes are allowed in the name.

Type

Values are Entry or Checkbox. This determines how the "input" to the Procedure or Function is rendered when it is dropped into the Action Editor.

Present

Type: Entry

The text that will be prepended to the value should the argument be provided. For example, for a "filename" argument the Present flag could be set to –f. If filename is provided then the argument will become –f "<filename>".


Type: Checkbox

The text that will appear if the checkbox is selected. For example, if Present is set to –checked then the argument will become –checked should the checkbox be checked.

Missing

Type: Entry

The value that will be inserted should the argument not be provided. Only used if "Required" (see below) is false. If the optional argument is not provided then the Missing text is substituted. For example, for a "filename" argument the Missing flag could be set to –nofile. If no filename is provided then the argument will become –nofile.


Type: Checkbox

The text that will appear if the checkbox is not selected. For example, if Missing is set to –notchecked then the argument will become ‑notchecked should the checkbox be unchecked.

Preserve With (Pad)

Preserve With "" When Not Present ensures that the argument occupies its positional parameter regardless of whether it is a null-length string or not. For example, if the command line is

myscript ARG1 ARG2 ARG3

if ARG2 is a null-length string then myscript would be called with:

       myscript ARG1 ARG3

Padding (or preserving) will mean the script is invoked like this:

       myscript ARG1 “” ARG3

This feature is useful if the script always requires the same parameters to be in the same position on the command line.

Required

Indicates the argument is required for the Procedure/Function. This is used when dropping the Procedure/Function into the Action Editor. Any Argument marked as being "Required" is highlighted and cannot be left blank.


The section titled ‘Additional command line switches for program below’ 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 sign (+)  icon and adding text.


Each "Additional Command Line Switch" can include variables and these 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 that are set by Additional Parameters to the invoking Task. See Chapter 1 (Domains) for more information on adding Additional Parameters to Tasks.


Each "Additional Command Line Switch" will be "padded" (surrounded by implicit quotes) and will be treated as a single argument when the command line is constructed. If you want to have separate flags and variables (for example –homedir $SERVDIR (where SERVDIR is an attribute held against the Target Endpoint) then you will need to create two "Additional Command Line Switches" – one for –homedir and one for $SERVDIR.


All the input parameters and the Additional Command Line Switches will appear above the resulting command line in dotted boxes. To construct the command line, simply drag and drop the boxes in the order required to build the command line.

Type: DMScript

There is only a single section to the Args tab for DMScript Procedures or Functions (either in Repository or in Database).

The section titled ‘Inputs to this Function/Procedure’ contains the following fields:


Field

Description

Name

Name of the Argument. The Name must start with a letter and must only include A-Z, a-z, 0-9 and _ (underscore). No spaces or dashes are allowed in the name.

Type

Values are Entry or Checkbox. This determines how the "input" to the Procedure or Function is rendered when it is dropped into the Action Editor.

Required

Indicates the argument is required for the Procedure. This is used when dropping the Procedure/Function into the Action Editor. Any Argument marked as being "Required" is highlighted and cannot be left blank.


Entered Parameters will be accessible as variables within the DMScript Procedure/Function. Checkbox values are passed as true (1) if the checkbox is selected, false (0) otherwise. You can therefore use DMScript constructs like this:


if ($myval) {

// myval checkbox is checked

} else {

       // myval checkbox is NOT checked

}


To see if the checkbox named "myval" is checked or not

Timeline Tab

This tab displays log file entries for deployments that used this Procedure/Function, including deployment number, Environment, and how many days ago the deployment (hours for all of today’s deployments) took place. Click on the ‘Click to see earlier items’ link to see all of the entries.

Timeline Comments

Users can add comments to these entries by clicking on the ‘Comment’ link within each entry, which opens a text entry field just below the deployment information. Users can also click on the Subscribe link in each entry of the list, which allows the User to receive information about the selected deployment. Any comments added to the deployment will appear in the Timeline column of the subscriber’s home page.


A field labeled “Say something about this Procedure?” is above all of the deployment lines for such comments. Files can be attached as well. Entering text here activates the Add Message button. Click to save the comment as a new audit entry.

Adding Documents to the Timeline

Clicking on the paperclip button next to the Add Message button brings up a file explorer, which allows multiple files to be selected and attached to the comment.


Comments with files attached are shown with a paperclip. Clicking on the paperclip expands the audit entry to show those as hyperlinks. Clicking on the link will download the file. This process is browser-specific.

Access Tab

This tab contains Groups and the Users that have access to this Procedure/Function. Click on a Group name in the Available Groups list. Drag this into one of the lists to allow the Users to View, Change, or Execute the currently selected Procedure/Function. If the Procedure/Function is already part of a parent Action then no check is yet the Procedure/Function still runs.

Access includes:


Access

Description

View

Allows the User to see the Procedure/Function. If the User does not belong to a Group in the View Access list, the Procedure/Function will not appear in the tree structure.

Change

Allows the User to changes the Procedure’s/Function’s characteristics i.e. Name, Summary, etc.

Execute

Allows Users to execute this Procedure/Function.

General Tab

The General tab is where the basic information about the Function or Procedure is defined. This information includes:


Field

Description

Name

Name of the Function/Procedure.  This cannot be the same as a reserved word within DMScript (see the DMScript chapter), as it will cause a syntax error when executed.

Summary

A short description of the Function/Procedure.

Category

The category in which the Function/Procedure can be found under the Activities pane on the Action Editor.

Owner Type

The default owner is the User who created the Function/Procedure. When editing this field, the Owner Type field is available which includes Owner and Group as choices. Selecting one of these causes the Owner field to display either Users or Groups to choose from.

Created

The date and time the Function/Procedure was created. Read Only.

Modified

The date and time that the Function/Procedure was last modified. Read Only.

Description

A brief description of the Procedure/Function.

Kind

  • Options include:

Function/Procedure Provided by Local External Script or Program

An external script (written in any programming or scripting language) that is invoked when the Function/Procedure is called. The script is resident on the same machine as the deployment engine or can be referenced from that machine via a shared drive or UNC path. An additional Filepath field will appear if this option is chosen. Filepath is the location on the deployment engine where the script can be located.


Function/Procedure Provided by Remote External Script or Program

An external script (written in any programming or scripting language) that is invoked when the Function/Procedure is called. The script is resident on the target Endpoint unless “Copy to Remote” is checked (see below) in which case the path should refer to a directory on the same machine as the deployment engine (or can be referenced from that machine via a shared drive or UNC path) and the script is then “pushed” onto the target Endpoint and executed there. If the script is pushed onto a Windows server, the script is placed into the c:\Windows\System32 folder. On a Unix or Linux system, it’s placed into the /tmp directory.


All scripts that ship with DeployHub are placed into the $DMHOME\scripts directory on the deployment engine server. It would be a good idea to place any customized scripts into that directory as well, and always enter $DMHOME\scripts into the Filepath field (see below) when using Copy to Remote.


An additional Filepath field will appear if Function/Procedure Provided by Remote Script or Program is chosen. The Filepath is the location either on the remote (target) Endpoint (copy to remote not checked) or on the deployment engine (copy to remote checked) where the script can be located.


DMScript Function/Procedure in Repository

A Procedure or Function written in DMScript and stored in an external repository. This means the script can be under version control. Additional fields will appear if this option is chosen:

Repository: The name of the repository where the script can be located.


Filepath: The full path to the file in the repository containing the script.

NOTE: Since the only option is "filepath", the Repository definition must include all the other properties required to locate the script.


DMScript Function/Procedure in Database

A Procedure/Function written in DMScript and stored in the DeployHub Database.

Display Name

The name that appears on the icon that represents the Procedure/Function within a Workflow. Defaults to the value of the Name field if not supplied.

Filepath

The filepath to the script to be executed, which includes the name of the script. This appears for all but the “DMScript Procedure in Database” Kind of Procedure/Function.

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.

Copy to Remote

A checkbox that causes DeployHub to copy the procedure script from the directory indicated by the filepath field on the localhost machine to the target machine. The procedure is then executed there. In Windows, it is placed into c:\Windows\System32. On Linux/Unix, it is placed into /tmp. This only appears for Procedures/Functions that are of the Kind ‘Procedure/Function provided by remote external script or program’.

Result is Expr

Available only for Functions. If this box is checked then the return value from the function is interpreted as DMScript.


Thus, if the Function returns this as its standard output:

set a = {"x" => "1", "y" => "2"};

If "result is expr" is checked, an array is created called "a" with two elements - key "x" will be value "1" and key "y" will be value "2".

This is used in various Functions. For example, the "listservices" Function which lists the services on a Windows server returns the list into an array using this mechanism.


To delete a Procedure/Function, right click on it in the tree structure and select “Delete this Procedure”.

Archiving

Any time a Procedure or Function is changed, an archived version is saved within DeployHub. In the tree structure beneath the Function or Procedure, and within the Domain, there will be a copy of the Function/Procedure with all Access removed, using the original name followed by ‘_archived’. Every time the Function/Procedure is changed, another one will appear with the name followed by an incremented number (‘_archived_1’, ‘_archived_2’, etc.).