Workflow Tasks

A Task is an atomic activity in the workflow process that is performed by user or another application.

Script Task

A Script Task defines a custom task logic provided as a script snippet. The implementer defines a script in javascript language that the engine will interpret and execute. When the task is ready to start, the engine will execute the script. On completion of script, the element execution completes and results are passed on to the next element in the flow.

Example: In the below example a script task is being utilized to calculate the interest.

Image

Settings

  • Script Format : This parameter defines the format of the script that needs to be executed. Currently only Javascript is supported.
  • Script Type : This parameter defines the script type. Currently only Inline Script is supported.
  • Script : Provide the script that needs to be executed here. Following script text is specified in the example above.
var p = msg.principal;
var r = msg.interestRate;
var t = msg.period;
var interest = p*r*t/100;
setPV("simpleInterest", interest);
msg.simpleInterest = interest;
sendMsg(msg);
  • Result Variable : When the script-type is Expression the result of evaluating the expression is stored in the variable specified.

This functionality is not supported currently as only Inline Script type is implemented.

Allowed operations

The script defined in script task is executed inside a sandbox and only limited set of functions are available.

  • Process Variables are process level variables that are available throughout the process (including inside the subprocess).
  • A task node can receive message from previous node and can also pass message to next node.
  • While process variables pass through each node cumulatively, the message is passed only from one node to next and is discarded after next node execution completes, unless forwarded explicitly by current node.
  • pv(<variable name>) : Access process variable value by name
  • setPV(<variable name>, <value>) : Set or modify the process variable value. Note that the consolidated modifications are reflected in the process variables only when script evaluation completes. So setting a process variable and accessing it immediately in same script would not work. Instead, for such cases you should hold the value in a javascript variable, modify and use at multiple places as normal.
  • msg : The message object passed to this script node from previous node can be accessed via msg variable.
  • sendMsg(<msg-object>) : Pass message to the next node in workflow.
  • getEnv(<env-var>) : Get value for an environment variable.
  • options : The options object can be accessed via options variable.
  • _log(<log message>): logs the passed log-message to engines log stream.
  • _instance : In case of Maker-Checker flow the model instance can be manipulated via set of functions on _instance object.
    • _instance.setAttribute(key, val)
    • _instance.unsetAttribute(key)
    • _instance.setAttributes(Obj) : Set keys and corresponding values on model instance.
    • _instance.unsetAttributes(Obj) : Unset keys from model instance where value is true.
    • _instance.toObject() : Returns a copy of model instance with any set/unset attributes applied.

Example

var amount = pv('amount');
setPV('name', 'John');
var period = msg.period;
var currentUser = options.ctx.username;

_instance.setAttribute('cashback', 50);
_instance.unsetAttribute('cashback');
_instance.setAttributes({cashback: 50});
_instance.unsetAttributes({cashback: true});

sendMsg({status: 'success', data: _instance.toObject()});

Service Task

A Service Task simulates invoking an API. It allows invoking a remote REST end-point or making a local method call on loopback model.

Image

Settings

  • Implementation : This parameter defines implementation type of service task. Valid values are REST Connector, OE Connector and Finalize Transaction Connector

    • REST Connector provides an interface to make REST calls (GET/PUT/POST). Additional details must be provided on separate tab.
    • OE Connector provides an interface to make direct method calls on oeCloud models.
    • Finalize Transaction Connector provides a way to automatically apply a record approval/rejection in a maker-checker scenario. E.g. auto approve/reject if amount is less/more than certain limit. In a multi-checker scenario, reject the change-request if first checker rejects.

REST Connector

  • URL specifies the URL to make REST call. URL construct accepts dollar expressions e.g. ${getEnv('LOANS_API')}/Accruals/${pv('loanId')}

  • Method : HTTP method for rest call (GET/POST/PUT). dollar expressions are accepted.

  • Data : Payload for the REST call(accepts only json). Specify dynamic values as direct expressions e.g.

