Process definition

Each process is defined as a JSON structure. At a high level it defines an array of actions or tasks, which together form a process.

The template has the following format:

[
  {
    "name": "action name",
    "script": "binding ref",
    "comment": "optional comment",
    "next": next clause,
    "config": {
      : any config
    }
  },
  ... another action
]

name	Identifies the action.
script	Binding reference for script that fulfils the action, known as a task script. Defaults to the name. May be null, which indicates that no script should be run.
comment	Optional comment, shown on documentation.
next	The next clause identifies what should happen if the script completes successfully. It can be: true – run the next action. This is the default. false – exit the process. The name of another action which should be run. A lookup of states and actions. In this, the property names are the states, and the property value can be: true – run the next action. This is the default. false – exit the process. The name of another action which should be run. Use a state of "" to specify a default. If not given, a default of true is assumed. Exampe 1: Run the next step. This is the default* "next": true Example 2: Exit the process "next": false Example 3: Jump to "Other action" "next": "Other action" Example 4: If the state is "a", jump to action_a, if it is "x", end the process, otherwise jump to action_b "next": { "a": "action_a", "x": false, "*": "action_b }
config	The config object is used to configure the called script. This allows generic scripts to be included in the process and then configured for different role. The config object can be in any format. If any of the properties are of the form "${reference}", they are replaced with node bound to reference. This binding takes place as the process definition is derived, allowing bindings to be overridden in extended processes. The action property of the config object is used when calling sub processes (see below).

The Process type provides a documentation tab which summarises the template definition.

How the definition is interpreted

The process acts as a script.

During script initialisation, an empty object is created and stored as the application attribute "data".

If the script is run with an action parameter, control is passed to the action identified by the action parameter. If the action parameter is passed and no action is found, an error is raised (but see below about @unknown and optional actions). If there is no action parameter, control is passed to the first action. The script bound to the action name in the bindings is called, in the following way:

The application attribute "config" is set to the config object of the action definition, or removed if there is none.
The application attribute "process" is set the the process node.
The application attribute "state" is removed.
The script is called, using application.call(). This preserves the application attributes.
If the script returns an error, end the process.
Retrieve the application attribute "state".
Use the combination of the name of the action and the state to look up the next action to be invoked.
If an action is defined for the combination of predecessor and state, look for a default for the predecessor.
If no action is defined, proceed to the next action.

Some action names have a special meaning:

@start – run at the start of the process, before the requested action.
@end – run at the end of the process, assuming there is no error.
@default – run if an action parameter is not passed, rather than running the first action.
@unknown - run if an action parameter is passed and not otherwise declared. If you use @default and not @unknown, you will get an error for an unknown action. If you use @unknown and not @default, if no action is passed the first step will be run.
@error – run if there is an error. @end is not run after @error. The @error action must reset the error to run any further actions.

If the requested action name ends with a "?" it is considered an optional action. The "?" is removed, but no error is raised if the action cannot be found. Passing in an action of "run?" means invoke the "run" action, but do nothing if there is no run action. @start, @end, @default and @unknown actions are not run if the optional action is not found.

Other action names are not interpreted by the process, but should only be used with specific meanings:

@init – run when the process is first instantiated.
@display – used to display the thing
@consume – consume a published message if required, in a publish/subscribe arrangement. Consumption may be optional, so the action is often passed in as "@consume?".

Task script requirements

The scripts called from the process (the task scripts) can access the request sent to the process and can set a response.

They may also:

Read configuration from the application attribute "config".
Identify the process from application attribute "process",
Read the action definition from the application attribute "action". Use application.get("action").name to get the name of the action.
Read and write process data from the application attribute "data".
Set an outcome in the application attribute "state".

Using a process

A process is just a script, and it can be run, executed, included or called like any other script.

The request action is identified by the request parameter "action".

Extending processes

Processes can be extended as follows:

By inheriting from a process template and overriding the bindings, to change action scripts.
By creating a new process template and listing process templates on which it is based in the Extends list. These are applied in turn, each one overriding any like-named actions and bindings. The bindings and process definition for the process template itself override all the ones it extends.

Status rules are extended in a similar way. Overrides to the rules are applied during conversion from the status rule definition to the status rules, with later-defined status rules overriding earlier ones.