Procedures and Functions

Customizing your Deployment Actions with Functions and Procedures.

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.
  • DMScript in Database
  • Local Script
  • Endpoint Script
Add Function Allows you to Add a new Function with the types:
  • DMScript in Database
  • Local Script
  • Endpoint Script
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:
  • Build - Actions, Functions and Procedures for calling ANT (SalesForce integration).
  • Database - Actions, Functions and Procedures for database updates.
  • Deploy-Actions, Functions and Procedures for Deployments.
  • Dropzone- Actions, Functions and Procedures for interacting with the Dropzone.
  • File Logic-Actions, Functions and Procedures related to File manipulation.
  • Flow Logic-Actions, Functions and Procedures for if then else in DMScrit.
  • Loops-Actions, Functions and _Procedures_for file looping.
  • General-Non-categorized Objects (default).
  • WebLogic-Actions, Functions and Procedures for deploying to WebLogic.
  • WebSphere-Actions, Functions and Procedures for deploying to WebSphere.
  • Windows-Actions, Functions and Procedures used for Windows deployments.
  • 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 layed 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 drog 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.
    • Entry Field - Using the “entry” option will allow your user to enter the required value and not worry about any flags that are needed for the command line. In this field you will enter the flags that should be used for the command line. The end user will enter the value that they require and it will be pre-pended with the flag defined on this screen. The result will be used for the command line call. For example, if you enter -f in this field and then your user enters “filename” as a value, the resulting parameter passed to the command line will be “–f filename”.
    • If your type is set to “checkbox,” this will give the user the option to select the value or not for the command line call. In this case, you are defining the value and flags and simply giving the user the option to use them or not.
    Missing This field provides a default if the above Format value is null. Like the Format value, it uses Entry and Checkbox types.
    • Using the “entry” option will provide a default value for when the Format is not entered.
    • If your type is set to “checkbox,” this will provide a value when the Format checkbox is not selected by the user.
    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.).

    Last modified June 28, 2020: run markdownlint tidy (1259dc6)