{	
	status: msg.status, 
	loanId: pv('loanId')}
}
  • Headers : HTTP headers to set in REST call (accepts only json). Specify dynamic values as direct expressions e.g.
{	
	Authorization: options.accessToken
}
  • Number of Retries: Number of times to retry if the REST call fails. Default value is 1
  • Timeout : Duration in milliseconds to wait for the response.

Image

URL and Method are evaluated as dollar-expression, so dynamic variables are allowed while defining URL. A dynamic variable VAR stored in Process Variables should be written as ${pv("VAR")} while variable VAR passed as message to the Service Node should be accesed using ${msg.VAR} in the URL for it to be evaluated. To use Authentication Token in URL one can directly use ${accessToken}.

Data and Header fields are evaluated as simple js expression and any dynamic value from process variables or message object should be refered as it is without ${…}

{
  "workflowInstanceId" : pv("_workflowInstanceId"),
  "comments" : msg.text,
  "status" : "approved"
}
  • SSL Context: If the URL is https, then rest connector allows you to configure SSL certificates. SSL certificates should be defined in app’s config.json as shown below
  {
    "SSLContexts": {
         "Context1": {
            "certificateAuthority": "certificatestore.pem",
            "certificate": "certificate.pem",
            "key": "some_key.pem",
             "passphrase": "passphrase"
         },
         "Context2": {
            "certificateAuthority": "certificatestore.pem",
            "pfx": "some_pfx.pfx",
            "passphrase": "passphrase"
         }
     }
  }

Image

Additionally we can specify custom ssl context using Custom Context option. Custom SSL Context accepts dollar expressions e.g.

{
  "certificateAuthority": "certificatestore.pem",
  "pfx": "${getEnv('pfx_file')}",
  "passphrase": "${getEnv('passphrase')}"       
}

Image

The above payload can be in many forms. Refer the got module https documentation here

OE Connector

  • Model : oeCloud model to invoke method on

  • Method : Name of the method to invoke. The drop-down is automatically refreshed depending on selected model.

  • Arguments : Arguments to pass to the method. Specify as an array and use direct expressions for dynamic values.

[options, pv('loanId'), msg.status, 'Argument-3-Value']

Image

Finalize Transaction Connector

  • Type : Value/Source of the status to finalize maker-checker transaction(Process Variable, Message, Approve, Reject)
    • Specify static value Approve or Reject
    • Or specify the source of status as Process Variable or Message object.
  • Value : If Type is Process Variable or Message, the variable name to extract status.

Image

Example: Finalize Transaction Connector will reject the change request, when Type is Process Variable, Value is ApprovalAction and Process Variables are

{
	ApprovalAction: 'rejected',
	name: 'John',
	age: 23
}

User Task

A user task models work that needs to be done using a human interaction like data enrichment, approval, verification etc. When the process execution arrives at a user task, a new Task record is created for assigned user or role. The workflow execution suspends at the user task and resumes when the task is completed via /api/Tasks/complete API.

Image

