User Task Hooks

A user-task could have candidate users/roles/groups as well as due date and followup date. Each of these can be configured as expressions. Workflow engine evaluates expressions and populates the actual values on the created Task record.

Sometimes, a more complex logic is required to arrive at these values. For example, assign from a pool of users and make sure the assignee is not on leave. Due date is not 3 calendar days but 3 working days. So, on a Friday the task due date is not Monday but Wednesday. And if Tuesday is a holiday then the due date is further pushed to Thursday.

Such complex calculations can not be configured in the workflow diagram but are practical reality. To support this, oeWorkflow engine allows defining pre-creation and pre-completion hooks on user-task.

Pre Creation, Pre Completion and Post Completion hook functions provide a way for application to insert a custom logic during task creation and completion phase.

Specifying hook functions in modeler

User Task allows specifying names of functions to invoke while creating and completing the task.

Specifying Hooks in Modeler

Defining and loading addon functions

These hook functions can be defined in a node module and be loaded during startup.

In the following example, we populate the due-date based on the due-date specified in task definition and calendar from process variables. The before complete function errors the task completion if the comments are not provided.

module.exports = {
  computeAssigneeDetails: function (options, taskDef, taskData, cb) {
    let dueDate = Calendar.getDate(taskDef.dueDate, this._processVariables.calendar);
    taskData.dueDate = dueDate;
    return cb(null, taskData);
  },
  validationCompletionData: function (options, payload, taskInstance, taskDef, cb) {
    let err = null;
    if (!payload.__comments__) {
      err = new Error('Comments must be provided');
      err.statusCode = err.status = 422;
      err.code = 'INVALID_DATA';
    }
    return cb(err);
  },
  resetUserContext: function(options, task, cb){
    let newOptions = Object.assign({}, options);
    ... acquire token for system process ...
    ... and update newOptions ... 
    cb(null, newOptions, task);
  }

}

Notice the usage this._processVariables. The hook functions are invoked with Process Instance as this.

Specify workflow.addonModule property in the application’s config.json file as below for addon module to be loaded.

  ...
  "workflow":{
    "addonModule": "utils/addon-functions",
    ...
  },
  ...

Here utils/addon-functions is the path (relative to applications root directory) to module containing hook functions.

If workflow.addonModule is specified, it must exist and be found. If a wrong value is specified or module is not readable the application boot throws error and stops.

Global defaults

If a common hook needs to be invoked for all user tasks, define a functions with name defaultTaskCreationHook (for pre create hook) in the addon module. If defined, this function is invoked for all user-tasks where Creation Hook is not specified in the modeler.

Similarly, if defaultTaskCompletionHook function is defined in addon module, it is invoked (as pre-completion hook) for all user-tasks where Completion Hook is not specified in the modeler.

Hook Signatures

  • Creation Hook

    • function creationHook(taskDef, taskData, cb)
    • taskDef : Task Definition Data (as defined in the modeler)
    • taskData : Evaluated data (define/override properties on this object)
    • cb: Pass modified task-data as second argument. If any error is passed as first argument, it is logged but does not cause the workflow to stop.
  • Completion Hook

    • function completion(payload, taskInstance, taskDef, cb)
    • payload : Payload passed to complete API.
    • taskInstance : The task being completed
    • taskDef : Task Definition Data (as defined in the modeler)
    • cb: Callback function. If error is passed the completion API will stop and return the error. Otherwise rest of the completion flow would continue.