When you click on any process definition, reusable form, app definition or stencil in the four Kickstart tabs, you open the Kickstart editor. The Kickstart editor lets you work with the item itself, rather than its contents. You can copy it, comment on it, delete it, favorite it, share it with others, and export it. You can also open the corresponding editor to make changes to the content, and perform actions specific to the item type. For example, you can publish an app definition.

In the above example, the Kickstart editor is open on an app definition called publisher. The editor always shows item details in the top panel and a set of buttons in the top right. The right-most button opens the editor corresponding to the item displayed. So in this example, the right-most button opens the app editor. If a process definition created using the step editor is opened in the Kickstart editor, then the right-most button would open the step editor.

A human step is a task to be completed by a user. You choose who to assign the task to, you can provide a form for that user to complete, you can define a due date for the task, and set a timer which, if it is triggered will allow Activiti to take some action related to the task, such as reassign it to another user.

The human step dialog contains four tabs that let you fully define the task.

Name and Description are simple text fields that help you and others to identify the task in your task list. Assignment lets you choose who is assigned to complete this step:

You can select a form to display when the task runs. You can choose an existing form, or create a new one. Forms that you create here while designing your process definition are accessible to steps in this process definition only. Forms that you have designed in the Forms tab of the SkyVault Activiti app are reusable by any process definition owned by someone you have shared the form with. Both types of form are listed in the chooser dialog. You can filter the available list of forms by entering text in the Filter box.

If you specify a Due date, then the time remaining until that date will be displayed in the task details when the process is running. If the task is not completed in that time, then the amount of time since the due date is displayed. You have three options for setting a due date:

Timer is similar to Due date, except you specify a time after which some action will be performed on the task by Activiti. You have three options for setting a timer:

You also specify an action for the task to be taken when the timer completes:

When an email step starts in a running process, it sends an email with a fixed text body and a fixed title to a single or multiple recipients.

The email step dialog contains two tabs that let you fully define the task.

Name and Description are simple text fields that help you and others to identify the task in your task list.

Recipient type lets you choose who receives the email defined in this step:

A choice step lets your process start one of two or more sequences of substeps, based on conditions.

The choice step dialog contains two tabs that let you fully define the task.

Name and Description are simple text fields that help you and others to identify the task in your task list.

When you select the Choices tab on a new choice step it shows two choice boxes. You can use the + icon between them to add more choices. When you click on a choice box you can edit the choice to give it a name and a condition. The condition can be one of the following:

There a two steps that you can at the end of a substep sequence in a choice step that change the flow of control in the process:

A sub process step lets you create a step that itself contains a sequence of steps that constitute a complete process definition. When saved, this definition is added to the list of substeps available to your main process definition. This gives you a method of managing complex processes by refining repeated sequences of steps into a sub step. This can make your process definition easier to comprehend visually.

The sub step step dialog contains one tab that lets you fully define the task.

Name and Description are simple text fields that help you and others to identify the task in your task list.

Sub process lets you choose a sub process that you have already defined in this process definition, or you can create a new sub process that is reusable in this process definition.

This step allows you to write a document or all documents uploaded in your process to a SkyVault repository. This can be a SkyVault 2.0 on-premise repository, or SkyVault in the Cloud.

The Publish to SkyVault step dialog contains three tabs that let you fully define the task.

Name and Description are simple text fields that help you and others to identify the task in your task list.

This step allows you make an arbitrary Activiti REST API call to any Activiti endpoint defined by an administrator on your Activiti server. You can supply parameters to the call directly in the URL or from process variables in forms, and you can extract properties from the JSON response into process variables for use in your process definition.

The Activiti REST APIs are described ?. The REST call step dialog contains four tabs that let you fully define the call.

Name and Description are simple text fields that help you and others to identify the task in your task list.

You define the URL for your REST API call in this tab.

Some REST API calls require a JSON request body. You can add one or more JSON properties using this tab.

For each property you define the name, property type and value. The value can either be a fixed value, or you can select the value of a form field from a list of available form fields in your process definition.

REST API calls return a JSON response body. You can define one or more pairs JSON response properties and process variables. When the step completes, each process variable will contain the value of the returned response property. You can use those values later in your process. In this example, the returned JSON property edition will be contained in the process variable activitiedition which is a form field in a form used to display the edition string later in the process definition.

This step lets you to generate a Microsoft Word or a PDF document from a template document written in Microsoft Word. The process step will substitute any templates you place in the template document with process and form variables. You can upload global template documents for use by all users, or upload personal template documents for your own use.

The Generate Document step dialog contains three tabs that let you fully define the task.

Name and Description are simple text fields that help you and others to identify the task in your task list.

Output format choose the format that you want your generated document to be in, PDF or Word.

This tab let’s you choose from a list of company templates that an an administrator has uploaded, or you can upload your own personal template. In the above example, the offer.docx company template has been chosen.

You can also filter the list of company templates with a search string, and download any template to see what form and process variable substitutions are made in the template.

Variable lets you enter a name for your output document.

In this example, Example Corp’s human resources department has a process to send out offer letters. They use a template document that looks like this:

Note the format of the templates. For example, <<[name]>> is substituted in the output document by the form variable name. Templates are processed using the LINQ reporting engine, the programming guide in the link describes the format of the templates, and provide a set of examples to help you create your own templates.

Templates can be simple, like the <<[name]>> example, or you can use expressions to build more complex templates. For example, look at the following section of the template letter:

This template uses a conditional expression that tests the value of the form variable annualsalary and outputs one of two different text phrases, depending on that value.

This is the process definition that uses the template:

The user starts the process by filling in a form called starter. The form contains four fields, a text field with the ID name, a set of radio buttons with the ID department, and two number fields with the IDs annualsalary and annualbonus. Once the user has filled the form, the Generate Document step takes the offer.docx template described above and generates a document with a name defined by value of the Variable tab shown, offer-letter.docx.

If the user fills in the starter form like this:

When the user clicks Start Process, the Generate Document step is executed and the offer-letter.docx document is generated, and looks like this:

In this example the Generate Document step is the last step in the process definition, and you can view and download the generated document in the completed process display.

A start event indicates where a process starts. You can define events that start on the arrival of a message, or start at specific time intervals, or start as a result of an error, or start as when a specific signal is raised, or start on no specific trigger.

In the XML representation, the type of start event is specified as a sub-element.

Start events are always catching: a start event waits until a specific trigger occurs.

An activity describes a single item of work to be performed in a process. SkyVault Activity provides some Activity types that are additional to those described in the BPMN 2.0 specification.

You use structural components to group multiple components in a sub process to reuse in a parent process definition, and to embed and call other process definitions from inside your own process.

You use gateways to control the flow of execution in your process.

In order to explain how Sequence Flows are used within a Process, BPMN 2.0 uses the concept of a token. Tokens traverse sequence flows and pass through the elements in the process. The token is a theoretical concept used to explain the behavior of Process elements by describing how they interact with a token as it “traverses” the structure of the Process. SkyVault Activiti, and any other BPMN engine does not define a token, but this documentation uses the concept.

Gateways are used to control how how tokens flow through sequence flows as they converge and diverge in a Process. As the term “gateway” suggests, there is a gating mechanism that either allows or prevents passage of a token through the Gateway. As tokens arrive at a Gateway, they can be merged together on input and/or split apart on output from the Gateway.

Gateways, like Activities, are capable of consuming or generating additional control tokens, to control the execution semantics of the Process. Gateways do not represent ‘work’ being done and they are considered to have zero effect on the cost or time of the Process being executed.

