Task Rules

The OpenGroupware Coils Logic layer provides a simple rule system to help drive tasks along a user work-flow and to facilitate consistency for tasks of a specific type. Use of rules can help simply the logic of client applications and ensure consistent chains of events occur when tasks are modified by multiple applications.

Task rules are stored in the “Rules/Tasks” folder of project 7,000 as YAML documents. These files can be created, edited, and deleted via WebDAV at /dev/Administration/Rules/Tasks. The name of a rule-set is the kind string of the task with a .yaml extension. For example the rules defined in the YAML document presented as /dav/Administration/Rules/Tasks/myExample.yaml will be processed by any update to or action on a task with a kind of myExample.

Each rule is a dictionary of two keys: match and apply. The value of match is a list of criteria which is used to determine if the rule applies to the task, if the rule matches the task the values specified in the apply list are applied to the task. A rule may optionally have keys name, description, and action. If defined the description value should be a human readable explanation of the purpose and intent of the rule; this value may be multi-line text as supported by the YAML parser. The value of the name key is used then the application of the rule is recorded in the task's audit log and should be a simple single-line string; when a rule without a name is applied to a task the audit log will refer to the rule as unnnamed.

The criteria of match are dictionaries of three keys: key, value, expression. Each match criteria compares the attribute of the task specified by key with the provided value using the requested expression. The expression key is optional; if not provided the default expression is equality. If the value of key begins with the curly brace character [“{“] the key is assumed to indicate an object property in the form of "{namespace}attribute"; as object property values are typed the comparison is made against value as the persisted type. A comparison against an object property which does not exist is always false regardless of expression. All match criteria must evaluate to true for the rule to apply to the task; the server ceases to process criteria as soon as any criteria evaluates to false.

If the expression value is any of other than a supported types an exception will be raised – this will cause the update to or action upon the task to fail. All rules specified in a rule set must be syntactically valid.

The apply section of each rule which matches the task will be used to set the specified values of the task. If multiple rules apply each will be processed in turn; there is no specified order by which rules are processed so care should be take to avoid potentially overlapping rules.

The value of apply must be a dictionary. The keys of the dictionary identify the attributes of the task5 to which the value will be copied, overwriting the value of the task attributes. A key which begins with the curly brace [“{“] character is assumed to name an object property with the form of “{namespace}attribute”; the object property will persist both the type and value of the value assigned. For task attributes the value assigned must correspond with the type of the attribute6 [in the ORM].

- apply:
  - {key: keywords, value: it-task}
  - {key: "{example.com}testProp", value: fred123}
  match:
  - {key: executor_id, expression: MEMBEROF, value: 11530}
  name: myExampleRule
  description: set keywords and object property if the executor is a member of team 11530

When a value is copied to a task attribute as the application of a rule a 10_commented audit entry is created on the task describing what attribute was changed and the name of the rule which was applied; if a rule has no name the change is recorded as from rule unnamed.

Note that task rules are applied only upon a task action – such as task creation, update, accept, comment, etc... Direct modification of an object property will not invoke the processing of task rules, nor will adding or removing object links, or uploading or deletion of attachments.

Task rule-sets can be verified using the toolbox protocol [see documentation of the toolbox protocol in WMOGAG].

- apply:
  - {key: "{www.example.com/task}autoArchived", value: 'YES'}
  match:
  - {key: owner_id, expression: MEMBEROF, value: 955840}
  - {key: state, expression: EQUALS, value: 00_created}
  name: archiveMVPskuAdd
  description: Automatically archive SKU adds from MVP employees
  action: archive

A task rule which matches tasks in the 00_created state whose owner is a member of the team OGo#955840. An object property will be created on matching tasks and the tasks will be automatically archived.

A task rules may also contain an action value which must specify a valid task action: reject, accept, comment, done, reactivate, or archive. If the rule matches the task this action will be performed on the task with a comment indicating the name of the rule which specified the action occur; if an action is performed by a rule not having a name the rule invocation will be recorded as unnamed. Additional rules will not be applied to the task as a result of rule driven actions; this prevents creating a rule loop.

A rule file may contain as many rules as necessary.

- apply:
  ...
  match:
  ...
  name: rule1
- apply:
  ...
  match:
  ...
  name: rule2
- apply:
  ...
  match:
  ...
  name: rule3

Order of operations when planning task rules is important. Whatever operation is performed on the task is performed first [create, update, or action], then rules are checked. Each rule that matches will apply the specified values and then the specified action, if any, will be performed – after the values of the task have been updated by the rule. As previously stated multiple rules from a rule-set may apply to a task, however there is no order to how rules are processed.