Step Library

The Step Library contains JavaScript based workflow steps. They can be used as steps inside Workflows.

Step Library steps have access to an Avantra JavaScript API that is dependent on the monitored system the step is executed on. More information about the available APIs can be found in our API documentation.

Steps

Creating a new step is easily accomplished through the Step Library.

Procedure: Creating a new step

  1. Choose Automation  Step Library.

  2. Click the New button.

  3. Enter a name and namespace to name the step

    When naming a Step Library step, it must have a unique name and namespace combination.

  4. Optionally, set a customer that to further group this step in the Step Library.

  5. Click the Create button to create the step.

The configuration of a step consists of a JavaScript editor on the left side and configuration properties on the right. In these configuration properties, you can change basic settings, add and remove parameters, edit documentation and test the step on a running agent depending on your requirements.

The subsequent sections detail how to configure a step.

Parameters

A step can have input and output parameters. Input parameters allow the workflow to pass information to the step to control its processing. This can either be from the input parameters to the workflow itself or the output parameters from a previous step in the workflow.

Step parameters can be configured in the Parameters tab.

Every step has some built-in parameters used by the workflow engine itself and to report messages and success of the execution of the step.

  • Input

    • systemId: the monitored system the step should run on (this cannot be accessed in JavaScript)

    • timeout: the time in seconds to wait before terminating a long running step (this cannot be access in JavaScript)

  • Output

    • success: true, if step was executed successful

    • message: short message of step execution (shown in the execution log)

    • details: detailed message of step execution (shown in the detailed execution log)

These built-in parameters are pre-defined and don’t need to be added again manually in the UI. However custom parameters can be added to meet the requirements of the step

Procedure: Adding a parameter

  1. Choose Automation  Step Library.

  2. Double click on the required Step Library step.

  3. Click the Parameters tab.

  4. Add a new row by selecting the + in the top right of the parameter table

  5. Enter a unique name for the parameter. We recommend parameters are named in camelCase and start with a letter.

  6. Choose either Input, Input (Mandatory) or Output for Parameter Type to match this parameters intended use case.

  7. Choose an appropriate Parameter Type from the Parameter Types list.

    Not all parameter types are available for Step Library step usage currently. Please refer to the documentation on Parameter Types

  8. Optionally, enter a Default Value and Documentation (hint) to make the step easier to understand for future workflow builders.

For more information about usage of parameters in JavaScript, please refer to our API documentation.

Documentation

The Documentation tab allows the step builder to provide more information on the usage of the step, its intended inputs and restrictions and any other helpful information that will allow future workflow builders to understand the step better.

The documentation is rendered in the UI as part of the process of choosing a step when creating Workflows and when editing an existing step.

Test

The Test tab can be used to execute only this step on a running agent to test its output as part of the development process.

Procedure: Testing a step

  1. Choose Automation  Step Library.

  2. Double click on the required Step Library step.

  3. Click the Test tab.

  4. All inputs for the step are listed (including the built-in inputs) and mandatory values need to be entered before the step can be executed. The built-in parameter systemId is mandatory and allows the tester to choose which agent to test the step on.

  5. Click the Run script or Debug script buttons to start executing the step.

    To enable debugging on an agent, the value JS_DEBUG=on must be added to the AgentEnvironment monitoring parameter.

    If the Debug script button is used, a URL is displayed that must be opened in a Chromium based browser to step through the script code.

    Once the code has executed, or debugging is complete, the output parameters can be seen in the result text field.

Import and export

To share steps between systems the export and import buttons can be used.

Export

Select all steps that should be included into the export and click on Export. Specify a filename and click on Export. After that the export file is created and is downloaded.

File format

See Workflow export

Import

To start the import wizard click on Import.