A gateway is displayed as a diamond, with an icon inside. The icon shows the type of gateway.

You use boundary events to handle an event associated with an activity. A boundary event is always attached to an activity.

While the activity the boundary event is attached to is is running, the boundary event is listening for a certain type of trigger. When the event is caught, the activity is interrupted and the sequence flow going out of the event is followed.

A boundary event is displayed as an circled icon which is always attached to the rounded rectangle representing the associated activity.

You use an intermediate catching event to indicate where something happens between the start and end of a Process. It can affect the flow of the Process, but will not start, or directly end, the Process.

Here are some examples of situations where you might want to use an intermediate catching event:

An intermediate event is displayed as two concentric circles containing an icon. The icon shows the type of intermediate event.

You use an intermediate throwing event to indicate where something happens between the start and end of a Process. It can affect the flow of the Process, but will not start, or directly end, the Process.

An example of a situation where you might want to use an intermediate throwing event is where you need to disrupt the normal flow by throwing a signal.

An intermediate event is displayed as two concentric circles which may contain an icon. If present, the icon shows the type of intermediate event. A throwing none event contains no icon.

You use an end event to signify the end of a process or sub-process, or the end of a path in a process or sub-process.

An end event is displayed as thick black circle which may contain an icon. If present, the icon shows the type of end event. A none end event has no icon.

You use swimlanes to display activities in your process divided by business function or participant group. A process definition can have one swimlane diagram containing one pool, which in turn contains one or more lanes. The pool represents the whole process, and each lane corresponds to a business function or participant group.

For example the process of selling a book consists of several activities; Ordering a book, processing the order, shipping the book, and reading the book, but the activities are performed by participants in different groups; by the customer, by the sales department, and by the warehouse or store. The following process definition has one pool called Sell a book with three lanes, Customer, Sales, and Store. The process sequence flow moves between lanes in the pool as the order progresses.

When you drag a pool to your process diagram it creates an unnamed pool containing one unnamed lane. You can add lanes by dragging a lane icon from the pallette to the canvas. When you mouse-over the name box of the pool, the whole pool border turns green, indicating the lane will be added to the pool when you release the mouse button.

You use artifacts to provide additional information about the Process. The BPMN editor supports the text annotation artifact which associates additional text to an element in your process, or to the process itself. The text does not influence the execution of a process, it is provided by the process designer to give information to the user of the process.

Text annotation.

You can set the following properties in the property sheet:

In your site’s document library, you can start a workflow on one or more files. In this tutorial you start a workflow, using one of the pre-defined Activiti processes, on two files.

The tutorial assumes you have your own site and added some files and folders to it.

You have started an Activiti process on selected files in a SkyVault site.

This tutorial leads you though the steps required to run your first Activiti process as a workflow from the SkyVault Share from the My Activiti Tasks dashlet.

All process definitions that you deploy to Apps in SkyVault Activiti are available to you in SkyVault Share. This tutorial assumes you have deployed the First process workflow using the ? tutorial. If you havn’t done so already, follow that tutorial now to deploy the workflow.

You have run an Actviti process definition as a workflow in SkyVault Share. Note on the menu bar that you can get to the My tasks and My workflows pages from the Tasks menu, and you can go to the associated SkyVault Activiti for this SkyVault Share site.

Event definitions define the semantics of an event.

Without an event definition, an event "does nothing special". For instance a start event without and event definition does not specify what exactly starts the process. If we add an event definition to the start event (like for instance a timer event definition) we declare what "type" of event starts the process (in the case of a timer event definition the fact that a certain point in time is reached).

A start event indicates where a process starts. You can define events that start on the arrival of a message, or start at specific time intervals, or start as a result of an error, or start as when a specific signal is raised, or start on no specific trigger.

In the XML representation, the type of start event is specified as a sub-element.

Start events are always catching: a start event waits until a specific trigger occurs.

You can specify the following Activiti-specific properties:

You use an end event to signify the end of a process or sub-process, or the end of a path in a process or sub-process.

An end event is displayed as thick black circle which may contain an icon. If present, the icon shows the type of end event. A none end event has no icon.

An end event is always throwing. This means that when process execution arrives in the end event, a result is thrown. In the XML representation, the type is given by the declaration of a sub-element.

You use boundary events to handle an event associated with an activity. A boundary event is always attached to an activity.

When you drag a boundary event icon from the pallette on to the canvas and you mouse-over an activity, the Activiti symbol with turn green, indicating the boundary event will be attached to this activity when you release the mouse button.

While the activity the boundary event is attached to is is running, the boundary event is listening for a certain type of trigger. When the event is caught, the activity is interrupted and the sequence flow going out of the event is followed.

A boundary event is displayed as an circled icon which is always attached to the rounded rectangle representing the associated activity.

All boundary events are defined in the same way:

A boundary event is defined with

There is a known issue regarding concurrency when using boundary events of any type.

You can not have multiple outgoing sequence flow attached to a boundary event (see issue ACT-47 ). A solution to this problem is to use one outgoing sequence flow that goes to a parallel gateway.

You use an intermediate catching event to indicate where something happens between the start and end of a Process. It can affect the flow of the Process, but will not start, or directly end, the Process.

Here are some examples of situations where you might want to use an intermediate catching event:

An intermediate event is displayed as two concentric circles containing an icon. The icon shows the type of intermediate event.

All intermediate catching events events are defined like this:

An intermediate catching event is defined with:

You use an intermediate throwing event to indicate where something happens between the start and end of a Process. It can affect the flow of the Process, but will not start, or directly end, the Process.

An example of a situation where you might want to use an intermediate throwing event is where you need to disrupt the normal flow by throwing a signal.

An intermediate event is displayed as two concentric circles which may contain an icon. If present, the icon shows the type of intermediate event. A throwing none event contains no icon.

All intermediate throwing events events are defined like this:

An intermediate throwing event is defined with:

A sequence flow can have a condition defined on it.

When a BPMN 2.0 activity is left, the default behavior is to evaluate the conditions on the outgoing sequence flow. When a condition evaluates to true, that outgoing sequence flow is selected. When multiple sequence flow are selected that way, multiple executions will be generated and the process will be continued in a parallel way.

A conditional sequence flow is visualized as a regular sequence flow, with a small diamond at the beginning.

The condition expression is shown next to the sequence flow.

A conditional sequence flow is represented in XML as a regular sequence flow, containing a conditionExpression sub-element.

Note that only tFormalExpressions are supported, Omitting the xsi:type="" definition will default to this single supported type of expression.

Currently conditionalExpressions can only be used with UEL, detailed info about these can be found in section ?. The expression used should resolve to a boolean value, otherwise an exception is thrown while evaluating the condition.

The Activiti distribution contains the following example process using value and method expressions (see org.activiti.examples.bpmn.expression):

All BPMN 2.0 tasks and gateways can have a default sequence flow. This sequence flow is only selected as the outgoing sequence flow for that activity if and only if none of the other sequence flow could be selected. Conditions on a default sequence flow are always ignored.

A default sequence flow is visualized as a regular sequence flow, with a 'slash' marker at the beginning.

A default sequence flow for a certain activity is defined by the default attribute on that activity.

The following XML snippet shows for example an exclusive gateway that has as default sequence flow flow 2. Only when conditionA and conditionB both evaluate to false, will it be chosen as outgoing sequence flow for the gateway.

