Introduction

• Order Variables can be used to parameterize workflows and jobs.

Scope

• Order Variables are declared with a Workflow.

Feature Video

This video explains how to parameterize workflows and pass variables to jobs in a workflow.

Declaring Variables

Download example (upload .json): pdwVariablesDeclared.workflow.json

The JS7 - Workflow Editor offers the Image Removed icon with the property editor to declare variables:

Image Removed 

A popup window opens that offers to declare variables:

Image Removed

Explanations:

allows variables to be declared. Clicking in the workflow editor panel will display the workflow properties where variables can be added:

Image Added

Explanation:

• Order variables Variables are declared by specifying a name and data type.
  • If no default value is added then the Variable order variable is mandatory, i.e. any Orders have an order has to specify a value for the Variablevariable.
  • If a default value is added then
    • the
    Variable
    • order variable is optional, i.e.
    Orders
    • orders can specify a value and otherwise the default value
    is used.
• Any number of Variables can be declared.

Using Variables

• • • will be used.
    • the final data type can be used that prevents the variable from being modified after the point in time of submission of an order.
  • Default values accept constant values and JS7 - Expressions for Variables.
• Any number of order variables can be declared.

For order variables of data type "String" the workflow editor offers the following operations from the Image Added icons:

• The Image Addedicon invokes facet entry mode.
• The Image Added icon invokes the list entry mode.
• The Image Added icon invokes the editor entry mode for values of variables

Editor Entry Mode

Clicking the Image Added icon brings up a popup window that offers more space for character input to values of variables:

Image Added

The window size will adjust automatically if more characters are entered.

• The Image Added icon can be used to maximize the window size.
• The Image Added icon can be used to change the window length.

List Entry Mode

The Image Added icon invokes the list editor that is used to compile a list of values which a user can select from when adding an order to the workflow.

Image Added

In the Workflows view when an order is added users select from the list of values like this:

Image Added

Facet Entry Mode

The Image Addedicon invokes the facet editor. Facets are regular expressions that are used to check user input to match a given pattern.

Image Added

Regular expressions can be complex and lengthy. The facet editor offers the Add from Favorites link to select values from JS7 - Inventory Favorites.

In the Workflows view when an order is added user input is checked like this:

• Input that does not match the regular expression is denied and the order cannot be submitted.
• An information icon displays a tooltip with the message that has been added to the facet.
  
  

Image Added 

Using Order Variables

Order variables Variables can be used in a number of places:

• to populate environment variables that are used in job scriptsshell jobs,
• to populate node arguments,
• to be evaluated with by an expression of in a JS7 - If Instruction.

Using Order Variables in Shell Jobs

Shell jobs can access Variables by use of environment variables to access order variables.

Mapping Order Variables to Environment Variables

A mapping is performed with the "Environment Variables" sub-tab of the Job job property editor:

ExplanationsExplanation:

• The property editor suggests to use using the names of Variables order variables for environment variables.
  • Environment variable names are automatically converted to uppercase letterscreated with the given spelling. In Unix environment variables are case-sensitive, in Windows they are case-insensitive.
• Similarly the values of Variables order variables are suggested with a $ prefixing the Variable name of the variable.
  • Consider Note that only names of existing Variables order variables can be used as the value for an environment variable.
• In addition, expressions can be used for order variables - for details see:
  • JS7 - Expressions for Variables
  • JS7 - Assignment of Variables

Using Environment Variables

...

in Job Scripts

Environment variables can be used with Job scripts considering in job scripts according to the syntax of the respective operating system that the Job job is executed for:

• for Windows use: %VAR_STRING%
• For Unix use
  • $VAR_STRING
  • ${VAR_STRING}

Image Modified

Using Node Arguments

Node Arguments are typically are used in a situation when the same job occurs more than once in a Workflowworkflow. The basic assumption is that the Job job will make use of the same Variables that variables which should use carry different values per at each node in which the job is used.

• Note that node arguments cannot be modified dynamically - which is why they are called arguments, not variables. 
• Node arguments are available for mapping to environment variables in a similar manner to order variables.

Creating Order Variables

Order variables can be created dynamically from shell jobs.

• The job script can append a key/value pair to a temporary file indicated with the JS7_RETURN_VALUES environment variable.
• The JS7 Agent will pick up the temporary file after execution of the shell job and will use the file's entries to create order variables for subsequent instructions and jobs in the workflow.
• This mechanism is used to create new order variables from Shell Jobs. It cannot be used to modify existing order variables declared with a workflow. Order variables that are not declared but created on-the-fly by shell jobs can be updated by subsequent shell jobs.

SOME_VARIABLE=some value
echo "myVar=$SOME_VARIABLE" >> $JS7_RETURN_VALUES

set SOME_VARIABLE=some value
echo myVar=%SOME_VARIABLE% >> %JS7_RETURN_VALUES%

Explanation:

• Both examples assign a value to an environment variable SOME_VARIABLE that is local to the job.
• The key/value pair myVar=.... is appended to the temporary file indicated by the JS7_RETURN_VALUES environment variable.
  • This assignment makes use of the value stored in the SOME_VARIABLE environment variable.
  • This assignment could also use a constant value instead of using SOME_VARIABLE.

Built-in Variables

Built-in variables are available at the following scopes:

Workflow

• $js7WorkflowPath
  • The unique name of a workflow. Note that in a workflow the name does not include the folder location.
• $js7WorkflowPosition
  • The position of an order in the workflow.
• $js7Label
  • The label of the current instruction for which an order is executed.
• $js7OrderId
  • The order identifier.
• $js7ControllerId
  • The Controller's identifier as specified during installation.

Job

• $js7JobName
  • The name of the current job for which an order is executed.
• $js7JobExecutionCount
  • A counter for the number of times that the same job node is executed within a workflow, e.g. if used

...

• • with the JS7 - Retry Instruction.
• $js7EpochMilli
  • The number of milliseconds since January 1^st 1970 UTC.
• $returnCode
  • The numeric exit code of the current job for which an order is executed.