Activiti BPM
Activiti BPM - Start a process
Method used to start a process and get back a process instance id.
Syntax:
Description:
Argument
Description
appId
application id having the process defined internally
processDefinitionId
process id defined when creating the workflow though the Activiti Web Designer
params
optional parameters which can override the default ones; for example there can be attributes like "username" and "password" which can be used instead of the current logged user, when starting the process
processVariables
input parameters defined for the Start task within the process definition
The responseObj is a Java object containing:
success - boolean flag reporting whether the process was started successfully
id - the process instance id related to the instance just started, in case of success = true
msg - error message, in case of success = false
In order to access to these values, you have to use the get("attrname") method; example:
var id = responseObj.get("id");
Activiti BPM - Complete a manual task
Method used to complete a manual task for the current logged user.
DO NOT USE THIS METHOD IF THE TASK IS NOT ASSIGNED TO THE CURRENT USER: you cannot use this method if the Manual Task does not have an assigned user and such a suer is the current user!
In case of troubles, use closeActivitiTask method.
Syntax:
Description:
Argument
Description
processInstanceId
instance id related to a process started
params
optional parameters which can override the default ones; for example there can be attributes like "username" and "password" which can be used instead of the current logged user, when starting the process
processVariables
input parameters to pass forward to the manual task to start/complete
The responseObj javascript object can contain:
success - boolean flag reporting whether the process was started successfully
msg - error message, in case of success = false
Activiti BPM - Delete an instance process programmatically
Method used to delete an instance process currently under execution.
Syntax:
Description:
Argument
Description
processInstanceId
instance id related to a process to kill
In case of errors, an exception is fired.
Activiti BPM - Get all instance process variables
Method used to delete an instance process currently under execution.
Syntax:
Argument
Description
processInstanceId
instance id related to a process to kill
processDefinitionId
process id
The method returns a JSON string representing the list of variables, having the following format:
In case of errors, an exception is fired.
Activiti BPM - Get process descriptor
Method used to get the description, in JSON format, of the static definition of a process.
Such a description contains all objects defined in a process: user tasks, automatic tasks (service/script tasks), gateways (if, fork, join), start/ends events.
Syntax:
Description:
Argument
Description
processId
identifier of the process
includeSubProcesses
boolean value used to enable the retrieval of tasks for all referring sub-processes; if set to true, the "invocation process" task is replaced by the whole subprocess tasks
tasksDueDates
javascript object; if set, it contains the due date for each task id; each attribute is the processId.taskId (including task ids for all referred sub-processes) and its value is the due date, expressed as a String either in "yyyy-MM-dd HH:mm:ss" format or using the ISO-8610 format (see https://en.wikipedia.org/wiki/ISO_8601#Dates)
The response is a String representing the process descriptor, expressed in JSON format. An exception is fired in case of errors or null if the processed has not been found.
The JSON has the following content:
By and large, the result is always a list, where each js object is related to an element of the process (a task, a gateway, an event, etc); the elements in the list are not reported in a specific order.
Each js object always contains the following attributes:
name - the task name
id - the task id, helpful to refer the task in the rest of the application or to sort the task reference in a database table
type - the element type; if can be: startEvent, endEvent, userTask, serviceTask, scriptTask, parallelGateway, inclusiveGateway, callActivity (in case of an invocation of a sub-process), boundaryEvent (a timer linked to a userTask)
sources - list of ids related to all elements having a link starting from them and arriving in the current element (predecessors)
targets - list of ids related to all elements having a link whose origin is the current element (destinations)
flowConditions - list of conditions, one for each target reported above, indicating the boolean condition to fulfill, in order to go onto the corresponding target (in case of exclusiveGateway task)
flowNames - list of names for the conditions, one for each target reported above, in order to go onto the corresponding target (in case of exclusiveGateway task)
sequence - a string representing the execution order of each task with regards to each other; in case of gateway (if, parallel execution), the sequence is expressed as "num1.num2"; in this way tasks belonging to different branches of the same original gateway task can continue with a consistent enumeration; when a join task is met, the sequence returns to "num" format; recursive sequence is supported as well (n1.n2.n3...). In case of sub-processes (with "includeSubProcesses" flag set to true) the sequence is defined in "num1.num2" format again.
Additionally, according to the type, there can be other attributes:
candidateUsers, candidateGroups, assignee - for a userTask element; they can be null even for userTask elements
dueDate - for a userTask element; it can be null even for userTask elements
expirationDate - for a userTask element; it can be null even for userTask elements; it can be replaced by the one passed forward through the "tasksDueDates" argument
calledElement - process id related to the sub-process to invoke, in case of a callActivity type element
timeDuration - duration of a timer, in case of a boundaryEvent type element
attachedToRef - id of the userTask a boundaryEvent is attached to, in case of a boundaryEvent type element
Example:
Note: to quickly figure out how a process definition is, you can use the following utility URL from browser:
Activiti BPM - How to get the preview image for a process definition
URL
where id is the full key for a process.
Example:
It can be defined by concatenating the following content:
"SIN" constant string
company id
"_" constant string
company id
"_" constant string
process id
":" constant string
last process version
":" constant string
deployment id for the specified process id
The information above can be easily retrieved starting from the process list web service or by invoking the javascript server-side utility method getActivitiLastVersionProcessId.
The same value can retrieved also by invoking the standard Platform web service:
which returns the following JSON string:
Activiti BPM - Get the full key for a process
A process id is simply a code; when referring a process, it is often needed to specify the full key, composed of version and deployment id.
It can be retrieved by invoking the standard Platform web service:
which returns the following JSON string:
Activiti BPM - How to get the preview image for a process instance execution
URL
Activiti BPM - How to get the preview image for a process instance execution
URL
The result is something like:
Activiti BPM - How to get the list of assigned tasks for the current user
URL
The result is something like
Activiti BPM - How to assign a task to a user
URL
where the taskInstanceId is the value for the id attribute in the assignable tasks list reported in the previous section.
The same operation can be executed also within a server-side javascript action, through the function:
Activiti BPM - How to get the list of running tasks
URL
You can add any number of additional filters to get a subset of all running tasks, like assignee, candidateUsers, candidateGroups, due date, process id, process instance id, etc.
The whole list of available filters is reported here:
The result is something like:
The same operation can be executed also within a server-side javascript action, through the following function:
Activiti BPM - How to get the list of tasks assigned to other users where the specified user is a candidate
URL
You can add any number of additional filters to get a subset of all running tasks, like process id, process instance id, task id, due date, etc.
The whole list of available filters is reported here:
https://www.activiti.org/5.x/userguide/#restTasksGet
The returned list of tasks only includes tasks already assigned to other users, but which have the specified username as a candidate for those tasks.
The result is something like:
The same operation can be executed also within a server-side javascript action, through the following function:
Activiti BPM - How to get the list of tasks where the specified user is a candidate
There is a server-side javascript function available to get the list of tasks potentially assignabled to the specified user, i.e. where the user is a candidate.
Syntax:
Argument
Description
candidate
mandatory argument; username to use when filtering the tasks list: only tasks where the user is a candidate will be fetched
processInstanceId
optional argument: if set, the tasks list is filtered not only by username but also by process instance id
taskDefinitionKey
optional argument: if set, the tasks list is filtered not only by username but also by the task definition id, i.e. the code specified in the BPM model, when creating a task (if not filled, it is automatically defined by Activiti as a UUID)
returned value
a JSON string, expressed as { valueObjectList: [{...},....] }
where an element of the list is something like:
{
"id": "...", // instance task id
"owner": null,
"assignee": "...", // username
"name": "...", // the task description, as defined in the BPM model
"description": null,
"dueDate": "2020-05-20T10:09:10.000+0000",
"taskDefinitionKey": "...",
"processInstanceId": "...",
"processDefinitionId": "..."
}
Activiti BPM - how to close a task
There are 3 ways to close a task for an instance process. In any case, the task must be
a manual task not completed yet
either potentially assignable to a user or already assigned to a user
ready to be started
In order to close the task, you can:
use the standard "To do" functionality, provided by Platform and close a task
close a task, starting from its "task id", which is related to a specific process instance id, user and task; you can get the "task id", through one of the methods described above (getActivitiUserAssignedTasks or getActivitiUserCandidateTasks)
close a task starting from a process instance id, a task definition key and a user
In any case, if some task properties are mandatory, you have to provide them, when closing the task, otherwise, an exception will be fired. An exception will be fired also when:
invalid process instance id, a task definition key and a user have been provided
invalid task id has been provided
There are 2 server-side javascript methods available, in order to close a task, described as follows.
Syntax:
Argument
Description
taskInstanceId
a valid task id (as a String), which can be retrieved starting from
getActivitiUserAssignedTasks or getActivitiUserCandidateTasks methods
map
a javascript object containing all required values to pass forward to activiti, in order to close the process
Syntax:
Argument
Description
processInstanceId
a valid process instance id (as a String), which can be retrieved starting from
getActivitiUserAssignedTasks or getActivitiUserCandidateTasks methods
taskDefinitionKey
a task definition key, as defined in the BPM model (its id)
assignee
the username for the user who has the specified task assigned
map
a javascript object containing all required values to pass forward to activiti, in order to close the process
Activiti BPM - How to get the list of tasks assigned to a specific user
There is a server-side javascript function available to get the list of tasks assigned to the specified user.
Syntax:
Argument
Description
assignee
mandatory argument; username to use when filtering the tasks list: only tasks assigned to this user will be fetched
processInstanceId
optional argument: if set, the tasks list is filtered not only by username but also by process instance id
taskDefinitionKey
optional argument: if set, the tasks list is filtered not only by username but also by the task definition id, i.e. the code specified in the BPM model, when creating a task (if not filled, it is automatically defined by Activiti as a UUID)
returned value
a JSON string, expressed as { valueObjectList: [{...},....] }
where an element of the list is something like:
{
"id": "...", // instance task id
"owner": null,
"assignee": "...", // username
"name": "...", // the task description, as defined in the BPM model
"description": null,
"dueDate": "2020-05-20T10:09:10.000+0000",
"taskDefinitionKey": "...",
"processInstanceId": "...",
"processDefinitionId": "..."
}
Activiti BPM - How to parse a duration/period expressed in ISO-8601 format
A duration/period can be expressed in ISO.8601 (see https://en.wikipedia.org/wiki/ISO_8601#Dates)
You can extract the time information from it, using the following javascript function:
Argument
Description
period
a String containg a duration expressed in ISO-8601 format, e.g. "PT1M" (i.e. 1 minute)
The returning string is in JSON format and always contains as follows:
The example above is related to the input string "PT1M".
Activiti BPM - How to add a duration/period expressed in ISO-8601 format to a Date
A duration/period can be expressed in ISO.8601 (see https://en.wikipedia.org/wiki/ISO_8601#Dates)
You can add the duration to a Date object, using the following javascript function:
Argument
Description
date
a Date object
period
a String containing a duration expressed in ISO-8601 format, e.g. "PT1M" (i.e. 1 minute)
The returning Date is like the input Date, incremented by the duration expressed through the "period" argument.
Last updated