Which corresponds with the following graphical representation:

You use an exclusive gateway model a decision in your process.When execution arrives at an exclusive gateway, the outgoing sequence flows are evaluated in the order in which they are defined. The first sequence flow whose condition evaluates to true, or which does not have a condition set, is selected and the process continues.

Note that if no sequence flow can be selected, an exception will be thrown.

Graphical notation.

The exclusive gateway is defined by the exclusiveGateway element, and condition expressions on the outgoing sequence flows.

See the section on ? to see which options are available for such expressions.

The above model is represented in XML as follows:

You use a parallel gateway to model concurrency in a process. It allows you to fork multiple outgoing paths of execution or join multiple incoming paths of execution.

In a fork, all outgoing sequence flows are followed in parallel, which creates one concurrent execution for each sequence flow.

In a join, all concurrent executions arriving at the parallel gateway wait at the gateway until an execution has arrived for every incoming sequence flow. Then the process continues past the joining gateway.

A single parallel gateway can both fork and join, if there are multiple incoming and outgoing sequence flow. The gateway will first join all incoming sequence flows, before splitting into multiple concurrent paths of executions.

Unlike other gateways, the parallel gateway does not evaluate conditions. Any conditions defined on the sequence flow connected with the parallel gateway are ignored.

Graphical notation.

The following element defines a parallel gateway:

The fork, join or both are defined by the sequence flows connected to the parallel gateway.

The model above is defined by the following XML:

In the example, after the process is started, two tasks are created:

When both these tasks are completed, the second parallel gateway will join the two executions. Since there is only one outgoing sequence flow, no concurrent paths of execution will be created, and only the Archive Order task will be active.

Note that a parallel gateway does not need to be balanced – the number of incoming and outgoing sequence flows does not need to match. A parallel gateway will wait for all incoming sequence flows and create a concurrent path of execution for each outgoing sequence flow. It is influenced by other constructs in the process model. For example, the following diagram is a valid BPMN 2.0 process model:

You use an inclusive to join and fork multiple sequence flows based on conditions.

Like an exclusive gateway you can define conditions on outgoing sequence flows and the inclusive gateway will evaluate them, but an inclusive gateway can take more than one sequence flow, like the parallel gateway.

In a fork, all outgoing sequence flow conditions are evaluated. Every sequence flow with a condition that evaluates to true, is followed in parallel, creating one concurrent execution for each sequence flow.

In a join, all concurrent executions arriving at the inclusive gateway wait at the gateway until an execution has arrived for each of the incoming sequence flows that have a process token. The inclusive gateway will only wait for the incoming sequence flows that will be executed. After the join, the process continues past the joining inclusive gateway.

Note that an inclusive gateway can have both fork and join behavior, in which case there are multiple incoming and outgoing sequence flows for the same inclusive gateway. The gateway will join all incoming sequence flows that have a process token, before splitting into multiple concurrent paths of executions for the outgoing sequence flows that have a condition that evaluates to true.

Graphical notation.

The following element defines an inclusive gateway:

The fork, join or both are defined by the sequence flows connected to the inclusive gateway.

The model above is defined by the following XML:

In the above example, after the process is started, two tasks will be created only if the process variables paymentReceived is false and shipOrder is true. If only one of these process variables evaluates to true, then only one task will be created. If no condition evaluates to true an exception is thrown. You can prevent the exception by specifying a default outgoing sequence flow.

In the following example one task will be created, the ship order task:

When this task is completed, the second inclusive gateway will join the two executions and since there is only one outgoing sequence flow, no concurrent paths of execution will be created, and only the Archive Order task will be active.

Note that an inclusive gateway does not need to be 'balanced' (i.e. a matching number of incoming/outgoing sequence flow for corresponding inclusive gateways). An inclusive gateway will wait for all incoming sequence flow and create a concurrent path of execution for each outgoing sequence flow, not influenced by other constructs in the process model.

You use an event gateway to take a decision based on events.

Each outgoing sequence flow of the event gateway must be connected to an intermediate catching event. When process execution reaches an event gateway execution is suspended, and for each outgoing sequence flow, an event subscription is created.

Outgoing sequence flows connect to an event gateway are never "executed", but they do allow the process engine to determine which events an execution arriving at an Event-based Gateway needs to subscribe to. The following restrictions apply to event gateways:

Graphical notation.

The eventBasedGateway XML element used to define an event gateway.

You use a user task to model work to be done by a human actor. When process execution arrives at a user task in the process definition, it creates a new task in the task list of the assignee or assignees defined in the task.

Graphical notation.

A user task is defined in XML as follows.

The id attribute is required, the name attribute is optional.

A user task can have also a description. In fact any BPMN 2.0 element can have a description. A description is defined by adding the documentation element.

The description text can be retrieved from the task in the standard Java way:

Each task has a field, indicating the due date of that task. The Query API can be used to query for tasks that are due on, before or after a certain date.

There is an activity extension which allows you to specify an expression in your task-definition to set the initial due date of a task when it is created. The expression should always resolve to a java.util.Date, java.util.String (ISO8601 formatted), ISO8601 time-duration (for example, PT50M) or null. For example, you could use a date that was entered in a previous form in the process or calculated in a previous Service Task. In case a time-duration is used, the due-date is calculated based on the current time, incremented by the given period. For example, when "PT30M" is used as dueDate, the task is due in thirty minutes from now.

A user task can be directly assigned to a user.

This is done by defining a humanPerformer sub element. Such a humanPerformer definition needs a resourceAssignmentExpression that actually defines the user. Currently, only formalExpressions are supported.

Only one user can be assigned as human performer to the task. In Activiti terminology, this user is called the assignee. Tasks that have an assignee are not visible in the task lists of other people and can be found in the so-called personal task list of the assignee instead.

Tasks directly assigned to users can be retrieved through the TaskService as follows:

Tasks can also be placed in the candidate task list for people. You use the potentialOwner construct, its usage is similar to the humanPerformer construct. Do note that it is required to define for each element in the formal expression to specify if it is a user or a group (the engine cannot guess this).

Tasks defines with the potential owner construct, can be retrieved as follows (or a similar TaskQuery usage as for the tasks with an assignee):

This will retrieve all tasks where kermit is a candidate user, i.e. the formal expression contains user(kermit). This will also retrieve all tasks that are assigned to a group where kermit is a member of (e.g. group(management), if kermit is a member of that group and the Activiti identity component is used). The groups of a user are resolved at runtime and these can be managed through the ?.

If no specifics are given whether the given text string is a user or group, the engine defaults to group. So the following would be the same as when group(accountancy) was declared.

It is clear that user and group assignments are quite cumbersome for use cases where the assignment is not complex.

To avoid these complexities, you can use ? on the user task.

Note: Although Activiti provides an identity management component, which is exposed through the ?, no check is done whether a provided user is known by the identity component. This allows Activiti to integrate with existing identity management solutions when it is embedded into an application.

The BPMN standard supports a single assigned user or humanPerformer or a set of users that form a potential pool of potentialOwners as defined in User assignment. In addition, Activiti defines extension attribute elements for the User Task that can represent the task assignee or candidate owner.

The supported Activiti identity link types are:

The BPMN standard and Activiti example authorization identities are user and group. As mentioned in the previous section, the Activiti identity management implementation is not intended for production use, but should be extended depending upon the supported authorization scheme.

If additional link types are required, custom resources can be defined as extension elements with the following syntax:

The custom link expressions are added to the TaskDefinition class:

