A process defines how the system should respond to a request, and is responsible for checking the authority and validity of incoming requests. However, many solutions also need control over what requests should come under which conditions, i.e. to control what actions should be offered to the user.
Status rules provide a compact way of translating a status, i.e. a link to one of a defined set of target nodes, into a list of actions that could be offered to the user.
The Status Rules type provides a way of defining status rules. This contains a Status rules definition, of the format:
[
{
"comment":comment,
"role":role,
"status":status,
"action":action
}, ...
]
| comment |
An optional comment. |
| role |
A string which represents a logical role in the process, such as "administrator" or "contributor". More than one role can be specified by passing an array of strings. role is optional, and defaults to the empty string. |
| status |
A binding reference that identifies a status node. More than one status can be specified by passing an array of status references. A status of undefined or "*" means "all statuses". The actions are added to all statuses that are identified in other rules, and a status of "*" is made available for use with unlisted statuses. A status that starts with ! means "all statuses except the given status". "!null" can be used to indicate that the rule should not apply to the null status. |
| action |
A JavaScript object that specifies an available action. More than one action can be specified by passing an array of objects. object properties of the form "${..}" are translated to node version references using the bindings. In most cases, the action items do themselves contain an action property, so a more complete example could be something like: [ |
The rules are collated so that for each status there is a lookup of actions per role. For example, in a data gathering solution, an Open status might have rules like the following:
{
"administrator": [
{
"action": "resendAssignment",
"caption": "Resend"
},
{
"action": "cancelAssignment",
"caption": "Cancel"
}
],
"contributor": [
{
"action": "submitAssignment",
"caption": "Submit"
},
{
"action": "referAssignment",
"caption": "Refer"
}
]
}These are then stored in two ways:
- All of the action lookups are stored in a Status rules field, indexed by status reference. If the undefined role, the "*" role or any ! roles have been used, then there will also be an entry for "*", to be used on statuses not listed in the rules.
- The action lookup for each status is stored using the status itself as the field.
The actions for a status can then be looked up in one of two ways:
-
From the Status rules field, i.e.
JSON.parse(statusRules.getValue(mtStatusRules))[role]
Or, if there is a possibility of statuses not defined in the rules
var statusRules = JSON.parse(statusRules.getValue(mtStatusRules)); var rulesForStatus = statusRules[status.getNodeReference()] || statusRules['*']; var rulesForRole = rulesForStatus[role] || [];
-
From the status field itself, i.e.
JSON.parse(statusRules.getValue(status))[role]
The status rules can be held on any accessible node. In many cases, it is useful to associate them with the process, by inheriting from them in the process node itself. In other cases, it is useful to hold them separately, or to hold them separately and default them on the process itself.
Null status
A status of null is allowed.
In the Status rules structure, this is held using a reference of "null".
An action lookup using Null (system.NULL) as the field is created.
The null status is different from omitting status. Omitting a status means "any status", or more precisely any status mentioned elsewhere in the status rules, including null if that is mentioned. A null status means "no status".
Extends
The Extends list allows a set of status rules to be extended. The extension works on the Status rules definition field, not on the Status rules field.
The extension follows the approach convention described in the Object List Merge Script. In short, using extension involves adding a reference property to rules in the base definition. The base definition can then be extended by using a position property on rules in the extending definition. The position property is a reference preceded by a position operator. The reference is used to identify a previously-defined rule, the position rule. Five operators are supported:
- @ – replace the position rule with this rule.
- + – extend this rule's values into the position rule.
- < – precede the position rule with this rule.
- > – follow the position rule with this rule.
- ! – delete the position rule.
See Object List Merge Script for more details of the merge logic.
The + operator adds new items to the role and status lists if they are not already there. It merges the action lists using default Object List Merge Script processing, allowing individual actions to be tailored provided that they have been given a reference. The + operator in the actions performs a standard JavaScript object extends process.
Status bindings from the extend list are copied over, but can be overridden by the extending list.
The extension rules are not applied if there is nothing in the Extends list, i.e. you cannot use position operators to modify the list you have written.