Settings

  • Task Category : Specifies how the task completion is handled specially in maker-checker scenario. Refer this guide for more details.

  • Candidate Users : Defines whom the User Task is assigned. Multiple users can be comma separated. Field can accept and evaluate dollar-expressions.

  • Candidate Roles : Defines the user roles that can act and complete the User Task. Multiple roles can be comma separated. A user who has any of the candidate roles assigned can act of the task provided user is not mentioned as Excluded. Field can accept and evaluate dollar-expressions.

  • Candidate Groups : Defines the groups that can act and complete the User Task. Multiple groups can be comma separated. A user who has any of the candidate groups assigned can act of the task provided user is not mentioned as Excluded. Field can accept and evaluate dollar-expressions.

  • Excluded Users : Specifies the user who are excluded from acting on this task. Multiple users can be comma separated. Field can accept and evaluate dollar-expressions.

  • Excluded Roles : Specifies the roles that are forbidden from acting on this task. Multiple roles can be comma separated. Field can accept and evaluate dollar-expressions.

  • Excluded Groups : Specifies the groups that are forbidden from acting on this task. Multiple groups can be comma separated. Field can accept and evaluate dollar-expressions.

    Note that oeCloud user model has no group field. Applications intending to use candidate-group/excluded-group feature should populate context.group field appropriately using application’s definition of group (possibly a user department or user’s context entity).

    This is done by means of context injection during API call.

  • Due Date : Due date for the task in DD-MM-YYYY format or any kind of date expressions and dollar-expressions e.g. tod, tom, 5m, 30d, ${pv(‘calDate’)}

  • Followup Date : FollowUp date for the task in DD-MM-YYYY format or any kind of date expressions and dollar-expressions like tod, tom, 5m, 30d, ${pv(‘calDate’)} etc.

  • Priority : Priority of the task.

Note that Due Date, Followup Date and Priority are captured, evaluated and populated on the created Task record. The workflow engine does not use these fields in any way. Applications can make use of this information and perform appropriate work e.g. a batch-job scans through the pending tasks having followup dates as today and sends an email notification to user/team.

  • Creation / Completion / Post Completion Hooks : These properties provide a way for application to insert a custom logic for task creation and completion. Refer this guide for more details.

Note : If no Candidate Users & Candidate Roles are specified, any user except the excluded ones can complete the task.

Manual Task

A manual task has no impact on the workflow execution. It is used as a notification task for the users to do a task outside the system.

Business Rule Task

A business rule task enables the workflow to execute a DMN rule task and proceed with the results.

Image

Settings

  • Implementation : The rule engine implementation. Currently only oeCloud implementation of DMN rules is suported. Select DMN from the dropdown.

  • Decision Type : Name of the decision-rule to evaluate. Select from the dropdown, or choose custom and provide name in Decision Ref field. This custom text box is for dynamic rule names, which will be evaluated at run time and a dollar expression can be used.

  • Decision Mode : oeCloud rule engine’s decision construct. Choose Decision Table, Decision Graph or Decision Tree.

A decision tree allows defining conditional evaluation of a series of decision tables.

Payload for rule execution can be prepared and passed by means of input parameters. Refer step variabes for more details.

Call Activity

A call activity allows integrating external bpmn files (workflows) within the current workflow as a module. This is somewhat similar to a sub process, however a sub-process is defined and embedded within the workflow where it is being used. Whereas, a call activity is a reference to another external bpmn flow that has been already deployed.

The property panel on the right side of the diagram editor has a “Called Element” dropdown that lists all the deployed workflows. It allows picking a particular workflow from the list or if Custom Workflow is selected, the workflow name can be input through a text box. This custom text box is for dynamic call activity configuration, which will be evaluated at run time and a dollar expression can be used.

Image

Passing state to child flow

The process variables from the main process instance can be passed to the call activity directly or can be mapped using input variable mapping. Similarly, process variables from the child process can be extracted and set on main process using output variable mapping. These mappings helps in the reuse of business process logic. Any call activity or subprocess can be designed without any reference to the variables in invoking process. Any input variable expected in call activity can be mapped from the main process variables and any output expected from call activty can also be mapped to main process variables.

Settings

  • Type : Mapping type (Source, Source Expression or All). Source and Source Expression have same behavior.
  • Source :
    • For Input Mapping, this is the process variable name of main process instance to pass to child
    • for Output Mappings, this is the call-activity’s process variable name that is copied to main process
  • Target :
    • For Input Mapping, this is the target variable name for child process’
    • For Output Mappings, this is the target variable name for main instance

Note that, mappings are meant for transferring process variables between main and child process. To pass fixed values can use (step variables)(step-variables).

Subflows

A sub flow allows defining and running a separate child flow inside a main running process.

Image