Use Modules in Workflows

This topic provides an example that shows how to create:

  • A workflow module that uses steps to send an approval email and execute an embedded script. The module uses input variables to enable information to be passed in from steps in the workflow the module is added to.
  • A command workflow that includes a step to run the configured module. Input variables used in a step in the workflow will pass information into a step in the workflow module.

Input variables provide a way to pass information from a workflow to steps in the workflow module. In this example, the command workflow passes static information (an approver's email and a script) into the input variables used in the workflow module.

It's also possible to pass output that's generated from a workflow step into the input variables used in a Run Module step that comes after the workflow step. For example, a workflow step could retrieve information, such as an IP address, from another system, then, in the Run Module step, pass it into an input variable that provides the information to the workflow module.

This example uses a command workflow, but the steps are similar for all workflow types.

Create the workflow module

  1. Click Configuration > Command Workflows.
  2. Click the Modules tab, then click Add.
  3. In the Command Workflow Module Configuration dialog, enter "Approve and execute script" as the module name and enter a description for the workflow module (for example, "Sends an approval email, and once approved executes the specified script.").
  4. For Target Type, leave the default value of VM, then click Next.
  5. On the Input Variables page, do the following to add two input variables for the module to use — one for the approver's email address, the other for the script contents:
    • To add an input variable for the approver's email address, click Add. In the Input Variables dialog that appears, enter the following:
      1. For Display Name, enter an identifying name for the input variable (in this case, "Approver Email Address").
      2. For Variable Name, enter the name that will be used for the variable expression. For example, if you enter "approver", the resulting expression will be #{inputVariable['approver']. See Variable Syntax for Emails and Scripts for basic variable syntax.
      3. For Description, enter a description to indicate that the variable is used to get the approver's email address.
      4. For Default Value, enter the email address of the network administrator.
      5. Enable the Required check box to ensure that a value is provided for this variable when the workflow is run.
      6. Click OK.
    • To add a variable for an embedded script, click Add. In the Input Variables dialog, enter the following:
      1. For Display Name, enter an identifying name for the input variable (in this case, "Script Contents").
      2. For Variable Name, enter the name to be used for the variable expression (in this case, "Script").
      3. For Description, enter a description to indicate that the variable is used to receive output from script that will be run in the workflow.
      4. Enable the Required check box to ensure a value for the variable is provided when the workflow is run.
      5. Click OK.
  6. Click Next.
  7. On the Steps page, add a step to send an approver email:
    1. Click Add > Send Approval Email.
    2. In the details section, name the step "Send Email".
    3. From Step Execution, select Execute when condition are met, then click Edit at the right of the field.
    4. In the script editor, search for Input Variables, then select the Approver Email Address attribute and click Insert.

      In the Condition section, enter "-ne"" to add a not-equals operator to the end of the expression. This indicates that if the approver exists (or isn't empty), then run the step:

      "#{inputVariable['approver']}" -ne ""

      See Make Workflow Steps Conditional for more details on operators.

    5. Click OK.
    6. For Address List, click .
    7. In the script editor, search for Input Variables, then select the Approver Email Address attribute. Click Insert, then click OK.
    8. For Email Subject, enter "Command workflow approval needed".
    9. For Email Body, click .
    10. In the script editor, enter "Please review the following script and approve:", then from the Variables list, search for Input Variables, select the Script Contents attribute. Click Insert, then click OK.
  8. Add an step to execute an embedded script:
    1. On the Steps page, click Add > Execute Embedded Script.

      An Execute Embedded Script differs from an Execute Script in that you must provide the entire script contents, which is then saved in the workflow definition. This makes the step portable — it allows you to use the module that contains the step in multiple workflows, but you don't have to worry about uploading the script file. See Add Execute Embedded Script workflow steps for more information.

    2. In the details section, name the step "Execute Embedded Script".
    3. For the Executable field, enter the executable that will be used run the script.

      If your system environment doesn't have the script executable on its path, you must provide the fully-qualified path to it (for example, "C:\python37\python.exe"). Note that to use Windows Powershell, you only need to enter "powershell.exe".

      When the step is run, it writes a temporary script file to the system. Some scripting executables require files to have a particular extension (for example, powershell.exe requires a .ps1 extension for scripts). For an executable that requires a file extension, you must map the executable and file extension in the embotics.workflow.embedded.script.extensions Commander system property. By default, default mappings already exist for the following executables: powershell.exe=.ps1, python.exe=.py, cmd.exe=.bat. See Set system properties in Commander for details on how to modify system properties through the Admin Portal.

    4. In the Script Contents field, click .
    5. In the script editor, search for Input Variables and select the Script Contents attribute. Click Insert, then click OK.
  9. Click Next.
  10. On the Summary page, enter details about the module in the Description of Changes field, review the module details, then click Finish.

Create the command workflow

  1. Go to Configuration > Command Workflows.
  2. On the Workflows page, click Add.
  3. In the Command Workflow Configuration wizard, enter a name for the workflow (for example "Email VM's primary owner email and execute script").
  4. For Target Type, leave the default value of VM, then click Next.
  5. On the Steps page, add a step to send an email to the VM's primary owner:
    1. Click Add > Send Email.
    2. In the Address List field, click .
    3. In the script editor, select the Primary Owner Email, click Insert, then click OK.
    4. In the Email Body field, enter the message to send out (for example, "Getting approval to run a script on the VM.").
  6. Add a step to run your the module you configured in the previous procedure:
    1. Click Add > Run Module.
    2. For Step Name, rename the step to something more descriptive (for example, "Run module to send email then execute script").
    3. For Step Execution, leave the default value of Always Execute.
    4. From Workflow Module, select Approve and execute script that you created earlier.

      The input variables included with the module are displayed.

    5. In the Input Variables section, for the Approver Email Address variable, enter the administrator's email address.

      The <a> tag is automatically added to links in emails (only the http protocol is supported). For example, if the value of a custom attribute is a link, the value will be formatted as a link in the email.

      If you don't use HTML markup in the email body, the body is assumed to be plain text; <br> and <p> tags are automatically added for new lines.

      If you add HTML markup to the email body, however, no additional tags are added.

    6. For Script contents, enter "NET USE:Z: \\CorpDIR\Files.

      This provides the content for the embedded script step in the module to run.

  7. Click Next.
  8. On the Permissions page, decide who will have access this workflow, then click Next.
  9. On the Options page, enable other settings as required, then click Next.
  10. On the Summary page, enter details about the workflow in the Description of Changes field, review the module details, then click Finish.