which are populated at runtime by the UserTaskActivityBehavior handleAssignments method.

Finally, the IdentityLinkType class must be extended to support the custom identity link types:

Here is an example db entry for a custom identity link type administrator with a single user ( gonzo ) and group ( engineering ) values.

A user task can be directly assigned to a user.

This is done by defining a humanPerformer sub element. Such a humanPerformer definition needs a resourceAssignmentExpression that actually defines the user. Currently, only formalExpressions are supported.

Only one user can be assigned as human performer to the task. In Activiti terminology, this user is called the assignee. Tasks that have an assignee are not visible in the task lists of other people and can be found in the so-called personal task list of the assignee instead.

Tasks directly assigned to users can be retrieved through the TaskService as follows:

Tasks can also be put in the so-called candidate task list of people. In that case, the potentialOwner construct must be used. The usage is similar to the humanPerformer construct. Do note that it is required to define for each element in the formal expression to specify if it is a user or a group (the engine cannot guess this).

Tasks defines with the potential owner construct, can be retrieved as follows (or a similar TaskQuery usage as for the tasks with an assignee):

This will retrieve all tasks where kermit is a candidate user, i.e. the formal expression contains user(kermit). This will also retrieve all tasks that are assigned to a group where kermit is a member of (e.g. group(management), if kermit is a member of that group and the Activiti identity component is used). The groups of a user are resolved at runtime and these can be managed through the ?.

If no specifics are given whether the given text string is a user or group, the engine defaults to group. So the following would be the same as when group(accountancy) was declared.

A script task defines a JavaScript script or other script of a type included in JSR-223 to be run in your process definition.

Graphical notation.

A script task is defined by specifying the script and the scriptFormat.

The value of the scriptFormat attribute must be a name that is compatible with the JSR-223 (scripting for the Java platform). By default JavaScript is included in every JDK and as such doesn’t need any additional jars. If you want to use another (JSR-223 compatible) scripting engine, you can add the corresponding jar to the classpath and use the appropriate name. For example, the Activiti unit tests often use Groovy because the syntax is pretty similar to that of Java.

All process variables that are accessible through the execution that arrives in the script task, can be used within the script.

In the example, the script variable 'inputArray' is in fact a process variable (an array of integers).

You can also set process variables in a script, by calling execution.setVariable("variableName", variableValue) `. By default, no variables are stored automatically. You can automatically store any variable defined in the script, for example sum in the example above, by setting the property `autoStoreVariables on the scriptTask to true. However, the best practice is not to do this and use an explicit execution.setVariable() call, as on some recent versions of the JDK auto storing of variables does not work for some scripting languages. See this link for more details.

The default of this parameter is false, meaning that if the parameter is omitted from the script task definition, all the declared variables will only exist during the duration of the script.

This example shows how to set a variable in a script:

Note: the following names are reserved and cannot be used as variable names: out, out:print, lang:import, context, elcontext.

The return value of a script task can be assigned to an existing or to a new process variable by specifying the process variable name as a literal value for the 'activiti:resultVariable' attribute of a script task definition.

Any existing value for a specific process variable will be overwritten by the result value of the script execution. When not specifying a result variable name, the script result value gets ignored.

In the above example, the result of the script execution (the value of the resolved expression '#{echo}' ) is set to the process variable named 'myVar' after the script completes.

You use a service task to invoke an external Java class.

Graphical notation.

There are four ways of invoking Java logic:

To specify a class that is called during process execution, the fully qualified classname must be provided by the 'activiti:class' attribute.

See the implementation section for more details on how to use such a class.

You can also use an expression that resolves to an object. This object must follow the same rules as objects that are created when the activiti:class attribute is used (see further ).

Here, the delegateExpressionBean is a bean that implements the JavaDelegate interface, defined in for example the Spring container.

To specify a UEL method expression that should be evaluated, use attribute activiti:expression.

Method printMessage (without parameters) will be called on the named object called printer.

You can also pass parameters with a method used in the expression.

Method printMessage will be called on the object named printer. The first parameter passed is the DelegateExecution, which is available in the expression context by default available as execution. The second parameter passed, is the value of the variable with name myVar in the current execution.

To specify a UEL value expression that should be evaluated, use attribute activiti:expression.

The getter method of property ready, getReady (without parameters), will be called on the named bean called split. The named objects are resolved in the execution’s process variables and (if applicable) in the Spring context.

To implement a class that can be called during process execution, this class needs to implement the org.activiti.engine.delegate.JavaDelegate interface and provide the required logic in the execute method.

When process execution arrives at this particular step, it will execute this logic defined in that method and leave the activity in the default BPMN 2.0 way.

Let’s create for example a Java class that can be used to change a process variable String to uppercase. This class needs to implement the org.activiti.engine.delegate.JavaDelegate interface, which requires us to implement the execute(DelegateExecution) method. It is this operation that will be called by the engine and which needs to contain the business logic. Process instance information such as process variables and other can be accessed and manipulated through the DelegateExecution interface (click on the link for a detailed Javadoc of its operations).

Note: there will be only one instance of that Java class created for the serviceTask it is defined on. All process-instances share the same class instance that will be used to call execute(DelegateExecution). This means that the class must not use any member variables and must be thread-safe, since it can be executed simultaneously from different threads. This also influences the way ? is handled.

The classes that are referenced in the process definition (i.e. by using activiti:class ) are NOT instantiated during deployment. Only when a process execution arrives for the first time at the point in the process where the class is used, an instance of that class will be created. If the class cannot be found, an ActivitiException will be thrown. The reasoning for this is that the environment (and more specifically the classpath ) when you are deploying is often different from the actual runtime environment. For example when using ant or the business archive upload in Activiti Explorer to deploy processes, the classpath does not contain the referenced classes.

[INTERNAL: non-public implementation classes] You can also provide a class that implements the org.activiti.engine.impl.pvm.delegate.ActivityBehavior interface. Implementations have then access to the more powerful ActivityExecution that for example also allows to influence the control flow of the process. Note that this is not good practice, and should be avoided as much as possible. The ActivityBehavior interface is only for advanced use cases.

It is possible to inject values into the fields of the delegated classes.

The following types of injection are supported:

If available, the value is injected through a public setter method on your delegated class, following the Java Bean naming conventions (e.g. field firstName has setter setFirstName(…​) ). If no setter is available for that field, the value of private member will be set on the delegate. SecurityManagers in some environments don’t allow modifying private fields, so it is safer to expose a public setter-method for the fields you want to have injected. Regardless of the type of value declared in the process-definition, the type of the setter/private field on the injection target should always be org.activiti.engine.delegate.Expression.

The following code snippet shows how to inject a constant value into a field. Field injection is supported when using the 'class' attribute. Note that we need to declare a 'extensionElements' XML element before the actual field injection declarations, which is a requirement of the BPMN 2.0 XML Schema.

The class ToUpperCaseFieldInjected has a field text which is of type org.activiti.engine.delegate.Expression. When calling text.getValue(execution), the configured string value Hello World will be returned.

Alternatively, for longs texts (e.g. an inline e-mail) the 'activiti:string' sub element can be used:

To inject values that are dynamically resolved at runtime, expressions can be used. Those expressions can use process variables, or Spring defined beans (if Spring is used). As noted in Service Task Implementation, an instance of the Java class is shared among all process-instances in a service task. To have dynamic injection of values in fields, you can inject value and method expressions in a org.activiti.engine.delegate.Expression which can be evaluated/invoked using the DelegateExecution passed in the execute method.

