Scripts make it possible to calculate values, exchange data between different tasks in the process and to execute specific operations using SOAP calls.
Scripts are ubiquitous in a workflow diagram:
- All activities have initialization scripts. An initialization script is executed when the activity is activated and can be used to initialize variables and to modify the properties.
- instance : Represents the workflow being executed. The schema of this object is xtk:workflow .
- task : Represents the tasks being executed. The schema of this object is xtk:workflowTask .
- event : Represents the events that activated the task being executed. The schema of this object is xtk:workflowEvent . This object is not initialized for AND-join type activities that have been activated from multiple transitions.
- events : Represents the list of events which activated the current task. The schema of this object is xtk:workflowEvent . This table usually contains one element but may contain several for AND-join type activities which have been activated based on several transitions.
- activity : Represents the model of the task being executed. The schema of this object depends on the activity type. This object can be modified by the initialization script, in other scripts, modifications with have indeterminable effects.
The properties available for these objects are can be viewed in a drop-down list by clicking the button at the right of the script toolbar.
The properties of these objects are read-only except for the sub-properties of the vars property.
Most of these properties are only updated after executing an elementary task or when the instance is passivated. The values that are read do not necessarily match the current status but the previous status.
logInfo("Label: " + instance.label) logInfo("Start date: " + task.creationDate)
The logInfo(message) function inserts a message into the log.
Click OK to close the creation wizard, then start the workflow using the action buttons situated at the top right of the list of workflows. At the end of execution, consult the log. You should see two messages corresponding to the script: one displays the label of the workflow, the other displays the date that the script was activated.
The instance variables ( instance.vars.xxx ) are comparable to global variables. They are shared by all activities.
The task variables ( task.vars.xxx ) are comparable to local variables. They are only used by the current task. These variables are used by persistent activities to keep data and are sometimes used to exchange data between the different scripts of a same activity.
The event variables ( vars.xxx ) enable the exchange of data between the elementary tasks of a workflow process. These variables are passed by the task that activated the task in progress. It is possible to modify them and to define new ones. They are then passed to the following activities.
In the case of AND-join type activities, the variables are merged but if a same variable is defined twice, there is a conflict and the value remains undetermined.
Event are the most often used variables, and they should be used in preference to instance variables.
Certain event variables are modified or read by the various activities. These are all string-type variables. For example, an export sets the vars.filename variable with the full name of the file that has just been exported. All these read or modified variables are documented in About activities , in the sections Input parameters and Output parameters of the activities.
Additional worklow use cases are available in this section .
In this example, an instance variable is used to compute dynamically the split percentage to apply on a population.
- Create a workflow and add a Start activity.
- Add a Query activity and target recipients according to your needs.
- Add a Split activity and configure it to perform a random sampling of the incoming population. The sampling percentage can be anything of your choice. It is set to 50% in this example.It is this percentage which is updated dynamically thanks to the instance variable defined previously.
- Inside the Initialization script section of the Advanced tab of the Split activity, define a JS condition. The JS condition selects the random sampling percentage of the first transition coming out of the Split activity and updates it to a value set by the instance variable created previously.
activity.transitions.extractOutput.limiter.percent = instance.vars.segmentpercent;
- Make sure that the complement is generated in a separate transition of the Split activity and add End activities after each of the outbound transitions.
- Save and execute the workflow. The dynamic sampling gets applied according to the instance variable.
instance.vars.foo = "bar1" vars.foo = "bar2" task.vars.foo = "bar3"
- Add the following script to the initialization script of the End activity:
logInfo("instance.vars.foo = " + instance.vars.foo) logInfo("vars.foo = " + vars.foo) logInfo("task.vars.foo = " + task.vars.foo)
- Start the workflow, and then look at the log.
Workflow finished task.vars.foo = undefined vars.foo = bar2 instance.vars.foo = bar1 Starting workflow (operator 'admin')
Calling an instance variable in a query
Once you have specified an instance variable in an activity, you can re-use it in a workflow query.
Thus, to call a variable instance.vars.xxx = "yyy" in a filter, enter $(instance/vars/xxx) .
- Create a query whose targeting and filtering dimensions are the recipients. In the conditions, specify that you would like to find all the recipients that were sent the delivery specified by the variable.As a reminder, this information is stored in the delivery logs.To reference the instance variable in the Value column, enter $(instance/vars/@deliveryIN) .The workflow will return the recipients of the DM42 delivery.
logInfo(message) was detailed in the above examples. This function adds an information message to the journal.
logError(message) adds an error message to the log. The script interrupts its execution and the workflow changes to error status (by default, the instance will be paused).
Under certain conditions, you can modify a property of an activity at the time of execution.
For other properties, however, you must use the initialization script. This script is evaluated before the task is executed. The activity variable references the activity corresponding to the task. The properties of this activity can be modified and will affect this task only.