Executing Scripts through Workflow Steps

To execute a script in a workflow, you can add an Execute Script or Execute Embedded step to a workflow or a workflow module.

The two types of workflow steps offer the same basic functionality, but they are implemented and get the script contents in different ways:

  • Execute Script step — This step executes a script that's saved on the local system. For this type of script, you must provide the absolute path to the executable.
  • Execute Embedded Script step — This step executes a script whose contents are provided in the workflow step itself (that is, the workflow definition) rather than saved on disk. This offers a few benefits:
    • Makes the step portable — if you export the workflow or module and use it in another Commander installation, you don't have to upload a separate script file.
    • Variables can be resolved and the data can be added to the script contents at runtime. For example, environment variables can be used to provide the required credentials to the script. For more information, see Using Environment Variables for Credentials.
    • The embedded script is versioned with the workflow. This means that if you modify the script contents and save the step, each new revision of the workflow or module will preserve your modifications. You can then revert to a previous revision if required. For more information, see Managing Workflow Revisions.

For more information, see:

Adding Execute Script workflow steps

Access through:

Configuration > Command Workflows

Configuration > Self-Service > Approval tab

Configuration > Self-Service > Completion tab

Available to:

Commander Role of Superuser and Enterprise Admin

To add an execute step to a workflow or a workflow module:

  1. On the Steps page of one of the workflow or workflow module configuration wizards, click Add > Execute Script.
  2. In the details section, change the step's default name of "Execute Script" if you want.
  3. For Step Execution, indicate whether you want the step to execute automatically (the default behavior) or execute only when specific conditions are met. To make a step conditional, select Execute when conditions are met, then click Edit and define the condition. See Making Workflow Steps Conditional for more details.
  4. For Timeout, adjust the default timeout, if required. The step will fail if it can't be completed within the given time.
  5. For Script Output, specify whether the value returned by the script should be captured as a comment, thus determining whether the request is approved or rejected. When you capture script output as comment, you can use script output as the input to a subsequent Set Custom Attribute step. See Using Script Output as Input to a Workflow Step. Scripts in approval workflows can also set deployment parameters.
  6. For Script Fails, indicate what to do if the script fails:
    • mark the step as failed and don't proceed
    • or, skip the step and go to the next step in the workflow

    Note: If a retry step is added to this execute script step, and it's set to Mark as Failed, the workflow will retry the failed step. See Adding Retry Steps to Workflows for details.

  7. For Command Line, enter the script that you want to execute.

    Note: You must provide the absolute path to the executable in the Command Line field, even if the executable exists in the Windows path. Otherwise, Java may attempt to execute the command in an incorrect location.

  8. If required, continue to add steps, and when you've finished, click Next.
  9. Continue to configure the workflow or workflow module, as required.

Adding Execute Embedded Script workflow steps

Access through:

Configuration > Command Workflows

Configuration > Self-Service > Approval tab

Configuration > Self-Service > Completion tab

Available to:

Commander Role of Superuser and Enterprise Admin

To add an embedded execute step to a workflow or a workflow module:

  1. On the Steps page of one of the workflow or workflow module configuration wizards, click Add > Execute Embedded Script.
  2. In the details section, change the step's default name of "Execute Embedded Script" if you want.
  3. For Step Execution, indicate whether you want the step to execute automatically (the default behavior) or execute only when specific conditions are met. To make a step conditional, select Execute when conditions are met, then click Edit and define the condition. See Making Workflow Steps Conditional for more details.
  4. For Timeout, adjust the default timeout, if required. The step will fail if it can't be completed within the given time.
  5. For Script Output, specify whether the value returned by the script should be captured as a comment, thus determining whether the request is approved or rejected. When you capture script output as comment, you can use script output as the input to a subsequent Set Custom Attribute step. See Using Script Output as Input to a Workflow Step. Scripts in approval workflows can also set deployment parameters.
  6. For Script Fails, indicate what to do if the script fails:
    • mark the step as failed and not proceed
    • or, skip the step and go to the next step in the workflow

    Note: If a retry step is added to this execute script step, and it's set to Mark as Failed, the workflow will retry the failed step. See Adding Retry Steps to Workflows for details.

  7. For Credentials, choose or add guest OS credentials that are required to run the script. See Managing Credentials for more information.

    Tip: Instead of hard-coding the credentials, you can use environment variables to provide the credentials to the script when it executes. For more information, see Selected credential.

    Best Practice: If you have selected Capture Script Output as Comment, don't use echoing in your script to avoid exposing credentials in the workflow comments. For example, when using a cmd.exe script file, you would use "@echo off" in the script contents.

  8. For Executable, 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".

    Note: 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 Setting system properties in Commander for details on how to modify system properties through Commander.

  9. For Script Contents, enter the body of the script file that will be executed.
  10. For Script Arguments, enter any arguments that you want to postfix to the generated script file.
  11. If required, continue to add steps, and when you've finished, click Next.
  12. Continue to configure the workflow or workflow module, as required.