The example class below uses the injected expressions and resolves them using the current DelegateExecution. Full code and test can be found in org.activiti.examples.bpmn.servicetask.JavaServiceTaskTest.testExpressionFieldInjection

Alternatively, you can also set the expressions as an attribute instead of a child-element, to make the XML less verbose.

Since the Java class instance is reused, the injection only happens once, when the serviceTask is called the first time. When the fields are altered by your code, the values won’t be re-injected so you should treat them as immutable and don’t make any changes to them.

The return value of a service execution (for service task using expression only) can be assigned to an already existing or to a new process variable by specifying the process variable name as a literal value for the 'activiti:resultVariable' attribute of a service task definition.

Any existing value for a specific process variable will be overwritten by the result value of the service execution. When not specifying a result variable name, the service execution result value gets ignored.

In the example above, the result of the service execution (the return value of the 'doSomething()' method invocation on an object that is made available under the name 'myService' either in the process variables or as a Spring bean) is set to the process variable named 'myVar' after the service execution completes.

When custom logic is executed, it is often required to catch certain business exceptions and handle them inside the surrounding process. Activiti provides different options to do that.

BPMN Errors can be thrown from user code inside Service Tasks or Script Tasks.

In order to do this, a special ActivitiException called BpmnError can be thrown in JavaDelegates, scripts, expressions and delegate expressions. The engine will catch this exception and forward it to an appropriate error handler, e.g., a Boundary Error Event or an Error Event Sub-Process.

The constructor argument is an error code, which will be used to determine the error handler that is responsible for the error. See ? for information on how to catch a BPMN Error.

This mechanism should be used only for business faults that shall be handled by a Boundary Error Event or Error Event Sub-Process modeled in the process definition. Technical errors should be represented by other exception types and are usually not handled inside a process.

[INTERNAL: non-public implementation classes] Another option is to route process execution through another path in case some exception occurs. The following example shows how this is done.

Here, the service task has two outgoing sequence flow, called exception and no-exception. This sequence flow id will be used to direct process flow in case of an exception:

For some use cases, you might need to use the Activiti services from within a Java service task, for example starting a process instance through the RuntimeService, if the callActivity doesn’t suit your needs). The org.activiti.engine.delegate.DelegateExecution allows to easily use these services through the org.activiti.engine.EngineServices interface:

All of the Activiti service API’s are available through this interface.

All data changes that occur as an effect of using these API calls, will be part of the current transaction. This also works in environments with dependency injection like Spring and CDI with or without a JTA enabled datasource. For example, the following snippet of code will do the same as the snippet above, but now the RuntimeService is injected rather than it is being fetched through the org.activiti.engine.EngineServices interface.

Important technical note: since the service call is being done as part of the current transaction any data that was produced or altered before the service task is executed, is not yet flushed to the database. All API calls work on the database data, which means that these uncommitted changes are not be 'visible' within the api call of the service task.

A Web Service task is used to synchronously invoke an external Web service.

A Web Service task is visualized the same as a Java service task.

To use a Web service we need to import its operations and complex types. This can be done automatically by using the import tag pointing to the WSDL of the Web service:

The previous declaration tells Activiti to import the definitions but it doesn’t create the item definitions and messages for you. Let’s suppose we want to invoke a specific method called 'prettyPrint', therefore we will need to create the corresponding message and item definitions for the request and response messages:

Before declaring the service task, we have to define the BPMN interfaces and operations that actually reference the Web service ones. Basically, we define and 'interface' and the required 'operation’s'. For each operation we reuse the previous defined message for in and out. For example, the following declaration defines the 'counter' interface and the 'prettyPrintCountOperation' operation:

Then you can declare a Web Service Task by using the ##WebService implementation and a reference to the Web service operation.

Unless we are using the simplistic approach for data input and output associations (See below), each Web Service Task needs to declare an IO Specification which states which are the inputs and outputs of the task.

The approach is pretty straightforward and BPMN 2.0 complaint, for our prettyPrint example we define the input and output sets according to the previously declared item definitions:

There are 2 ways of specifying data input associations:

To specify the data input association using expressions we need to define the source and target items and specify the corresponding assignments between the fields of each item. In the following example we assign prefix and suffix fields of the items:

On the other hand you can use the simplistic approach which is much more simple. The 'sourceRef' element is an Activiti variable name and the 'targetRef' element is a property of the item definition. In the following example we assign to the 'prefix' field the value of the variable 'PrefixVariable' and to the 'suffix' field the value of the variable 'SuffixVariable'.

There are 2 ways of specifying data out associations:

To specify the data out association using expressions we need to define the target variable and the source expression. The approach is pretty straightforward and similar data input associations:

On the other hand you can use the simplistic approach which is much more simple. The 'sourceRef' element is a property of the item definition and the 'targetRef' element is an Activiti variable name. The approach is pretty straightforward and similar data input associations:

A Business rule task synchronously executes one or more rules.

Activiti uses Drools Expert, the Drools rule engine to execute business rules. The .drl files containing the business rules must be deployed with the process definition that defines the business rule task to execute those rules. This means that all .drl files that are used in a process have to be packaged in the process BAR file like for example the task forms. For more information about creating business rules for Drools Expert please refer to the Drools documentation at JBoss Drools

if you want to plug in your implementation of the rule task, e.g. because you want to use Drools differently or you want to use a completely different rule engine, then you can use the class or expression attribute on the BusinessRuleTask and it will behave exactly like a ?

Graphical notation.

To execute one or more business rules that are deployed in the same BAR file as the process definition, we need to define the input and result variables.

For the input variable definition a list of process variables can be defined separated by a comma. The output variable definition can only contain one variable name that will be used to store the output objects of the executed business rules in a process variable. Note that the result variable will contain a List of objects. If no result variable name is specified by default org.activiti.engine.rules.OUTPUT is used.

The following business rule task executes all business rules deployed with the process definition:

The business rule task can also be configured to execute only a defined set of rules from the deployed .drl files. A list of rule names separated by a comma must be specified for this.

In this case only rule1 and rule2 are executed.

You can also define a list of rules that should be excluded from execution.

In this case all rules deployed in the same BAR file as the process definition will be executed, except for rule1 and rule2.

As mentioned earlier another option is to hook in the implementation of the BusinessRuleTask yourself:

Now the BusinessRuleTask behaves exactly like a ServiceTask, but still keeps the BusinessRuleTask icon to visualize that we do business rule processing here.

You can enhance your business process with this automatic mail service tasks that sends emails to one or more recipients. The task supports normal email features such as cc lists, bcc lists, and HTML content.

Graphical notation.

The Activiti engine sends e-mails trough an external mail server with SMTP capabilities.

To actually send e-mails, the engine needs to know how to reach the mail server. The following properties can be set in the activiti.cfg.xml configuration file:

The Email task is implemented as a dedicated ? and is defined by setting 'mail' for the type of the service task.

The Email task is configured by ?. All the values for these properties can contain EL expression, which are resolved at runtime during process execution. The following properties can be set:

The following XML snippet shows an example of using the Email Task.

with the following result:

Lets you send messages to the Mule ESB (Enterprise Service Bus).

You can find more information on Mule ESB here.

The Mule task is implemented as a dedicated ? and is defined by setting 'mule' for the type of the service task.

The Mule task is configured by ?. All the values for these properties can contain EL expression, which are resolved at runtime during process execution. The following properties can be set:

