Using scripts in workflows

Scripts are a powerful tool for implementing customer-specific requests within the FirstSpirit workflows.

Within workflows, scripts can only be linked to activities. An activity can either be run manually by a user or automatically by a script (see the Activity page).

The result of an activity is always related to the instance of a workflow. It either involves a change of state to one of the subsequent states accessible to the activity or the retention of the current state (corresponds to the “Cancel” semantics in the activity dialog). This also applies to scripts that are coupled to the activity. This means that the script “itself” is responsible for ensuring that a transition to the next state is executed.

See Chapter Tutorials/Workflows/Using scripts for some examples of how to use scripts in workflows.

In principle, the activities connected to the script can be defined in the workflow model as either “manual” or “automatic” – in both cases, it can make sense to use a script.

If scripts are used within workflows, the editorial permissions are NOT evaluated automatically (e.g. during release). These permissions have to be suitably linked to the transition permissions within the workflow.

Automatic activities and scripts

Automatic activities do not wait for user interaction and are performed as soon as one of the states upstream in the model is reached (i.e. the action is triggered by the system and not by the user). Thus, an automatic action (and a connected script along with it) is performed directly after reaching a state.

Automatic actions can result in potentially endless loops. This situation is detected by the FirstSpirit workflow interpreter; execution of the corresponding workflow instance is terminated and an error message appears. The use of automatic activities is limited to 16 activities in succession at maximum.

Manual activities and scripts

In the case of manual activities, the action is initiated by a user. If no script is available, then the user is shown the standard form for workflows with all the transitions that he or she is allowed to execute (“Activity dialog”). As soon as the action is assigned a script, this dialog is no longer displayed automatically. If the activity dialog is to be shown to the user, then this has to be achieved via the script.

Methods for a workflow script context

Transition showActionDialog();

Task: Display of the activity dialog (usually only relevant for manual actions). The transition selected by the user is returned as a “Transition” object. Attention: The actual transition itself is NOT executed.
(For an example, see the following page: Outputting messages in workflows).

void doTransition(firstspirit.workflow.model.Transition transition)

Task: Execution of the specified transition. This can, for example, be the transition selected by the user or another one that is available (and permitted) within this action. If the selected transition is not permitted, an error message is output.
(For an example, see the following page: Outputting messages in workflows.)

void doTransition(String transitionName)

Task: Execution of the transition indicated by name. If the transition in the model is not assigned a name, then a name is automatically generated in the form “->” + “Name of the target state”, which can be specified here.
(For an example, see the following page: Persistent content within workflows.)

Transition[] getTransitions()

Task: Determines the set of all transitions that are available to the user in the current state.
(For an example, see the following page: Outputting messages in workflows.)

Data getData();

Task: A workflow model can be assigned a form. This form is shown to the editor in the activity dialog, who can enter or change data. Via this method, the script has access to the content of the form and is also able to make changes, if necessary.

Map getSession()

Task: Each instance of a workflow is assigned (alongside the form) a special data structure (Java map) which allows a script to save its own instance state and change it if necessary. Because this state is part of a workflow instance, it is available to all scripts that are run during the life cycle of the instance. As a result, this method allows (instance-related data) to be exchanged between scripts.
(For an example, see the following page: Persistent content within workflows.)