The following XML snippet shows an example of using the Mule Task.

You use the Camel task to send messages to, and receive messages from, Apache Camel.

You can find more information on Apache Camel here.

Graphical notation.

The Camel task is implemented as a dedicated ? and is defined by setting 'camel' for the type of the service task.

The process definition itself needs nothing else then the camel type definition on a service task. The integration logic is all delegated to the Camel container. By default the Activiti Engine looks for a camelContext bean in the Spring container. The camelContext bean defines the Camel routes that will be loaded by the Camel container. In the following example the routes are loaded from a specific Java package, but you can also define routes directly in the Spring configuration itself.

For more documentation about Camel routes you can look on the Camel website. The basic concepts are demonstrated through a few small samples here in this document. In the first sample, we will do the simplest form of Camel call from an Activiti workflow. Let’s call it SimpleCamelCall.

If you want to define multiple Camel context beans and/or want to use a different bean name, this can be overridden on the Camel task definition like this:

All the files related to this example can be found in org.activiti.camel.examples.simpleCamelCall package of activiti-camel module. The target is activating a specific camel route. First of all we need an Spring context which contains the introduction to the routes as mentioned previously. This part of the file serves this purpose:

The example worked but nothing is transferred between Camel and Activiti.

In this example you try to send and receive data to and from Camel. You send a string, Camel concatenates something to it and returns back the result. You send your message in form of a variable to Camel Task. Here is the caller code:

variable "input" is actually the input for the Camel route and outputMap is there to capture the result back from Camel. The process should be something like this:

Note that SaveOutput Service task, stores the value of "Output" variable from context to the previously mentioned OutputMap. Now we have to know how the variables are send to Camel and returned back. Here comes the notion of Camel behavior into the play. The way variables are communicated to Camel is configurable via CamelBehavior. Here you use Default one in the sample, a short description of the other ones comes afterwards. With such a code you can configure the desired camel behavior:

If you do not specify and specific behavior then, org.activiti.camel.impl.CamelBehaviorDefaultImpl will be set. This behavior copies the variables to Camel properties of the same name. In return regardless of selected behavior, if the camel message body is a map, then each of its elements is copied as a variable, else the whole object is copied into a specific variable with the name of "camelBody". Knowing that, this camel route concludes the second example:

In this route, the string "world" is concatenated to the end of property named "input" and the result will be in the message body. It is accessible by checking "camelBody" variable in the java service task and copied to "outputMap" and checked in test case. Now that the example on its default behavior works, lets see what are the other possibilities. In starting every camel route, the Process Instance ID will be copied into a camel property with the specific name of "PROCESS_ID_PROPERTY". It is later used for correlating the process instance and camel route. Also it can be exploited in the Camel route.

There are three different behaviors already available out of the box in Activiti. The behavior can be overwritten by a specific phrase in the route URL. Here is an example of overriding the already defined behavior in URL:

the following table provides an overview of three available camel behaviors:

The table above shows how Activiti variables are transferred to Camel. The next table shows how the Camel variables are returned to Activiti. This can only be configured in route URLs.

Source files of this example are available in org.activiti.camel.examples.pingPong package of activiti-camel module as well.

Previous examples were all synchronous.

The workflow stops until the camel route is concluded and returned. In some cases, we might need the Activiti workflow to continue. For such purposes the asynchronous capability of the Camel service task is useful. You can make use of this feature by setting the async property of the Camel service task to true.

By setting this feature the specified Camel route is activated asynchronously by the Activiti job executor. When you define a queue in the Camel route the Activiti process will continue with the activities after the Camel service task. The Camel route will be executed fully asynchronously from the process execution. If you want to wait for a response of the Camel service task somewhere in your process definition, you can use a receive task.

In the previous examples, the Activiti workflow started first and the Camel route was started within workflow.

A workflow can also be instantiated from an already started camel route. This is similar to a signalling receive task, except that the last part is not there. Here is a sample route:

The URL has two parts, the first is constant string "activiti" and the second name is the name of the process. The process should already be deployed and startable by engine configuration.

You can also set the initiator of the process to some authenticated user id that is provided in a Camel header. To achieve this first of all an initiator variable must be specified in the process definition:

Then given that the user id is contained in a Camel header named CamelProcessInitiatorHeader the Camel route could be defined as follows:

A Manual Task defines a task that is external to Activiti. You use it to model work done which the Activiti engine does not know of. A manual task is handled as a pass-through activity, the Activiti engine automatically continues the process from the instant process execution arrives at a manual task activity.

Graphical notation.

A Receive Task waits for the arrival of a specific message.

Only Java semantics are implemented for this task. When process execution arrives at a receive task, the process state is committed to the persistence store. This means the process will stay in a wait state, until a specific message is received by the engine, which triggers the continuation of the process.

Graphical notation.

To continue a process instance that is currently waiting at such a Receive Task, the runtimeService.signal(executionId) must be called using the id of the execution that arrived in the Receive Task. The following code snippet shows how this works in practice:

The shell task allows to run shell scripts and commands. Note that the Shell task is not an 'official' task of BPMN 2.0 spec (and it does not have a dedicated icon as a consequence).

The shell task is implemented as a dedicated ? and is defined by setting 'shell' for the type of the service task.

The Shell task is configured by ?. All the values for these properties can contain EL expression, which are resolved at runtime during process execution. The following properties could be set:

The following XML snippet shows an example of using the shell Task.

It runs shell script "cmd /c echo EchoTest", waits for it to be terminated and puts the result in resultVar

Compatibility note: After releasing 5.3, we discovered that execution listeners and task listeners and expressions were still in non-public API. Those classes were in subpackages of org.activiti.engine.impl…​, which has impl in it).

org.activiti.engine.impl.pvm.delegate.ExecutionListener, org.activiti.engine.impl.pvm.delegate.TaskListener and org.activiti.engine.impl.pvm.el.Expression have been deprecated. From now on, you should use org.activiti.engine.delegate.ExecutionListener, org.activiti.engine.delegate.TaskListener and org.activiti.engine.delegate.Expression. In the new publicly available API, access to ExecutionListenerExecution.getEventSource() has been removed. Apart from the deprecation compiler warning, the existing code should run fine. But consider switching to the new public API interfaces (without .impl. in the package name).

Execution listeners allow you to execute external Java code or evaluate an expression when certain events occur during process execution. The events that can be captured are:

The following process definition contains 3 execution listeners:

The first execution listener is notified when the process starts. The listener is an external Java-class (like ExampleExecutionListenerOne ) and should implement org.activiti.engine.delegate.ExecutionListener interface. When the event occurs (in this case end event) the method notify(ExecutionListenerExecution execution) is called.

You can also use a delegation class that implements the org.activiti.engine.delegate.JavaDelegate interface. These delegation classes can then be reused in other constructs, such as a delegation for a serviceTask.

The second execution listener is called when the transition is taken. Note that the listener element doesn’t define an event, since only take events are fired on transitions. Values in the event attribute are ignored when a listener is defined on a transition.

The last execution listener is called when activity secondTask ends. Instead of using the class on the listener declaration, a expression is defined instead which is evaluated/invoked when the event is fired.

As with other expressions, execution variables are resolved and can be used. Because the execution implementation object has a property that exposes the event name, it is possible to pass the event-name to your methods using execution.eventName.

Execution listeners also support using a delegateExpression, ?.

In Activiti 5.12 we also introduced a new type of execution listener, the org.activiti.engine.impl.bpmn.listener.ScriptExecutionListener. This script execution listener allows you to execute a piece of script logic for an execution listener event.

A task listener is used to execute custom Java logic or an expression upon the occurrence of a certain task-related event.

A task listener can only be added in the process definition as a child element of a ?. Note that this also must happen as a child of the BPMN 2.0 extensionElements and in the activiti namespace, since a task listener is an Activiti-specific construct.

A task listener supports following attributes:

A multi-instance activity lets you define repetition for a step in a business process.

In programming concepts, a multi-instance matches the for each construct: it allows to execute a certain step or even a complete sub-process for each item in a given collection, sequentially or in parallel.

A multi-instance is a regular activity that has extra properties defined, called multi-instance characteristics, which will cause the activity to be executed multiple times. The following activities can become a multi-instance activity:

A ? or ? can not become multi-instance.

As required by BPMN 2.0, each parent execution of the created executions for each instance will have following variables:

These values can be retrieved by calling the execution.getVariable(x) method.

Additionally, each of the created executions will have an execution-local variable (i.e. not visible for the other executions, and not stored on process instance level) :

If an activity is multi-instance, this is indicated by three short lines at the bottom of that activity.

Three vertical lines indicates that the instances will be executed in parallel, while three horizontal lines indicate sequential execution.

To make an activity multi-instance, the activity XML element must have a multiInstanceLoopCharacteristics child element.

The isSequential attribute indicates if the instances of that activity are executed sequentially or parallel.

The number of instances are calculated once, when entering the activity. There are a few ways of configuring this. On way is directly specifying a number, by using the loopCardinality child element.

Expressions that resolve to a positive number are can be used:

Another way to define the number of instances, is to specify the name of a process variable which is a collection using the loopDataInputRef child element. For each item in the collection, an instance will be created. Optionally, you can set that specific item of the collection for the instance using the inputDataItem child element. This is shown in the following XML example:

Suppose the variable assigneeList contains the values [kermit, gonzo, fozzie]. In the snippet above, three user tasks will be created in parallel. Each of the executions will have a process variable named assignee containing one value of the collection, which is used to assign the user task in this example.

The downside of the loopDataInputRef and inputDataItem is that 1) the names are pretty hard to remember and 2) due to the BPMN 2.0 schema restrictions they can’t contain expressions. Activiti solves this by offering the collection and elementVariable attributes on the multiInstanceCharacteristics:

A multi-instance activity ends when all instances are finished. However, you can specify an expression that is evaluated every time one instance ends. When this expression evaluates to true, all remaining instances are destroyed and the multi-instance activity ends, continuing the process. Such an expression must be defined in the completionCondition child element.

In this example, parallel instances are created for each element of the assigneeList collection. However, when 60% of the tasks are completed, the other tasks are deleted and the process continues.

Since a multi-instance is a regular activity, you can define a ? on its boundary. In case of an interrupting boundary event, when the event is caught, all instances that are still active will be destroyed. Take for example following multi-instance sub-process: Here, all instances of the sub-process will be destroyed when the timer fires, regardless of how many instances there are or which inner activities are currently not yet completed.

If an activity is used for compensating the effects of another activity, it can be declared to be a compensation handler. Compensation handlers are not contained in normal flow and are only executed when a compensation event is thrown.

Compensation handlers must not have incoming or outgoing sequence flows.

A compensation handler must be associated with a compensation boundary event using a directed association.

If an activity is a compensation handler, the compensation event icon is displayed in the center bottom area.

The following excerpt from a process diagram shows a service task with an attached compensation boundary event which is associated to a compensation handler. Notice the compensation handler icon in the bottom canter area of the "cancel hotel reservation" service task

A sub process is a single activity that contains activities, gateways, and events which form a process. A sub process is completely embedded inside a parent process.

You use can use a sub process in your process modeling to assist in the following cases:

Sub-processes in SkyVault Activiti must have the following characteristics:

Graphical notation.

One of the main reasons to use a sub process, is to define a scope for a certain event. The following process model shows an example of defining an event scope by using a sub process. Both the investigate software/investigate hardware tasks need to be done in parallel, but both tasks must be done within a certain time, before Level 2 support is consulted. Here, the scope of the timer is constrained by the sub process.

A sub process is defined by the sub-process element.

All activities, gateways, events, and other elements that are part of the sub process must be enclosed by this element.

An event sub-process is a sub-process that is triggered by an event. You can use an event sub-process in your main process, or in any sub-process.

The event sub-process start event defines the event to be handled by the sub-process, so the type of start event you use must have an event associated with it – none start events are not supported bt the event sub-processes. Your SkyVault Activiti event sub-process can be started by a start message event, or a start error event. The subscription to the start event is created when the scope, process instance or sub-process, hosting the event sub-process is created. The subscription is removed when the scope is destroyed.

a SkyVault Activiti event sub-process is interrupting. An interrupting sub-process cancels any executions in the current scope, and can only be triggered once for each activation of the scope hosting it.

Your event sub-process does not have any incoming or outgoing sequence flows. An event sub-process is triggered by an event, so there can be no incoming sequence flow. When a SkyVault Activiti event sub-process ends, the current scope also ends.

Graphical notation.

An event sub-process is represented using XML in the same way as an ? with the attribute triggeredByEvent set to true:

This is the event sub-process XML definition :

An event sub-process can also be added to an embedded sub-process. When added to an embedded sub-process, the event sub-process is an alternative to a boundary event. Consider these two process diagrams., in both cases the embedded sub-process throws an error event.The error is caught and handled using a user task.

as opposed to:

In both cases the same tasks are executed. However, there are some differences:

Consider these two differences when deciding if a boundary event or an embedded sub-process is better suited to any particular process modeling situation.

A transaction sub-process is an embedded sub-process, which can be used to group multiple activities to a transaction. A transaction is a logical unit of work which allows to group a set of individual activities, such that they either succeed or fail collectively.

Possible outcomes of a transaction: A transaction can have three different outcomes:

The following diagram illustrates the three different outcomes:

Relation to ACID transactions: it is important not to confuse theBPMNtransaction sub-process with technical (ACID) transactions. TheBPMNtransaction sub-process is not a way to scope technical transactions. In order to understand transaction management in Activiti, read the section on ?. ABPMNtransaction is different from a technical transaction in the following ways:

SinceBPMNtransactions are long-running in nature, the lack of isolation and a rollback mechanism need to be dealt with differently. In practice, there is usually no better solution than to deal with these problems in a domain specific way:

To sum it up: while ACID transactions offer a generic solution to such problems (rollback, isolation levels and heuristic outcomes), we need to find domain specific solutions to these problems when implementing business transactions.

Current limitations:

Consistency on top of ACID transactions and optimistic concurrency: ABPMNtransaction guarantees consistency in the sense that either all activities compete successfully, or if some activity cannot be performed, the effects of all other successful activities are compensated. So either way we end up in a consistent state. Note that in Activiti, the consistency model forBPMNtransactions is superposed on top of the consistency model for process execution. Activiti executes processes in a transactional way. Concurrency is addressed using optimistic locking. In Activiti,BPMNerror, cancel and compensation events are built on top of the same acid transactions and optimistic locking. For example, a cancel end event can only trigger compensation if it is actually reached. It is not reached if some undeclared exception is thrown by a service task before. Or, the effects of a compensation handler can not be committed if some other participant in the underlying ACID transaction sets the transaction to the state rollback-only. Or, when two concurrent executions reach a cancel end event, compensation might be triggered twice and fail with an optimistic locking exception. All of this is to say that when implementingBPMNtransactions in Activiti, the same set of rules apply as when implementing "ordinary" processes and subprocesses. So to effectively guarantee consistency, you should implement processes in a way that does take the optimistic, transactional execution model into consideration.

An transaction sub-process might be visualized as a an ? with a double outline.

A transaction sub-process is represented using XML using the transaction tag:

The following is an example of a transaction sub-process:

BPMN 2.0 makes a distinction between a regular sub-process , often also called embedded sub-process , and the call activity, which looks similar. From a conceptual point of view, both will call a sub-process when process execution arrives at the activity.

The difference is that the call activity references a process that is external to the process definition, whereas the ? is embedded within the original process definition. The main use case for the call activity is to have a reusable process definition that can be called from multiple other process definitions.

When process execution arrives in the call activity, a new execution is created that is a sub-execution of the execution that arrives in the call activity. This sub-execution is then used to execute the sub-process, potentially creating parallel child execution as within a regular process. The super-execution waits until the sub-process is completely ended, and continues the original process afterwards.

A call activity is visualized the same as a ?, but with a thick border (collapsed and expanded). Depending on the modeling tool, a call activity can also be expanded, but the default visualization is the collapsed sub-process representation.

A call activity is a regular activity, that requires a calledElement that references a process definition by its key.

In practice, this means that the id of the process is used in the calledElement.

Note that the process definition of the sub-process is resolved at runtime. This means that the sub-process can be deployed independently from the calling process.

You can pass process variables to the sub process and vice versa.

The data is copied into the sub-process when it is started and copied back into the main process when it ends.

We use an Activiti Extension as a shortcut for the BPMN standard elements called dataInputAssociation and dataOutputAssociation, which only work if you declare process variables in the BPMN 2.0 standard way.

You can use expressions here as well:

So in the end z = y+5 = x+5+5

The following process diagram shows a simple handling of an order.

Since the checking of the customer’s credit could be common to many other processes, the check credit step is modeled here as a call activity. The process looks as follows:

The sub-process looks as follows: There is nothing special to the process definition of the sub-process. It could as well be used without being called from another process.

Activiti executes processes in a transactional way which can be configured to suit your needs.

If you trigger Activiti by starting a process, completing a task, or signaling an execution, Activiti continue the process, until it reaches wait states on each active path of execution. A wait state is a task which is performed later, which means that Activiti persists the current execution and waits to be triggered again. The trigger can either come from an external source, for example, if we have a user task or a receive message task, or from Activiti itself, if we have a timer event. This is illustrated in the following diagram: There is a segment of a BPMN process with a user task, a service task, and a timer event. Completing the user task and validating the address is part of the same unit of work, so it should succeed or fail atomically. That means that if the service task throws an exception, we want to rollback the current transaction, such that the execution tracks back to the user task and the user task is still present in the database. This is the default behavior in Activiti. In (1) an application or client thread completes the task. In that same thread Activiti is now executing the service and advances until it reaches a wait state, in this case the timer event (2). Then it returns the control to the caller (3) potentially committing the transaction, if it was started by Activiti.

In some cases this is not what you want. Sometimes you need custom control over transaction boundaries in a process, in order to be able to scope logical units of work. This is where asynchronous continuations are useful. Consider the following process fragment: This time Activiti is completing the user task, generating an invoice and then sending that invoice to the customer. The generation of the invoice is not part of the same unit of work, so we do not want to rollback the completion of the user task if generating an invoice fails. So Activiti needs to complete the user task (1), commit the transaction and return the control to the calling application. Then it can generate the invoice asynchronously, in a background thread. This background thread is the Activiti job executor, actually a thread pool, which periodically polls the database for jobs. So internally, when the "generate invoice" task is reached, a job "message" is created for Activiti to continue the process later and persist it into the database. This job is then picked up by the job executor and executed. The local job executor given a hint that there is a new job, to improve performance.

In order to use this feature, you can use the activiti:async="true" extension. So for example, the service task would look like this:

activiti:async can be specified on the following BPMN task types: task, serviceTask, scriptTask, businessRuleTask, sendTask, receiveTask, userTask, subProcess, callActivity

On a userTask, receiveTask or other wait states, asynchronous continuations allow Activiti to execute the start execution listeners in a separate thread/transaction.

Activiti, in its default configuration, reruns a job 3 times in case of any exception in execution of a job.

This holds also for asynchronous task jobs. In some cases more flexibility is required. There are two parameters to be configured:

These parameters can be configured by activiti:failedJobRetryTimeCycle element. Here is a sample usage:

Time cycle expression follows ISO 8601 standard, just like timer event expressions. The above example, makes the job executor to retry the job 5 times and wait 7 minutes between before each retry.

An exclusive job cannot be performed at the same time as another exclusive job from the same process instance.

If you declare tasks to be exclusive, the JobExecutor will ensure that whenever it acquires an exclusive job from a specific process instance, it acquires all other exclusive jobs from that process instance, and delegates them to the same worker thread. This ensures sequential execution.

Exclusive jobs are specified in the default configuration. All asynchronous continuations and timer events are therefore exclusive by default. If you require a job to be non-exclusive, you can configure it using activiti:exclusive="false". For example, the following service task is asynchronous but non-exclusive.

Consider the following process definition:

There is a parallel gateway followed by three service tasks which all perform an asynchronous continuation. Three jobs are added to the database. Once such a job is present in the database it can be processed by the JobExecutor. The JobExecutor acquires the jobs and delegates them to a thread pool of worker threads. This means that using an asynchronous continuation, you can distribute the work to this thread pool (and in a clustered scenario even across multiple thread pools in the cluster). This scheme has an inherent problem: consistency. Consider the parallel join after the service tasks. When execution of a service task is completed, we arrive at the parallel join and need to decide whether to wait for the other executions or whether to continue. For each branch arriving at the parallel join, a decision is required on whether to continue or to wait for one or more other executions from the other branches.

Since the service tasks are configured using an asynchronous continuation, it is possible that the corresponding jobs are all acquired at the same time and delegated to different worker threads by the JobExecutor. The means that the transactions in which the services are executed, and in which the three individual executions arrive at the parallel join can overlap. If they do so, each individual transaction will not see that another transaction is arriving at the same parallel join concurrently and thus assume that it has to wait for the others. However, if each transaction assumes that it has to wait for the other ones, none will continue the process after the parallel join and the process instance will remain in that state forever.

To address this, Activiti performs optimistic locking. Whenever a decision is made based on data that might not be current, because another transaction might modify it before we commit, Activiti increments the version of the same database row in both transactions. This means whichever transaction commits first, wins, and the other ones fail with an optimistic locking exception. This solves the problem in the case of the process discussed above: if multiple executions arrive at the parallel join concurrently, they all assume that they have to wait, increment the version of their parent execution (the process instance) and then try to commit. Whichever execution is first will be able to commit and the other ones will fail with an optimistic locking exception. Since the executions are triggered by a job, Activiti will retry to perform the same job after waiting for a certain amount of time and try to pass the synchronizing gateway.

Optimistic locking allows Activiti to prevent inconsistencies. It makes sure that jobs do not get stuck at a joining gateway. Either all executions have passed the gateway or, there are jobs in the database that retry passing it. This is a solution to the problem of persistence and consistency, but might not be the required behavior at an higher level: