Activiti 5.15 User Guide


Table of Contents

1. Introduction
License
Download
Sources
Required software
JDK 6+
Eclipse Indigo and Juno
Reporting problems
Experimental features
Internal implementation classes
2. Getting Started
One minute version
Activiti setup
Activiti database setup
Include the Activiti jar and its dependencies
Next steps
3. Configuration
Creating a ProcessEngine
ProcessEngineConfiguration bean
Database configuration
Supported databases
Creating the database tables
Database table names explained
Database upgrade
Job executor activation
Mail server configuration
History configuration
Exposing configuration beans in expressions and scripts
Deployment cache configuration
Logging
Mapped Diagnostic Contexts
Event handlers
Event listener implementation
Configuration and setup
Adding listeners at runtime
Adding listeners to process definitions
Dispatching events through API
Supported event types
Additional remarks
4. The Activiti API
The Process Engine API and services
Exception strategy
Working with the Activiti services
Deploying the process
Starting a process instance
Completing tasks
Suspending and activating a process
Further reading
Query API
Expressions
Unit testing
Debugging unit tests
The process engine in a web application
5. Spring integration
ProcessEngineFactoryBean
Transactions
Expressions
Automatic resource deployment
Unit testing
Annotation-based configuration
JPA with Hibernate 4.2.x
6. Deployment
Business archives
Deploying programmatically
Deploying with Activiti Explorer
External resources
Java classes
Using Spring beans from a process
Creating a single app
Versioning of process definitions
Providing a process diagram
Generating a process diagram
Category
7. BPMN 2.0 Introduction
What is BPMN?
Defining a process
Getting started: 10 minute tutorial
Prerequisites
Goal
Use case
Process diagram
XML representation
Starting a process instance
Task lists
Claiming the task
Completing the task
Ending the process
Code overview
Future enhancements
8. BPMN 2.0 Constructs
Custom extensions
Events
Event Definitions
Timer Event Definitions
Error Event Definitions
Signal Event Definitions
Message Event Definitions
Start Events
None Start Event
Timer Start Event
Message Start Event
Signal Start Event
Error Start Event
End Events
None End Event
Error End Event
Cancel End Event
Boundary Events
Timer Boundary Event
Error Boundary Event
Signal Boundary Event
Message Boundary Event
Cancel Boundary Event
Compensation Boundary Event
Intermediate Catching Events
Timer Intermediate Catching Event
Signal Intermediate Catching Event
Message Intermediate Catching Event
Intermediate Throwing Event
Intermediate Throwing None Event
Signal Intermediate Throwing Event
Compensation Intermediate Throwing Event
Sequence Flow
Description
Graphical notation
XML representation
Conditional sequence flow
Default sequence flow
Gateways
Exclusive Gateway
Parallel Gateway
Inclusive Gateway
Event-based Gateway
Tasks
User Task
Script Task
Java Service Task
Web Service Task
Business Rule Task
Email Task
Mule Task
Camel Task
Manual Task
Java Receive Task
Shell Task
Execution listener
Task listener
Multi-instance (for each)
Compensation Handlers
Sub-Processes and Call Activities
Sub-Process
Event Sub-Process
Transaction subprocess
Call activity (subprocess)
Transactions and Concurrency
Asynchronous Continuations
Exclusive Jobs
Process Initiation Authorization
Data objects
9. Forms
Form properties
External form rendering
10. JPA
Requirements
Configuration
Usage
Simple Example
Query JPA process variables
Advanced example using Spring beans and JPA
11. History
Querying history
HistoricProcessInstanceQuery
HistoricVariableInstanceQuery
HistoricActivityInstanceQuery
HistoricDetailQuery
HistoricTaskInstanceQuery
History configuration
History for audit purposes
12. Eclipse Designer
Installation
Activiti Designer editor features
Activiti Designer BPMN features
Activiti Designer deployment features
Extending Activiti Designer
Customizing the palette
Validating diagrams and exporting to custom output formats
13. Activiti Explorer
Process diagram
Tasks
Start process instances
My instances
Administration
Reporting
Report data JSON
Example process
Report start forms
Example processes
Changing the database
14. Activiti Modeler
Model editing
Importing existing models
Convert deployed definitions to a editeable model
Export model to BPMN XML
Deploy model to the Activiti Engine
15. REST API
General Activiti REST principles
Installation and Authentication
Usage in Tomcat
Methods and return-codes
Error response body
Request parameters
Deployment
List of Deployments
Get a deployment
Create a new deployment
Delete a deployment
List resources in a deployment
Get a deployment resource
Get a deployment resource content
Process Definitions
List of process definitions
Get a process definition
Update category for a process definition
Get a process definition resource content
Get a process definition BPMN model
Suspend a process definition
Activate a process definition
Get all candidate starters for a process-definition
Add a candidate starter to a process definition
Delete a candidate starter from a process definition
Get a candidate starter from a process definition
Models
Get a list of models
Get a model
Update a model
Create a model
Delete a model
Get the editor source for a model
Set the editor source for a model
Get the extra editor source for a model
Set the extra editor source for a model
Process Instances
Get a process instance
Delete a process instance
Activate or suspend a process instance
Start a process instance
List of process instances
Query process instances
Get diagram for a process instance
Get involved people for process instance
Add an involved user to a process instance
Remove an involved user to from process instance
List of variables for a process instance
Get a variable for a process instance
Create (or update) variables on a process instance
Update a single variable on a process instance
Create a new binary variable on a process-instance
Update an existing binary variable on a process-instance
Executions
Get an execution
Execute an action on an execution
Get active activities in an execution
List of executions
Query executions
List of variables for an execution
Get a variable for an execution
Create (or update) variables on an execution
Update a variable on an execution
Create a new binary variable on an execution
Update an existing binary variable on a process-instance
Tasks
Get a task
List of tasks
Query for tasks
Update a task
Task actions
Delete a task
Get all variables for a task
Get a variable from a task
Get the binary data for a variable
Create new variables on a task
Create a new binary variable on a task
Update an existing variable on a task
Updating a binary variable on a task
Delete a variable on a task
Delete all local variables on a task
Get all identity links for a task
Get all identitylinks for a task for either groups or users
Get a single identity link on a task
Create an identity link on a task
Delete an identity link on a task
Create a new comment on a task
Get all comments on a task
Get a comment on a task
Delete a comment on a task
Get all events for a task
Get an event on a task
Create a new attachment on a task, containing a link to an external resource
Create a new attachment on a task, with an attached file
Get all attachments on a task
Get an attachment on a task
Get the content for an attachment
Delete an attachment on a task
History
Get a historic process instance
List of historic process instances
Query for historic process instances
Delete a historic process instance
Get the identity links of a historic process instance
Get the binary data for a historic process instance variable
Create a new comment on a historic process instance
Get all comments on a historic process instance
Get a comment on a historic process instance
Delete a comment on a historic process instance
Get a single historic task instance
Get historic task instances
Query for historic task instances
Delete a historic task instance
Get the identity links of a historic task instance
Get the binary data for a historic task instance variable
Get historic activity instances
Query for historic activity instances
List of historic variable instances
Query for historic variable instances
Get the binary data for a historic task instance variable
Get historic detail
Query for historic details
Get the binary data for a historic detail variable
Forms
Get form data
Submit task form data
Database tables
List of tables
Get a single table
Get column info for a single table
Get row data for a single table
Engine
Get engine properties
Get engine info
Runtime
Signal event received
Jobs
Get a single job
Delete a job
Execute a single job
Get the exception stacktrace for a job
Get a list of jobs
Users
Get a single user
Get a list of users
Update a user
Create a user
Delete a user
Get a user's picture
Updating a user's picture
List a user's info
Get a user's info
Update a user's info
Create a new user's info entry
Delete a user's info
Groups
Get a single group
Get a list of groups
Update a group
Create a group
Delete a group
Get members in a group
Add a member to a group
Delete a member from a group
Legacy REST - General Usage
Repository
Upload Deployment
Get Deployments
Get Deployment Resources
Get Deployment Resource
Delete Deployment
Delete Deployments
Engine
Get Process Engine
Processes
List Process Definitions
Get Process Definition Form Properties
Get Process Definition Form Resource
Get Process Definition Diagram
Start Process Instance
List Process Instances
Get Process Instance Details
Get Process Instance Diagram
Get open tasks for a process instance
Signal an activity (receive task) for a specific process instance
Trigger a signal for a specific process instance
Tasks
Get Task Summary
List Tasks
Get Task
Get Task Form
Perform Task Operation
List Form Properties
Add attachment to a task
Get task attachment
Add url to a task
Identity
Login
Get User
List User's Groups
Search users
Create user
Add user to groups
Remove user from group
Get user picture
Get Group
List Group Users
Search groups
Create group
Add users to a group
Remove user from group
Management
List Jobs
Get Job
Execute Job
Execute Jobs
List Database Tables
Get Table Meta Data
Get Table Data
16. CDI integration
Setting up activiti-cdi
Looking up a Process Engine
Configuring the Process Engine
Deploying Processes
Contextual Process Execution with CDI
Associating a Conversation with a Process Instance
Declaratively controlling the Process
Referencing Beans from the Process
Working with @BusinessProcessScoped beans
Injecting Process Variables
Receiving Process Events
Additional Features
Known Limitations
17. LDAP integration
Usage
Use cases
Configuration
Properties
Integrate LDAP in Explorer
18. Advanced
Hooking into process parsing
UUID id generator for high concurrency
Multitenancy
Execute custom SQL
Advanced Process Engine configuration with a ProcessEngineConfigurator
Enable safe BPMN 2.0 xml

List of Tables

2.1. The demo users
2.2. The webapp tools
3.1. Supported databases
3.2. Supported events
6.1.
6.2.
6.3.
8.1. Mail server configuration
8.2. Mail server configuration
8.3. Mule server configuration
8.4. Endpoint URL parts:
8.5. Existing camel behaviours:
8.6. Existing camel behaviours:
8.7. Shell task parameter configuration
15.1. HTTP-methods and corresponding operations
15.2. HTTP-methods response codes
15.3. URL query parameter types
15.4. JSON parameter types
15.5. Variable query JSON parameters
15.6. Variable query JSON parameters
15.7. Default query JSON types
15.8. Variable JSON attributes
15.9. Variable Types
15.10. URL query parameters
15.11. REST Response codes
15.12. Get a deployment - URL parameters
15.13. Get a deployment - Response codes
15.14. Create a new deployment - Response codes
15.15. Delete a deployment - URL parameters
15.16. Delete a deployment - Response codes
15.17. List resources in a deployment - URL parameters
15.18. List resources in a deployment - Response codes
15.19. Get a deployment resource - URL parameters
15.20. Get a deployment resource - Response codes
15.21. Get a deployment resource content - URL parameters
15.22. Get a deployment resource content - Response codes
15.23. List of process definitions - URL parameters
15.24. List of process definitions - Response codes
15.25. Get a process definition - URL parameters
15.26. Get a process definition - Response codes
15.27. Update category for a process definition - Response codes
15.28. Get a process definition resource content - URL parameters
15.29. Get a process definition BPMN model - URL parameters
15.30. Get a process definition BPMN model - Response codes
15.31. Suspend a process definition - JSON Body parameters
15.32. Suspend a process definition - Response codes
15.33. Activate a process definition - Response codes
15.34. Get all candidate starters for a process-definition - URL parameters
15.35. Get all candidate starters for a process-definition - Response codes
15.36. Add a candidate starter to a process definition - URL parameters
15.37. Add a candidate starter to a process definition - Response codes
15.38. Delete a candidate starter from a process definition - URL parameters
15.39. Delete a candidate starter from a process definition - Response codes
15.40. Get a candidate starter from a process definition - URL parameters
15.41. Get a candidate starter from a process definition - Response codes
15.42. Get a list of models - URL query parameters
15.43. Get a list of models - Response codes
15.44. Get a model - URL parameters
15.45. Get a model - Response codes
15.46. Update a model - Response codes
15.47. Create a model - Response codes
15.48. Delete a model - URL parameters
15.49. Delete a model - Response codes
15.50. Get the editor source for a model - URL parameters
15.51. Get the editor source for a model - Response codes
15.52. Set the editor source for a model - URL parameters
15.53. Set the editor source for a model - Response codes
15.54. Get the extra editor source for a model - URL parameters
15.55. Get the extra editor source for a model - Response codes
15.56. Set the extra editor source for a model - URL parameters
15.57. Set the extra editor source for a model - Response codes
15.58. Get a process instance - URL parameters
15.59. Get a process instance - Response codes
15.60. Delete a process instance - URL parameters
15.61. Delete a process instance - Response codes
15.62. Activate or suspend a process instance - URL parameters
15.63. Activate or suspend a process instance - Response codes
15.64. Start a process instance - Response codes
15.65. List of process instances - URL query parameters
15.66. List of process instances - Response codes
15.67. Query process instances - Response codes
15.68. Get diagram for a process instance - URL parameters
15.69. Get diagram for a process instance - Response codes
15.70. Get involved people for process instance - URL parameters
15.71. Get involved people for process instance - Response codes
15.72. Add an involved user to a process instance - URL parameters
15.73. Add an involved user to a process instance - Response codes
15.74. Remove an involved user to from process instance - URL parameters
15.75. Remove an involved user to from process instance - Response codes
15.76. List of variables for a process instance - URL parameters
15.77. List of variables for a process instance - Response codes
15.78. Get a variable for a process instance - URL parameters
15.79. Get a variable for a process instance - Response codes
15.80. Create (or update) variables on a process instance - URL parameters
15.81. Create (or update) variables on a process instance - Response codes
15.82. Update a single variable on a process instance - URL parameters
15.83. Update a single variable on a process instance - Response codes
15.84. Create a new binary variable on a process-instance - URL parameters
15.85. Create a new binary variable on a process-instance - Response codes
15.86. Update an existing binary variable on a process-instance - URL parameters
15.87. Update an existing binary variable on a process-instance - Response codes
15.88. Get an execution - URL parameters
15.89. Get an execution - Response codes
15.90. Execute an action on an execution - URL parameters
15.91. Execute an action on an execution - Response codes
15.92. Get active activities in an execution - URL parameters
15.93. Get active activities in an execution - Response codes
15.94. List of executions - URL query parameters
15.95. List of executions - Response codes
15.96. Query executions - Response codes
15.97. List of variables for an execution - URL parameters
15.98. List of variables for an execution - Response codes
15.99. Get a variable for an execution - URL parameters
15.100. Get a variable for an execution - Response codes
15.101. Create (or update) variables on an execution - URL parameters
15.102. Create (or update) variables on an execution - Response codes
15.103. Update a variable on an execution - URL parameters
15.104. Update a variable on an execution - Response codes
15.105. Create a new binary variable on an execution - URL parameters
15.106. Create a new binary variable on an execution - Response codes
15.107. Update an existing binary variable on a process-instance - URL parameters
15.108. Update an existing binary variable on a process-instance - Response codes
15.109. Get a task - URL parameters
15.110. Get a task - Response codes
15.111. List of tasks - URL query parameters
15.112. List of tasks - Response codes
15.113. Query for tasks - Response codes
15.114. Update a task - Response codes
15.115. Task actions - Response codes
15.116. >Delete a task - URL parameters
15.117. >Delete a task - Response codes
15.118. Get all variables for a task - URL parameters
15.119. Get all variables for a task - Response codes
15.120. Get a variable from a task - URL parameters
15.121. Get a variable from a task - Response codes
15.122. Get the binary data for a variable - URL parameters
15.123. Get the binary data for a variable - Response codes
15.124. Create new variables on a task - URL parameters
15.125. Create new variables on a task - Response codes
15.126. Create a new binary variable on a task - URL parameters
15.127. Create a new binary variable on a task - Response codes
15.128. Update an existing variable on a task - URL parameters
15.129. Update an existing variable on a task - Response codes
15.130. Updating a binary variable on a task - URL parameters
15.131. Updating a binary variable on a task - Response codes
15.132. Delete a variable on a task - URL parameters
15.133. Delete a variable on a task - Response codes
15.134. Delete all local variables on a task - URL parameters
15.135. Delete all local variables on a task - Response codes
15.136. Get all identity links for a task - URL parameters
15.137. Get all identity links for a task - Response codes
15.138. Get all identitylinks for a task for either groups or users - URL parameters
15.139. Get all identitylinks for a task for either groups or users - Response codes
15.140. Create an identity link on a task - URL parameters
15.141. Create an identity link on a task - Response codes
15.142. Delete an identity link on a task - URL parameters
15.143. Delete an identity link on a task - Response codes
15.144. Create a new comment on a task - URL parameters
15.145. Create a new comment on a task - Response codes
15.146. Get all comments on a task - URL parameters
15.147. Get all comments on a task - Response codes
15.148. Get a comment on a task - URL parameters
15.149. Get a comment on a task - Response codes
15.150. Delete a comment on a task - URL parameters
15.151. Delete a comment on a task - Response codes
15.152. Get all events for a task - URL parameters
15.153. Get all events for a task - Response codes
15.154. Get an event on a task - URL parameters
15.155. Get an event on a task - Response codes
15.156. Create a new attachment on a task, containing a link to an external resource - URL parameters
15.157. Create a new attachment on a task, containing a link to an external resource - Response codes
15.158. Create a new attachment on a task, with an attached file - URL parameters
15.159. Create a new attachment on a task, with an attached file - Response codes
15.160. Get all attachments on a task - URL parameters
15.161. Get all attachments on a task - Response codes
15.162. Get an attachment on a task - URL parameters
15.163. Get an attachment on a task - Response codes
15.164. Get the content for an attachment - URL parameters
15.165. Get the content for an attachment - Response codes
15.166. Delete an attachment on a task - URL parameters
15.167. Delete an attachment on a task - Response codes
15.168. Get a historic process instance - Response codes
15.169. List of historic process instances - URL parameters
15.170. List of historic process instances - Response codes
15.171. Query for historic process instances - Response codes
15.172. Response codes
15.173. Response codes
15.174. Get the binary data for a historic process instance variable - Response codes
15.175. Create a new comment on a historic process instance - URL parameters
15.176. Create a new comment on a historic process instance - Response codes
15.177. Get all comments on a process instance - URL parameters
15.178. Get all comments on a process instance - Response codes
15.179. Get a comment on a historic process instance - URL parameters
15.180. Get a comment on a historic process instance - Response codes
15.181. Delete a comment on a historic process instance - URL parameters
15.182. Delete a comment on a historic process instance - Response codes
15.183. Get a single historic task instance - Response codes
15.184. Get historic task instances - URL parameters
15.185. Get historic task instances - Response codes
15.186. Query for historic task instances - Response codes
15.187. Response codes
15.188. Response codes
15.189. Get the binary data for a historic task instance variable - Response codes
15.190. Get historic activity instances - URL parameters
15.191. Get historic activity instances - Response codes
15.192. Query for historic activity instances - Response codes
15.193. List of historic variable instances - URL parameters
15.194. List of historic variable instances - Response codes
15.195. Query for historic variable instances - Response codes
15.196. Get the binary data for a historic task instance variable - Response codes
15.197. Get historic detail - URL parameters
15.198. Get historic detail - Response codes
15.199. Query for historic details - Response codes
15.200. Get the binary data for a historic detail variable - Response codes
15.201. Get form data - URL parameters
15.202. Get form data - Response codes
15.203. Submit task form data - Response codes
15.204. List of tables - Response codes
15.205. Get a single table - URL parameters
15.206. Get a single table - Response codes
15.207. Get column info for a single table - URL parameters
15.208. Get column info for a single table - Response codes
15.209. Get row data for a single table - URL parameters
15.210. Get row data for a single table - URL query parameters
15.211. Get row data for a single table - Response codes
15.212. Get engine properties - Response codes
15.213. Get engine info - Response codes
15.214. Signal event received - JSON Body parameters
15.215. Signal event received - Response codes
15.216. Get a single job - URL parameters
15.217. Get a single job - Response codes
15.218. Delete a job - URL parameters
15.219. Delete a job - Response codes
15.220. Execute a single job - JSON Body parameters
15.221. Execute a single job - Response codes
15.222. Get the exception stacktrace for a job - URL parameters
15.223. Get the exception stacktrace for a job - Response codes
15.224. Get a list of jobs - URL query parameters
15.225. Get a list of jobs - Response codes
15.226. Get a single user - URL parameters
15.227. Get a single user - Response codes
15.228. Get a list of users - URL query parameters
15.229. Get a list of users - Response codes
15.230. Update a user - Response codes
15.231. Create a user - Response codes
15.232. Delete a user - URL parameters
15.233. Delete a user - Response codes
15.234. Get a user's picture - URL parameters
15.235. Get a user's picture - Response codes
15.236. Updating a user's picture - URL parameters
15.237. Updating a user's picture - Response codes
15.238. List a user's info - URL parameters
15.239. List a user's info - Response codes
15.240. Get a user's info - URL parameters
15.241. Get a user's info - Response codes
15.242. Update a user's info - URL parameters
15.243. Update a user's info - Response codes
15.244. Create a new user's info entry - URL parameters
15.245. Create a new user's info entry - Response codes
15.246. Delete a user's info - URL parameters
15.247. Delete a user's info - Response codes
15.248. Get a single group - URL parameters
15.249. Get a single group - Response codes
15.250. Get a list of groups - URL query parameters
15.251. Get a list of groups - Response codes
15.252. Update a group - Response codes
15.253. Create a group - Response codes
15.254. Delete a group - URL parameters
15.255. Delete a group - Response codes
15.256. Add a member to a group - URL parameters
15.257. Add a member to a group - Response codes
15.258. Delete a member from a group - URL parameters
15.259. Delete a member from a group - Response codes
17.1. LDAP configuration properties
17.2. Advanced properties

Chapter 1. Introduction

License

Activiti is distributed under the Apache V2 license.

Sources

The distribution contains most of the sources as jar files. To find and build the full source codebase, please read the 'Building the distribution' wiki page

Required software

JDK 6+

Activiti runs on a JDK higher than or equal to version 6. Go to Oracle Java SE downloads and click on button "Download JDK". There are installation instructions on that page as well. To verify that your installation was successful, run java -version on the command line. That should print the installed version of your JDK.

Eclipse Indigo and Juno

Download the the eclipse distribution of your choice from the Eclipse download page. Unzip the downloaded file and then you should be able to start it with the eclipse file in the directory eclipse. Further in this user guide, there is a section on installing our eclipse designer plugin.

Reporting problems

Every self-respecting developer should have read How to ask questions the smart way.

After you've done that you can post questions and comments on the Users forum and create issues in our JIRA issue tracker.

Note

Even though Activiti is hosted on GitHub, issues should not be reported using GitHub's issue system. If you wish to report an issue, do not create a GitHub issue, but use JIRA.

Experimental features

Sections marked with [EXPERIMENTAL] should not be considered stable.

All classes that have .impl. in the package name are internal implementation classes and can not be considered stable. However, if the user guide mentions those classes as configuration values, they are supported and can be considered stable.

Internal implementation classes

In the jar file, all classes in packages that have .impl. (e.g. org.activiti.engine.impl.pvm.delegate) in them are implementation classes and should be considered internal. No stability guarantees are given on classes or interfaces that are in implementation classes.

Chapter 2. Getting Started

One minute version

After downloading the Activiti Explorer WAR file from the Activiti website, follow these steps to get the demo setup running with default settings. You'll need a working Java runtime and Apache Tomcat installation (actually, any web container would work since we only rely on the servlet capability. But we test on Tomcat primarily).

  • Copy the downloaded activiti-explorer.war to the webapps directory of Tomcat.

  • Start Tomcat by running the startup.bat or startup.sh scripts in the bin folder of Tomcat

  • When Tomcat is started open your browser and go to http://localhost:8080/activiti-explorer. Login with kermit/kermit.

That's it! The Activiti Explorer application uses an in-memory H2 database by default, if you want to use another database configuration please read the longer version.

Activiti setup

To install Activiti you'll need a working Java runtime and Apache Tomcat installation. Also make sure that the JAVA_HOME system variable is correctly set. The way to do this depends on your operating system.

To get the Activiti Explorer and REST web applications running just copy the WARs downloaded from the Activiti download page to the webapps folder in your Tomcat installation directory. By default the Explorer application runs with an in-memory database and with example processes, users and groups.

These are the demo users:

Table 2.1. The demo users

UserIdPasswordSecurity roles
kermitkermitadmin
gonzogonzomanager
fozziefozzieuser

Now you can access following web application:

Table 2.2. The webapp tools

Webapp NameURLDescription 
Activiti Explorerhttp://localhost:8080/activiti-explorer The process engine user console. Use this tool to start new processes, assign tasks, view and claim tasks, etc. This tool also allows to administrate the Activiti engine.  

Note that the Activiti Explorer demo setup is a way of showing the capabilities and functionality of Activiti as easily and as fast as possible. This does however, not mean that it is the only way of using Activiti. As Activiti is 'just a jar', it can be embedded in any Java environment: with swing or on a Tomcat, JBoss, WebSphere, etc. Or you could very well choose to run Activiti as a typical, standalone BPM server. If it is possible in Java, it is possible with Activiti!

Activiti database setup

As said in the one minute demo setup, the Activiti Explorer runs an in-memory H2 database by default. To run the Activiti Explorer with a standalone H2 or another database the db.properties in the WEB-INF/classes of the Activiti Explorer web application should be changed.

In addition, be aware that the Activiti Explorer generates demo user and groups, process definitions and models by default. To disable this, the activiti-standalone-context.xml file in the WEB-INF folder should be changed. To disable the demo setup fully you can use the following snippet of the demoDataGenerator bean definition. But as you can see you can also enable and disable items individually.

      <bean id="demoDataGenerator" class="org.activiti.explorer.demo.DemoDataGenerator">
        <property name="processEngine" ref="processEngine" />
        <property name="createDemoUsersAndGroups" value="false" />
        <property name="createDemoProcessDefinitions" value="false" />
        <property name="createDemoModels" value="false" />
      </bean>
    

Include the Activiti jar and its dependencies

To include the Activiti jar and its dependent libraries, we advise using Maven (or Ivy), as it simplifies dependency management on both our and your side a lot. Follow the instructions at http://www.activiti.org/community.html#maven.repository to include the necessary jars in your environment.

Alternatively, if you don't want to use Maven you can include the jars in your project yourself. The Activiti download zip contains a folder libs which contain all the Activiti jars (and the source jars). The dependencies are not shipped this way. The required dependencies of the Activiti engine are (generated using mvn dependency:tree):

org.activiti:activiti-engine:jar:5.12.1
+- org.apache.commons:commons-email:jar:1.2:compile
|  +- javax.mail:mail:jar:1.4.1:compile
|  \- javax.activation:activation:jar:1.1:compile
+- org.apache.commons:commons-lang3:jar:3.1:compile
+- org.mybatis:mybatis:jar:3.1.1:compile
+- org.springframework:spring-beans:jar:3.1.2.RELEASE:compile
|  \- org.springframework:spring-core:jar:3.1.2.RELEASE:compile
|     +- org.springframework:spring-asm:jar:3.1.2.RELEASE:compile
|     \- commons-logging:commons-logging:jar:1.1.1:compile
\- joda-time:joda-time:jar:2.1:compile       
       

Note: the mail jars are only needed if you are using the mail service task.

All the dependencies can easily be downloaded using mvn dependency:copy-dependencies on a module of the Activiti source code.

Next steps

Playing around with the Activiti Explorer web application is a good way to get familiar with the Activiti concepts and functionality. However, the main purpose of Activiti is of course to enable powerful BPM and workflow capabilities in your own application. The following chapters will help you to get familiar with how to use Activiti programmatically in your environment:

  • The chapter on configuration will teach you how to set up Activiti and how to obtain an instance of the ProcessEngine class which is your central access point to all the engine functionality of Activiti.

  • The API chapter will guide you through the services which form Activiti's API. These services offer the Activiti engine functionality in a convenient yet powerful way and can be used in any Java environment.

  • Interested in getting insight on BPMN 2.0, the format in which processes for the Activiti engine are written? Then continue on to the BPMN 2.0 section.

Chapter 3. Configuration

Creating a ProcessEngine

The Activiti process engine is configured through an XML file called activiti.cfg.xml. Note that this is not applicable if you're using the Spring style of building a process engine.

The easiest way to obtain a ProcessEngine, is to use the org.activiti.engine.ProcessEngines class:

ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine()

This will look for an activiti.cfg.xml file on the classpath and construct an engine based on the configuration in that file. The following snippet shows an example configuration. The following sections will give a detailed overview of the configuration properties.

<beans xmlns="http://www.springframework.org/schema/beans" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans   http://www.springframework.org/schema/beans/spring-beans.xsd">

  <bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration">
  
    <property name="jdbcUrl" value="jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000" />
    <property name="jdbcDriver" value="org.h2.Driver" />
    <property name="jdbcUsername" value="sa" />
    <property name="jdbcPassword" value="" />
    
    <property name="databaseSchemaUpdate" value="true" />
    
    <property name="jobExecutorActivate" value="false" />
    
    <property name="mailServerHost" value="mail.my-corp.com" /> 
    <property name="mailServerPort" value="5025" />    
  </bean>

</beans>

Note that the configuration XML is in fact a Spring configuration. This does not mean that Activiti can only be used in a Spring environment! We are simply leveraging the parsing and dependency injection capabilities of Spring internally for building up the engine.

The ProcessEngineConfiguration object can also be created programmatically using the configuration file. It is also possible to use a different bean id (e.g. see line 3).

ProcessEngineConfiguration.createProcessEngineConfigurationFromResourceDefault();
ProcessEngineConfiguration.createProcessEngineConfigurationFromResource(String resource);
ProcessEngineConfiguration.createProcessEngineConfigurationFromResource(String resource, String beanName);
ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(InputStream inputStream);
ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(InputStream inputStream, String beanName);

It is also possible not to use a configuration file, and create a configuration based on defaults (see the different supported classes for more information).

ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration();
ProcessEngineConfiguration.createStandaloneInMemProcessEngineConfiguration();

All these ProcessEngineConfiguration.createXXX() methods return a ProcessEngineConfiguration that can further be tweaked if needed. After calling the buildProcessEngine() operation, a ProcessEngine is created:

ProcessEngine processEngine = ProcessEngineConfiguration.createStandaloneInMemProcessEngineConfiguration()
  .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_FALSE)
  .setJdbcUrl("jdbc:h2:mem:my-own-db;DB_CLOSE_DELAY=1000")
  .setJobExecutorActivate(true)
  .buildProcessEngine();

ProcessEngineConfiguration bean

The activiti.cfg.xml must contain a bean that has the id 'processEngineConfiguration'.

 <bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration">

This bean is then used to construct the ProcessEngine. There are multiple classes available that can be used to define the processEngineConfiguration. These classes represent different environments, and set defaults accordingly. It's a best practice to select the class the matches (the most) your environment, to minimalise the number of properties needed to configure the engine. The following classes are currently available (more will follow in future releases):

  • org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration: the process engine is used in a standalone way. Activiti will take care of the transactions. By default, the database will only be checked when the engine boots (and an exception is thrown if there is no Activiti schema or the schema version is incorrect).

  • org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration: this is a convenience class for unit testing purposes. Activiti will take care of the transactions. An H2 in-memory database is used by default. The database will be created and dropped when the engine boots and shuts down. When using this, probably no additional configuration is needed (except when using for example the job executor or mail capabilities).

  • org.activiti.spring.SpringProcessEngineConfiguration: To be used when the process engine is used in a Spring environment. See the Spring integration section for more information.

  • org.activiti.engine.impl.cfg.JtaProcessEngineConfiguration: To be used when the engine runs in standalone mode, with JTA transactions.

Database configuration

There are two ways to configure the database that the Activiti engine will use. The first option is to define the JDBC properties of the database:

  • jdbcUrl: JDBC URL of the database.

  • jdbcDriver: implementation of the driver for the specific database type.

  • jdbcUsername: username to connect to the database.

  • jdbcPassword: password to connect to the database.

The data source that is constructed based on the provided JDBC properties will have the default MyBatis connection pool settings. The following attributes can optionally be set to tweak that connection pool (taken from the MyBatis documentation):

  • jdbcMaxActiveConnections: The number of active connections that the connection pool at maximum at any time can contain. Default is 10.

  • jdbcMaxIdleConnections: The number of idle connections that the connection pool at maximum at any time can contain.

  • jdbcMaxCheckoutTime: The amount of time in milliseconds a connection can be 'checked out' from the connection pool before it is forcefully returned. Default is 20000 (20 seconds).

  • jdbcMaxWaitTime: This is a low level setting that gives the pool a chance to print a log status and re-attempt the acquisition of a connection in the case that it’s taking unusually long (to avoid failing silently forever if the pool is misconfigured) Default is 20000 (20 seconds).

Example database configuration:

<property name="jdbcUrl" value="jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000" />
<property name="jdbcDriver" value="org.h2.Driver" />
<property name="jdbcUsername" value="sa" />
<property name="jdbcPassword" value="" />
      

Alternatively, a javax.sql.DataSource implementation can be used (e.g. DBCP from Apache Commons):

<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" >
  <property name="driverClassName" value="com.mysql.jdbc.Driver" />
  <property name="url" value="jdbc:mysql://localhost:3306/activiti" />
  <property name="username" value="activiti" />
  <property name="password" value="activiti" />
  <property name="defaultAutoCommit" value="false" />
</bean>      

<bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration">
  
    <property name="dataSource" ref="dataSource" />
    ...
      

Note that Activiti does not ship with a library that allows to define such a data source. So you have to make sure that the libraries (e.g. from DBCP) are on your classpath.

The following properties can be set, regardless of whether you are using the JDBC or data source approach:

  • databaseType: it's normally not necessary to specify this property as it is automatically analyzed from the database connection meta data. Should only be specified in case automatic detection fails. Possible values: {h2, mysql, oracle, postgres, mssql, db2}. This property is required when not using the default H2 database. This setting will determine which create/drop scripts and queries will be used. See the 'supported databases' section for an overview of which types are supported.

  • databaseSchemaUpdate: allows to set the strategy to handle the database schema on process engine boot and shutdown.

    • false (default): Checks the version of the DB schema against the library when the process engine is being created and throws an exception if the versions don't match.

    • true: Upon building the process engine, a check is performed and an update of the schema is performed if it is necessary. If the schema doesn't exist, it is created.

    • create-drop: Creates the schema when the process engine is being created and drops the schema when the process engine is being closed.

Supported databases

Listed below are the types (case sensitive!) that Activiti uses to refer to databases.

Table 3.1. Supported databases

Activiti database typeExample JDBC URLNotes
h2jdbc:h2:tcp://localhost/activitiDefault configured database
mysqljdbc:mysql://localhost:3306/activiti?autoReconnect=trueTested using mysql-connector-java database driver
oraclejdbc:oracle:thin:@localhost:1521:xe 
postgresjdbc:postgresql://localhost:5432/activiti 
db2jdbc:db2://localhost:50000/activiti 
mssqljdbc:sqlserver://localhost:1433/activiti 

Creating the database tables

The easiest way to create the database tables for your database is to:

  • Add the activiti-engine jars to your classpath

  • Add a suitable database driver

  • Add an Activiti configuration file (activiti.cfg.xml) to your classpath, pointing to your database (see database configuration section)

  • Execute the main method of the DbSchemaCreate class

However, often only database administrators can execute DDL statements on a database. On a production system, this is also the wisest of choices. The SQL DDL statements can be found on the Activiti downloads page or inside the Activiti distribution folder, in the database subdirectory. The scripts are also in the engine jar (activiti-engine-x.jar), in the package org/activiti/db/create (the drop folder contains the drop statements). The SQL files are of the form

activiti.{db}.{create|drop}.{type}.sql

Where db is any of the supported databases and type is

  • engine: the tables needed for engine execution. Required.

  • identity: the tables containing users, groups and memberships of users to groups. These tables are optional and should be used when using the default identity management as shipped with the engine.

  • history: the tables that contain the history and audit information. Optional: not needed when history level is set to none Note that this will also disable some features (such as commenting on tasks) which store the data in the history database.

Note for MySQL users: MySQL version lower than 5.6.4 has no support for timestamps or dates with millisecond precision. To make things even worse, some version will throw an exception when trying to create such a column but other versions don't. When doing auto-creation/upgrade, the engine will change the DDL when executing it. When using the DDL file approach, both a regular version and a special file with mysql55 in it are available (this applies on anything lower than 5.6.4). This latter file will have column types with no millisecond precision it it.

Concretely, the following applies for MySQL version

  • <5.6: No millisecond precision available. DDL files available (look for files containing mysql55). Auto creation/update will work out of the box.

  • 5.6.0 - 5.6.3: No millisecond precision available. Auto creation/update will NOT work. It is advised to upgrade to a newer database version anyway. DDL files for mysql 5.5 could be used if really needed.

  • 5.6.4+:Millisecond precision available. DDL files available (default file containing mysql). Auto creation/update works out of the box.

Do note that in the case of upgrading the MySQL database later on and the Activiti tables are already created/upgraded, the column type change will have to be done manually!

Database table names explained

The database names of Activiti all start with ACT_. The second part is a two-character identification of the use case of the table. This use case will also roughly match the service API.

  • ACT_RE_*: 'RE' stands for repository. Tables with this prefix contain 'static' information such as process definitions and process resources (images, rules, etc.).

  • ACT_RU_*: 'RU' stands for runtime. These are the runtime tables, that contain the runtime data of process instances, user tasks, variables, jobs, etc. Activiti only stores the runtime data during process instance execution, and removes the records when a process instance ends. This keeps the runtime tables small and fast.

  • ACT_ID_*: 'ID' stands for identity. These tables contain identity information, such as users, groups, etc.

  • ACT_HI_*: 'HI' stands for history. These are the tables that contain historic data, such as past process instances, variables, tasks, etc.

  • ACT_GE_*: general data, which is used in various use cases.

Database upgrade

Make sure you make a backup of your database (using your database backup capabilities) before you run an upgrade.

By default, a version check will be performed each time a process engine is created. This typically happens once at boot time of your application or of the Activiti webapps. If the Activiti library notices a difference between the library version and the version of the Activiti database tables, then an exception is thrown.

To upgrade, you have to start with putting the following configuration property in your activiti.cfg.xml configuration file:

<beans ... >

  <bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration">
    <!-- ... -->
    <property name="databaseSchemaUpdate" value="true" />    
    <!-- ... -->
  </bean>

</beans>

Also, include a suitable database driver for your database to the classpath. Upgrade the Activiti libraries in your application. Or start up a new version of Activiti and point it to a database that contains an older version. With databaseSchemaUpdate set to true, Activiti will automatically upgrade the DB schema to the newer version the first time when it notices that libraries and DB schema are out of sync.

As an alternative you can also run the upgrade DDL statements. It's also possible to run the upgrade database scripts, available on the Activiti downloads page.

Job executor activation

The JobExecutor is a component that manages a couple of threads to fire timers (and later also asynchronous messages). For unit testing scenarios, it is cumbersome to work with multiple threads. Therefore the API allows to query for (ManagementService.createJobQuery) and execute jobs (ManagementService.executeJob) through the API so that job execution can be controlled from within a unit test. To avoid interference by the job executor, it can be turned off.

By default, the JobExecutor is activated when the process engine boots. Specify

<property name="jobExecutorActivate" value="false" />

when you don't want the JobExecutor to be activated upon booting the process engine.

Mail server configuration

Configuring a mail server is optional. Activiti supports sending e-mails in business processes. To actually send an e-mail, a valid SMTP mail server configuration is required. See the e-mail task for the configuration options.

History configuration

Customizing the configuration of history storage is optional. This allows you to tweak settings that influence the history capabilities of the engine. See history configuration for more details.

<property name="history" value="audit" />

Exposing configuration beans in expressions and scripts

By default, all beans that you specify in the activiti.cfg.xml configuration or in your own Spring configuration file are available to expressions and in the scripts. If you want to limit the visibility of beans in your configuration file, you can configure a property called beans in your process engine configuration. The beans property in ProcessEngineConfiguration is a map. When you specify that property, only beans specified in that map will be visible to expressions and scripts. The exposed beans will be exposed with the names as you specify in that map.

Deployment cache configuration

All process definition are cached (after they're parsed) to avoid hitting the database every time a process definition is needed and because process definition data doesn't change. By default, there is no limit on this cache. To limit the process definition cache, add following property

<property name="processDefinitionCacheLimit" value="10" />

Setting this property will swap the default hashmap cache with a LRU cache that has the provided hard limit. Of course, the 'best' value of this property depends on the total amount of process definitions stored and the number of process definitions actually used at runtime by all the runtime process instances.

You can also inject your own cache implementation. This must be a bean that implements the org.activiti.engine.impl.persistence.deploy.DeploymentCache interface:

<property name="processDefinitionCache">
  <bean class="org.activiti.MyCache" />
</property>

There is a similar property called knowledgeBaseCacheLimit and knowledgeBaseCache for configuring the rules cache. This is only needed when you use the rules task in your processes.

Logging

As of Activiti 5.12, SLF4J is used as logging framework, replacing the previous used java.util.logging. All logging (activiti, spring, mybatis, ...) is routed through SLF4J and allows for selecting the logging-implementation of your choice.

By default no SFL4J-binding jar is present in the activiti-engine dependencies, this should be added in your project in order to use the logging framework of your choice. If no implementation jar is added, SLF4J will use a NOP-logger, not logging anything at all, other than a warning that nothing will be logged. For more info on these bindings http://www.slf4j.org/codes.html#StaticLoggerBinder.

With Maven, add for example a dependency like this (here using log4j), note that you still need to add a version:

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
</dependency>

The activiti-explorer and activiti-rest webapps are configured to use Log4j-binding. Log4j is also used when running the tests for all the activiti-* modules.

Important note when using a container with commons-logging in the classpath: In order to route the spring-logging through SLF4J, a bridge is used (see http://www.slf4j.org/legacy.html#jclOverSLF4J). If your container provides a commons-logging implementation, please follow directions on this page: http://www.slf4j.org/codes.html#release to ensure stability.

Example when using Maven (version omitted):

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>jcl-over-slf4j</artifactId>
</dependency>

Mapped Diagnostic Contexts

As of version 5.13, activiti supports Mapped Diagnostic Contexts feature of sl4j. These basic information are passed to the underlying logger along with what is going to be logged:

  • processDefinition Id as mdcProcessDefinitionID

  • processInstance Id as mdcProcessInstanceID

  • execution Id as mdcexecutionId

None of these information are logged by default. The logger can be configured to show them in desired format, extra to the usual logged messages. For example in log4j the following sample layout definition causes the logger to show the above mentioned information:

 log4j.appender.consoleAppender.layout.ConversionPattern =ProcessDefinitionId=%X{mdcProcessDefinitionID}
executionId=%X{mdcExecutionId} mdcProcessInstanceID=%X{mdcProcessInstanceID} mdcBusinessKey=%X{mdcBusinessKey} %m%n"
      

This is useful where the systems are mission critical and logs should be seriously checked, by means of a log analyzer for example.

Event handlers

An event mechanism has been introduced in Activiti 5.15. It allows you to get notified when various events occur within the engine. Take a look at all supported event types for an overview of the events available.

It's possible to register a listener for certain types of events as opposed to getting notified when any type of event is dispatched. You can either add engine-wide event listeners through the configuration, add engine-wide event listeners at runtime using the API or add event-listeners to specific process definitions in the BPMN XML.

All events dispatched are a subtype of org.activiti.engine.delegate.event.ActivitiEvent. The event exposes (if available) the type, executionId, processInstanceId and processDefinitionId. Certain events contain additional context related to the event that occurred, additional information about additional playload can be found in the list of all supported event types.

Event listener implementation

The only requirement an event-listener has, is to implement org.activiti.engine.delegate.event.ActivitiEventListener. Below is an example implementation of a listener, which outputs all events received to the standard-out, with exception of events related to job-execution:

public class MyEventListener implements ActivitiEventListener {

  @Override
  public void onEvent(ActivitiEvent event) {
    switch (event.getType()) {
    
      case JOB_EXECUTION_SUCCESS:
        System.out.println("A job well done!");
        break;
  
      case JOB_EXECUTION_FAILURE:
        System.out.println("A job has failed...");
        break;
        
      default:
        System.out.println("Event received: " + event.getType());
    }
  }

  @Override
  public boolean isFailOnException() {
    // The logic in the onEvent method of this listener is not critical, exceptions
    // can be ignored if logging fails...
    return false;
  }
}

The isFailOnException() method determines the behaviour in case the onEvent(..) method throws an exception when an event is dispatched. In case false is returned, the exception is ignored. When true is returned, the exception is not ignored and bubbles up, effectively failing the current ongoing command. In case the event was part of an API-call (or any other transactional operation, eg. job-execution), the transaction will be rolled back. In case the behaviour in the event-listener is not business-critical, it's recommended to return false.

There are a few base implementations provided by activiti to facilitate common usecases of event-listeners. These can be used as base-class or as an example listener implementation:

  • org.activiti.engine.delegate.event.BaseEntityEventListener: An event-listener base-class that can be used to listen for entity-related events for a specific type of entity or for all entities. It hides away the type-checking and offers 4 methods that should be overridden: onCreate(..), onUpdate(..) and onDelete(..) when an entity is created, updated or deleted. For all other entity-related events, the onEntityEvent(..)is called.

Configuration and setup

If event-listener is configured in the process engine configuration, it will be active when the process engine starts and will remain active after subsequent reboots of the engine.

The property eventListeners expects a list of org.activiti.engine.delegate.event.ActivitiEventListener instances. As usual, you can either declare an inline bean definition or use a ref to an existing bean instead. The snippet below adds an event-listener to the configuration, that is notified when any event is dispatched, regardless of it's type:

<bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration">
    ...
    <property name="eventListeners">
      <list>
         <bean class="org.activiti.engine.example.MyEventListener" />
      </list>
    </property>
</bean>

To get notified when certain types of events get dispatched, use the typedEventListeners property, which expects a map. The key of a map-entry is a comma-separated list of event-names (or a single event-name). The value of a map-entry is a list of org.activiti.engine.delegate.event.ActivitiEventListener instances. The snippet below adds an event-listener to the configuration, that is notified when a job execution was successful or failed:

<bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration">
    ...
    <property name="typedEventListeners">
      <map>
        <entry key="JOB_EXECUTION_SUCCESS,JOB_EXECUTION_FAILURE" >
          <list>
            <bean class="org.activiti.engine.example.MyJobEventListener" />
          </list>
        </entry>
      </map>
    </property>
</bean>

The order of dispatching events is determined on the order the listeners were added. First, all normal event-listeners are called (eventListeners property) in the order they are defined in the list. After that, all typed event listeners (typedEventListeners properties) are called, if an event of the right type is dispatched.

Adding listeners at runtime

It's possible to add and remove additional event-listeners to the engine by using the API (RuntimeService):

/**
 * Adds an event-listener which will be notified of ALL events by the dispatcher.
 * @param listenerToAdd the listener to add
 */
void addEventListener(ActivitiEventListener listenerToAdd);

/**
 * Adds an event-listener which will only be notified when an event occurs, which type is in the given types.
 * @param listenerToAdd the listener to add
 * @param types types of events the listener should be notified for
 */
void addEventListener(ActivitiEventListener listenerToAdd, ActivitiEventType... types);

/**
 * Removes the given listener from this dispatcher. The listener will no longer be notified,
 * regardless of the type(s) it was registered for in the first place.
 * @param listenerToRemove listener to remove
 */
 void removeEventListener(ActivitiEventListener listenerToRemove);

Please note that the listeners added at runtime are not retained when the engine is rebooted.

Adding listeners to process definitions

It's possible to add listeners to a specific process-definition. The listeners will only be called for events related to the process definition and to all events related to process instances that are started with that specific process definition. The listener implementations can be defined using a fully qualified classname, an expression that resolves to a bean that implements the listener interface or can be configured to throw a message/signal/error BPMN event.

Listeners executing user-defined logic

The snippet below adds 2 listeners to a process-definition. The first listener will receive events of any type, with a listener implementation based on a fully-qualified class name. The second listener is only notified when a job is successfully executed or when it failed, using a listener that has been defined in the beans property of the process engine configuration.

<process id="testEventListeners">
  <extensionElements>
    <activiti:eventListener class="org.activiti.engine.test.MyEventListener" />
    <activiti:eventListener delegateExpression="${testEventListener}" events="JOB_EXECUTION_SUCCESS,JOB_EXECUTION_FAILURE" />
  </extensionElements>
        
  ...

</process>

For events related to entities, it's also possible to add listeners to a process-definition that get only notified when entity-events occur for a certain entity type. The snippet below shows how this can be achieved. It can be used along for ALL entity-events (first example) or for specific event types only (second example).

<process id="testEventListeners">
  <extensionElements>
    <activiti:eventListener class="org.activiti.engine.test.MyEventListener" entityType="task" />
    <activiti:eventListener delegateExpression="${testEventListener}" events="ENTITY_CREATED" entityType="task" />
  </extensionElements>
        
  ...

</process>

For events related to entities, it's also possible to add listeners to a process-definition that get notified only entity-events occur for a certain entity type. The snippet below shows how this can be done. It can be used along for ALL entity-events (first example) or for specific event types only (second example).

<process id="testEventListeners">
  <extensionElements>
    <activiti:eventListener class="org.activiti.engine.test.MyEventListener" entityType="task" />
    <activiti:eventListener delegateExpression="${testEventListener}" events="ENTITY_CREATED" entityType="task" />
  </extensionElements>
        
  ...

</process>

Supported values for the entityType are: attachment, comment, execution,identity-link, job, process-instance, process-definition, task.

Listeners throwing BPMN events

[EXPERIMENTAL]

Another way of handling events being dispatched is to throw a BPMN event. Please bare in mind that it only makes sense to throw BPMN-events with certain kinds of activiti event types. For example, throwing a BPMN event when the process-instance is deleted will result in an error. The snippet below shows how to throw a signal inside process-instance, throw a signal to an external process (global), throw a message-event inside the process-instance and throw an error-event inside the process-instance. Instead of using the class or delegateExpression, the attribute throwEvent is used, along with an additional attribute, specific to the type of event being thrown.

<process id="testEventListeners">
  <extensionElements>
    <activiti:eventListener throwEvent="signal" signalName="My signal" events="TASK_ASSIGNED" />
  </extensionElements>
</process>
<process id="testEventListeners">
  <extensionElements>
    <activiti:eventListener throwEvent="globalSignal" signalName="My signal" events="TASK_ASSIGNED" />
  </extensionElements>
</process>
<process id="testEventListeners">
  <extensionElements>
    <activiti:eventListener throwEvent="message" messageName="My message" events="TASK_ASSIGNED" />
  </extensionElements>
</process>
<process id="testEventListeners">
  <extensionElements>
    <activiti:eventListener throwEvent="error" errorCode="123" events="TASK_ASSIGNED" />
  </extensionElements>
</process>

If additional logic is needed to decide whether or not to throw the BPMN-event, it's possible to extend the listener-classes provided by Activiti. By overriding the isValidEvent(ActivitiEvent event) in your subclass, BPMN-event throwing can be prevented. The classes involved are org.activiti.engine.test.api.event.SignalThrowingEventListenerTest, org.activiti.engine.impl.bpmn.helper.MessageThrowingEventListener and org.activiti.engine.impl.bpmn.helper.ErrorThrowingEventListener.

Notes on listeners on a process-definition

  • Event-listeners can only be declared on the process element, as a child-element of the extensionElements. Listeners cannot be defined on individual activities in the process.

  • Expressions used in the delegateExpression do not have access to the execution-context, as other expressions (eg. in gateways) have. They can only reference beans defined in the beans property of the process engine configuration or when using spring (and the beans property is absent) to any spring-bean that implements the listener interface.

  • When using the class attribute of a listener, there will only be a single instance of that class created. Make sure the listener implementations do not rely on member-fields or ensure safe usage from multiple threads/contexts.

  • When an illegal event-type is used in the events attribute or illegal throwEvent value is used, an exception will be thrown when the process-definition is deployed (effectively failing the deployment). When an illegal value for class or delegateExecution is supplied (either unexisting class, unexisting bean referenced or delegate not implementing listener interface), an exception will be thrown when the process is started (or when the first valid event for that process-definition is dispatched to the listener). Make sure the referenced classes are on the classpath and that the expressions resolve to a valid instance.

Dispatching events through API

We opened up the event-dispatching mechanism through the API, to allow you to dispatch custom events to any listeners that are registered in the engine. It's recommended (although not enforced) to only dispatch ActivitiEvents with type CUSTOM. Dispatching the event can be done using the RuntimeService:

/**
 * Dispatches the given event to any listeners that are registered.
 * @param event event to dispatch.
 * 
 * @throws ActivitiException if an exception occurs when dispatching the event or when the {@link ActivitiEventDispatcher}
 * is disabled.
 * @throws ActivitiIllegalArgumentException when the given event is not suitable for dispatching.
 */
 void dispatchEvent(ActivitiEvent event);

Supported event types

Listed below are all event types that can occur in the engine. Each type corresponds to an enum value in the org.activiti.engine.delegate.event.ActivitiEventType.

Table 3.2. Supported events

Event nameDescriptionEvent classes
ENGINE_CREATEDThe process-engine this listener is attached to, has been created and is ready for API-calls.org.activiti...ActivitiEvent
ENGINE_CLOSEDThe process-engine this listener is attached to, has been closed. API-calls to the engine are no longer possible.org.activiti...ActivitiEvent
ENTITY_CREATEDA new entity is created. The new entity is contained in the event.org.activiti...ActivitiEntityEvent
ENTITY_CREATEDA new entity has been created and is fully initialized. If any children are created as part of the creation of an entity, this event will be fired AFTER the create/initialisation of the child entities as opposed to the ENTITY_CREATE event.org.activiti...ActivitiEntityEvent
ENTITY_UPDATEDAn existing is updated. The updated entity is contained in the event.org.activiti...ActivitiEntityEvent
ENTITY_DELETEDAn existing entity is deleted. The deleted entity is contained in the event.org.activiti...ActivitiEntityEvent
ENTITY_SUSPENDEDAn existing entity is suspended. The suspended entity is contained in the event. Will be dispatched for ProcessDefinitions, ProcessInstances and Tasks.org.activiti...ActivitiEntityEvent
ENTITY_ACTIVATEDAn existing entity is activated. The activated entity is contained in the event. Will be dispatched for ProcessDefinitions, ProcessInstances and Tasks.org.activiti...ActivitiEntityEvent
JOB_EXECUTION_SUCCESSA job has been executed successfully. The event contains the job that was executed.org.activiti...ActivitiEntityEvent
JOB_EXECUTION_FAILUREThe execution of a job has failed. The event contains the job that was executed and the exception.org.activiti...ActivitiEntityEvent and org.activiti...ActivitiExceptionEvent
JOB_RETRIES_DECREMENTEDThe number of job retries have been decremented due to a failed job. The event contains the job that was updated.org.activiti...ActivitiEntityEvent
TIMER_FIREDA timer has been fired. The event contains the job that was executed?org.activiti...ActivitiEntityEvent
ACTIVITY_STARTEDAn activity is starting to executeorg.activiti...ActivitiActivityEvent
ACTIVITY_COMPLETEDAn activity is completed successfullyorg.activiti...ActivitiActivityEvent
ACTIVITY_SIGNALEDAn activity received a signalorg.activiti...ActivitiSignalEvent
ACTIVITY_MESSAGE_RECEIVEDAn activity received a message. Dispatched before the activity receives the message. When received, a ACTIVITY_SIGNAL or ACTIVITY_STARTED will be dispatched for this activity, depending on the type (boundary-event or event-subprocess start-event)org.activiti...ActivitiMessageEvent
ACTIVITY_ERROR_RECEIVEDAn activity has received an error event. Dispatched before the actual error has been handled by the activity. The event's activityId contains a reference to the error-handling activity. This event will be either followed by a ACTIVITY_SIGNALLED event or ACTIVITY_COMPLETE for the involved activity, if the error was delivered successfully.org.activiti...ActivitiErrorEvent
UNCAUGHT_BPMN_ERRORAn uncaught BPMN error has been thrown. The process did not have any handlers for that specific error. The event's activityId will be empty.org.activiti...ActivitiErrorEvent
ACTIVITY_COMPENSATEAn activity is about to be compensated. The event contains the id of the activity that is will be executed for compensation.org.activiti...ActivitiActivityEvent
VARIABLE_CREATEDA variable has been created. The event contains the variable name, value and related execution and task (if any).org.activiti...ActivitiVariableEvent
VARIABLE_UPDATEDAn existing variable has been updated. The event contains the variable name, updated value and related execution and task (if any).org.activiti...ActivitiVariableEvent
VARIABLE_DELETEDAn existing variable has been deleted. The event contains the variable name, last known value and related execution and task (if any).org.activiti...ActivitiVariableEvent
TASK_ASSIGNEDA task has been assigned to a user. The event contains the taskorg.activiti...ActivitiEntityEvent
TASK_COMPLETEDA task has been completed. This is dispatched before the ENTITY_DELETE event. In case the task is part of a process, this event will be fired before the process has moved on and will be followed by a ACTIVITY_COMPLETE event, targeting the activity that represents the completed task.org.activiti...ActivitiEntityEvent
MEMBERSHIP_CREATEDA user has been added to a group. The event contains the id's of the user and group involved.org.activiti...ActivitiMembershipEvent
MEMBERSHIP_DELETEDA user has been removed from a group. The event contains the id's of the user and group involved.org.activiti...ActivitiMembershipEvent
MEMBERSHIPS_DELETEDAll members will be removed from a group. The event is thrown before the members are removed, so they are still accessible. No individual MEMBERSHIP_DELETED events will be thrown if all members are deleted at once, for performance reasons.org.activiti...ActivitiMembershipEvent

All ENTITY_* events are related to entities inside the engine. The list below show an overview of what entity-events are dispatched for which entities:

  • ENTITY_CREATED, ENTITY_INITIALIZED, ENTITY_DELETED: Attachment, Comment, Deployment, Execution, Group, IdentityLink, Job, Model, ProcessDefinition, ProcessInstance, Task, User.

  • ENTITY_UPDATED: Attachment, Deployment, Execution, Group, IdentityLink, Job, Model, ProcessDefinition, ProcessInstance, Task, User.

  • ENTITY_SUSPENDED, ENTITY_ACTIVATED: ProcessDefinition, ProcessInstance/Execution, Task.

Additional remarks

Only listeners are notified in the engine the events are dispatched from. So in case you have different engines - running against the same database - only events that originated in the engine the listener is registered for, are dispatched to that listener. The events that occur in the other engine are not dispatched to the listeners, regardless of the fact they are running in the same JVM or not.

Certain event-types (related to entities) expose the targetted entity. Depending on the type or event, these entities cannot be updated anymore (eg. when the entity is deleted). If possible, use the EngineServices exposed by the event to interact in a safe way with the engine. Even then, you need to be cautious with updates/operations on entities that are involved in the dispatched event.

No entity-events are dispatched related to history, as they all have a runtime-counterpart which have their events dispatched.

Chapter 4. The Activiti API

The Process Engine API and services

The engine API is the most common way of interacting with Activiti. The central starting point is the ProcessEngine, which can be created in several ways as described in the configuration section. From the ProcessEngine, you can obtain the various services that contain the workflow/BPM methods. ProcessEngine and the services objects are thread safe. So you can keep a reference to 1 of those for a whole server.

ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine();

RuntimeService runtimeService = processEngine.getRuntimeService();
RepositoryService repositoryService = processEngine.getRepositoryService();
TaskService taskService = processEngine.getTaskService();
ManagementService managementService = processEngine.getManagementService();
IdentityService identityService = processEngine.getIdentityService();
HistoryService historyService = processEngine.getHistoryService();
FormService formService = processEngine.getFormService();

ProcessEngines.getDefaultProcessEngine() will initialize and build a process engine the first time it is called and afterwards always return the same process engine. Proper creation and closing of all process engines can be done with ProcessEngines.init() and ProcessEngines.destroy().

The ProcessEngines class will scan for all activiti.cfg.xml and activiti-context.xml files. For all activiti.cfg.xml files, the process engine will be built in the typical Activiti way: ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(inputStream).buildProcessEngine(). For all activiti-context.xml files, the process engine will be built in the Spring way: First the Spring application context is created and then the process engine is obtained from that application context.

All services are stateless. This means that you can easily run Activiti on multiple nodes in a cluster, each going to the same database, without having to worry about which machine actually executed previous calls. Any call to any service is idempotent regardless of where it is executed.

The RepositoryService is probably the first service needed when working with the Activiti engine. This service offers operations for managing and manipulating deployments and process definitions. Without going into much detail here, a process definition is a Java counterpart of BPMN 2.0 process. It is a representation of the structure and behaviour of each of the steps of a process. A deployment is the unit of packaging within the Activiti engine. A deployment can contain multiple BPMN 2.0 xml files and any other resource. The choice of what is included in one deployment is up to the developer. It can range from a single process BPMN 2.0 xml file to a whole package of processes and relevant resources (for example the deployment 'hr-processes' could contain everything related to hr processes). The RepositoryService allows to deploy such packages. Deploying a deployment means it is uploaded to the engine, where all processes are inspected and parsed before being stored in the database. From that point on, the deployment is known to the system and any process included in the deployment can now be started.

Furthermore, this service allows to

  • query on deployments and process definitions known to the engine.

  • Suspend and activate deployments as a whole or specific process definitions. Suspending means no further operations can be done on them, while activation is the opposite operation.

  • Retrieve various resources such as files contained within the deployment or process diagrams that were auto generated by the engine.

  • Retrieve a pojo version of the process definition which can be used to introspect the process using Java rather than xml.

While the RepositoryService is rather about static information (ie. data that doesn't change, or at least not a lot), the RuntimeService is quite the opposite. It deals with starting new process instances of process definitions. As said above, a process definition defines the structure and behaviour of the different steps in a process. A process instance is one execution of such a process definition. For each process definition there typically are many instances running at the same time. The RuntimeService also is the service which is used to retrieve and store process variables. This is data which is specific to the given process instance and can be used by various constructs in the process (eg. an exclusive gateway often uses process variables to determine which path is chosen to continue the process). The Runtimeservice also allows to query on process instances and executions. Executions are a representation of the 'token' concept of BPMN 2.0. Basically an execution is a pointer pointing to where the process instance currently is. Lastly, the RuntimeService is used whenever a process instance is waiting for an external trigger and the process needs to be continued. A process instance can have various wait states and this service contains various operations to 'signal' the instance that the external trigger is received and the process instance can be continued.

Tasks that need to be performed by actual human users of the system are core to a BPM engine such as Activiti. Everything around tasks is grouped in the TaskService, such as

  • Querying tasks assigned to users or groups

  • Creating new standalone tasks. These are tasks that are not related to a process instances.

  • Manipulating to which user a task is assigned or which users are in some way involved with the task.

  • Claiming and completing a task. Claiming means that someone decided to be the assignee for the task, meaning that this user will complete the task. Completing means 'doing the work of the tasks'. Typically this is filling in a form of sorts.

The IdentityService is pretty simple. It allows the management (creation, update, deletion, querying, ...) of groups and users. It is important to understand that Activiti actually doesn't do any checking on users at runtime. For example, a task could be assigned to any user, but the engine does not verify if that user is known to the system. This is because the Activiti engine can also used in conjunction with services such as ldap, active directory, etc.

The FormService is an optional service. Meaning that Activiti can perfectly be used without it, without sacrificing any functionality. This service introduces the concept of a start form and a task form. A start form is a form that is shown to the user before the process instance is started, while a task form is the form that is displayed when a user wants to complete a form. Activiti allows to define these forms in the BPMN 2.0 process definition. This service exposes this data in an easy way to work with. But again, this is optional as forms don't need to be embedded in the process definition.

The HistoryService exposes all historical data gathered by the Activiti engine. When executing processes, a lot of data can be kept by the engine (this is configurable) such as process instance start times, who did which tasks, how long it took to complete the tasks, which path was followed in each process instance, etc. This service exposes mainly query capabilities to access this data.

The ManagementService is typically not needed when coding custom application using Activiti. It allows to retrieve information about the database tables and table metadata. Furthermore, it exposes query capabilities and management operations for jobs. Jobs are used in Activiti for various things such as timers, asynchronous continuations, delayed suspension/activation, etc. Later on, these topics will be discussed in more detail.

For more detailed information on the service operations and the engine API, see the javadocs.

Exception strategy

The base exception in Activiti is the org.activiti.engine.ActivitiException, an unchecked exception. This exception can be thrown at all times by the API, but 'expected' exceptions that happen in specific methods are documented in the the javadocs. For example, an extract from TaskService:

/**
 * Called when the task is successfully executed.
 * @param taskId the id of the task to complete, cannot be null.
 * @throws ActivitiObjectNotFoundException when no task exists with the given id.
 */
 void complete(String taskId);
    

In the example above, when an id is passed for which no task exists, an exception will be thrown. Also, since the javadoc explicitly states that taskId cannot be null, an ActivitiIllegalArgumentException will be thrown when null is passed.

Even though we want to avoid a big exception hierarchy, the following subclasses were added which are thrown in specific cases. All other errors that occur during process-execution or API-invokation that don't fit into the possible exceptions below, are throw as regular ActivitiExceptionss.

  • ActivitiWrongDbException: Thrown when the Activiti engine discovers a mismatch between the database schema version and the engine version.

  • ActivitiOptimisticLockingException: Thrown when an optimistic locking occurs in the data store caused by concurrent access of the same data entry.

  • ActivitiClassLoadingException: Thrown when a class requested to load was not found or when an error occurred while loading it (e.g. JavaDelegates, TaskListeners, ...).

  • ActivitiObjectNotFoundException: Thrown when an object that is requested or actioned on does not exist.

  • ActivitiIllegalArgumentException: An exception indicating that an illegal argument has been supplied in an Activiti API-call, an illegal value was configured in the engine's configuration or an illegal value has been supplied or an illegal value is used in a process-definition.

  • ActivitiTaskAlreadyClaimedException: Thrown when a task is already claimed, when the taskService.claim(...) is called. .

Working with the Activiti services

As described above, the way to interact with the Activiti engine is through the services exposed by an instance of the org.activiti.engine.ProcessEngine class. The following code snippets assume you have a working Activiti environment, ie. you have access to a valid org.activiti.engine.ProcessEngine. If you simply want to try out the code below, you can download or clone the Activiti unit test template, import it in your IDE and add a testUserguideCode() method to the org.activiti.MyUnitTest unit test.

The end goal of this little tutorial will be to have a working business process which mimics a simplistic vacation request process at a company:

Deploying the process

Everything that is related to 'static' data (such as process definitions) are accessed through the RepositoryService. Conceptually, every such static piece of data is content of the 'repository' of the Activiti engine.

Create a new xml file VacationRequest.bpmn20.xml in the src/test/resources/org/activiti/test resource folder (or anywhere else if you're not using the unit test template) with the following content. Note that this section won't explain the xml constructs being used in the example above. Please read the bpmn 2.0 chapter to become familiar with these constructs first if needed.

<?xml version="1.0" encoding="UTF-8" ?>
<definitions id="definitions"
             targetNamespace="http://activiti.org/bpmn20" 
             xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:activiti="http://activiti.org/bpmn">
  
  <process id="vacationRequest" name="Vacation request">
  
    <startEvent id="request" activiti:initiator="employeeName">
      <extensionElements>
        <activiti:formProperty id="numberOfDays" name="Number of days" type="long" value="1" required="true"/>
        <activiti:formProperty id="startDate" name="First day of holiday (dd-MM-yyy)" datePattern="dd-MM-yyyy hh:mm" type="date" required="true" />
        <activiti:formProperty id="vacationMotivation" name="Motivation" type="string" />
      </extensionElements>
    </startEvent>
    <sequenceFlow id="flow1" sourceRef="request" targetRef="handleRequest" />
    
    <userTask id="handleRequest" name="Handle vacation request" >
      <documentation>
        ${employeeName} would like to take ${numberOfDays} day(s) of vacation (Motivation: ${vacationMotivation}).
      </documentation> 
      <extensionElements>
         <activiti:formProperty id="vacationApproved" name="Do you approve this vacation" type="enum" required="true">
          <activiti:value id="true" name="Approve" />
          <activiti:value id="false" name="Reject" />
        </activiti:formProperty>
        <activiti:formProperty id="managerMotivation" name="Motivation" type="string" />
      </extensionElements>
      <potentialOwner>
        <resourceAssignmentExpression>
          <formalExpression>management</formalExpression>
        </resourceAssignmentExpression>
      </potentialOwner>         
    </userTask>
    <sequenceFlow id="flow2" sourceRef="handleRequest" targetRef="requestApprovedDecision" />
    
    <exclusiveGateway id="requestApprovedDecision" name="Request approved?" />
    <sequenceFlow id="flow3" sourceRef="requestApprovedDecision" targetRef="sendApprovalMail">
      <conditionExpression xsi:type="tFormalExpression">${vacationApproved == 'true'}</conditionExpression>
    </sequenceFlow>
    
    <task id="sendApprovalMail" name="Send confirmation e-mail" />
    <sequenceFlow id="flow4" sourceRef="sendApprovalMail" targetRef="theEnd1" />
    <endEvent id="theEnd1" />
    
    <sequenceFlow id="flow5" sourceRef="requestApprovedDecision" targetRef="adjustVacationRequestTask">
      <conditionExpression xsi:type="tFormalExpression">${vacationApproved == 'false'}</conditionExpression>
    </sequenceFlow>
    
    <userTask id="adjustVacationRequestTask" name="Adjust vacation request">
      <documentation>
        Your manager has disapproved your vacation request for ${numberOfDays} days.
        Reason: ${managerMotivation}
      </documentation>
      <extensionElements>
        <activiti:formProperty id="numberOfDays" name="Number of days" value="${numberOfDays}" type="long" required="true"/>
        <activiti:formProperty id="startDate" name="First day of holiday (dd-MM-yyy)" value="${startDate}" datePattern="dd-MM-yyyy hh:mm" type="date" required="true" />
        <activiti:formProperty id="vacationMotivation" name="Motivation" value="${vacationMotivation}" type="string" />
        <activiti:formProperty id="resendRequest" name="Resend vacation request to manager?" type="enum" required="true">
          <activiti:value id="true" name="Yes" />
          <activiti:value id="false" name="No" />
        </activiti:formProperty>
      </extensionElements>
      <humanPerformer>
        <resourceAssignmentExpression>
          <formalExpression>${employeeName}</formalExpression>
        </resourceAssignmentExpression>
      </humanPerformer>  
    </userTask>
    <sequenceFlow id="flow6" sourceRef="adjustVacationRequestTask" targetRef="resendRequestDecision" />
    
    <exclusiveGateway id="resendRequestDecision" name="Resend request?" />
    <sequenceFlow id="flow7" sourceRef="resendRequestDecision" targetRef="handleRequest">
      <conditionExpression xsi:type="tFormalExpression">${resendRequest == 'true'}</conditionExpression>
    </sequenceFlow>
    
     <sequenceFlow id="flow8" sourceRef="resendRequestDecision" targetRef="theEnd2">
      <conditionExpression xsi:type="tFormalExpression">${resendRequest == 'false'}</conditionExpression>
    </sequenceFlow>
    <endEvent id="theEnd2" />
      
  </process>
  
</definitions>
            

To make this process known to the Activiti engine, we must 'deploy' it first. Deploying means that the engine will parse the BPMN 2.0 xml to something executable and a new database record will be added for each process definition included in the 'deployment'. This way, when the engine reboots, it will still know all of the 'deployed' processes:

ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine();
RepositoryService repositoryService = processEngine.getRepositoryService();
repositoryService.createDeployment()
  .addClasspathResource("org/activiti/test/VacationRequest.bpmn20.xml")
  .deploy();
      
Log.info("Number of process definitions: " + repositoryService.createProcessDefinitionQuery().count());            
            

Read more about deployment in the deployment chapter.

Starting a process instance

After deploying the process definition to the Activiti engine, we can start new process instances from it. For each process definition, there are typically many process instances. The process definition is the 'blueprint', while a process instance is a runtime execution of it.

Everything related to the runtime state of processes can be found in the RuntimeService. There are various way to start a new process instance. In the following snippet, we use the key we defined in the process definition xml to start the process instance. We're also providing some process variables at process instance start, because the description of the first user task will use these in its expressions. Process variables are commonly used because they give meaning to the process instances for a certain process definition. Typically, the process variables are what make process instances differ from one another.

Map<String, Object> variables = new HashMap<String, Object>();
variables.put("employeeName", "Kermit");
variables.put("numberOfDays", new Integer(4));
variables.put("vacationMotivation", "I'm really tired!");
      
RuntimeService runtimeService = processEngine.getRuntimeService();
ProcessInstance processInstance = runtimeService.startProcessInstanceByKey("vacationRequest", variables);
      
// Verify that we started a new process instance
Log.info("Number of process instances: " + runtimeService.createProcessInstanceQuery().count());           
            

Completing tasks

When the process starts, the first step will be a user task. This is a step that must be performed by a user of the system. Typically, such a user will have an 'inbox of tasks' which lists all the tasks that need to be done by this user. Following code snippet shows how such a query might be performed:

// Fetch all tasks for the management group
TaskService taskService = processEngine.getTaskService();
List<Task> tasks = taskService.createTaskQuery().taskCandidateGroup("management").list();
for (Task task : tasks) {
  Log.info("Task available: " + task.getName());
}            
            

To continue the process instance, we need to finish this task. For the Activiti engine, this means you need to complete the task. Following snippet shows how this is done:

Task task = tasks.get(0);
      
Map<String, Object> taskVariables = new HashMap<String, Object>();
taskVariables.put("vacationApproved", "false");
taskVariables.put("managerMotivation", "We have a tight deadline!");
taskService.complete(task.getId(), taskVariables);            
            

The process instance will now continue to the next step. In this example, the next step allows the employee to complete a form that adjusts their original vacation request. The employee can resubmit the vacation request which will cause the process to loop back to the start task.

Suspending and activating a process

It's possible to suspend a process definition. When a process definition is suspended, new process instance can't be created (an exception will be thrown). Suspending the process definition is done through the RepositoryService:

repositoryService.suspendProcessDefinitionByKey("vacationRequest");
try {
  runtimeService.startProcessInstanceByKey("vacationRequest");
} catch (ActivitiException e) {
  e.printStackTrace();
}            
            

To reactivate a process definition, simply call one of the repositoryService.activateProcessDefinitionXXX methods.

It's also possible to suspend a process instance. When suspended, the process cannot be continued (e.g. completing a task throws an exception) and no jobs (such as timers) will executed. Suspending a process instance can be done by calling the runtimeService.suspendProcessInstance method. Activating the process instance again is done by calling the runtimeService.activateProcessInstanceXXX methods.

Further reading

We've barely scratched the surface in the previous sections regarding Activiti functionality. We will expand these sections further in the future with additional coverage of the Activiti API. Of course, as with any open source project, the best way to learn is to inspect the code and read the Javadocs!

Query API

There are two ways of querying data from the engine: The query API and native queries. The Query API allows to program completely typesafe queries with a fluent API. You can add various conditions to your queries (all of which are applied together as a logical AND) and precisely one ordering. The following code shows an example:

      List<Task> tasks = taskService.createTaskQuery()
         .taskAssignee("kermit")
         .processVariableValueEquals("orderId", "0815")
         .orderByDueDate().asc()
         .list();
      

Sometimes you need more powerful queries, e.g. queries using an OR operator or restrictions you can not express using the Query API. For these cases, we introduced native queries, which allow you to write your own SQL queries. The return type is defined by the Query object you use and the data is mapped into the correct objects, e.g. Task, ProcessInstance, Execution, etc.... Since the query will be fired at the database you have to use table and column names as they are defined in the database; this requires some knowledge about the internal data structure and it is recommended to use native queries with care. The table names can be retrieved via the API to keep the dependency as small as possible.

      List<Task> tasks = taskService.createNativeTaskQuery()
        .sql("SELECT count(*) FROM " + managementService.getTableName(Task.class) + " T WHERE T.NAME_ = #{taskName}")
        .parameter("taskName", "gonzoTask")
        .list();

      long count = taskService.createNativeTaskQuery()
        .sql("SELECT count(*) FROM " + managementService.getTableName(Task.class) + " T1, "
               + managementService.getTableName(VariableInstanceEntity.class) + " V1 WHERE V1.TASK_ID_ = T1.ID_")
        .count();
      

Expressions

Activiti uses UEL for expression-resolving. UEL stands for Unified Expression Language and is part of the EE6 specification (see the EE6 specification for detailed information). To support all features of latest UEL spec on ALL environments, we use a modified version of JUEL.

Expressions can be used in for example Java Service tasks, Execution Listeners, Task Listeners and Conditional sequence flows. Although there are 2 types of expressions, value-expression and method-expression, Activiti abstracts this so they can both be used where an expression is needed.

  • Value expression: resolves to a value. By default, all process variables are available to use. Also all spring-beans (if using Spring) are available to use in expressions. Some examples:

    ${myVar}
    ${myBean.myProperty}

  • Method expression: invokes a method, with or without parameters. When invoking a method without parameters, be sure to add empty parentheses after the method-name (as this distinguishes the expression from a value expression). The passed parameters can be literal values or expressions that are resolved themselves. Examples:

    ${printer.print()}
    ${myBean.addNewOrder('orderName')}
    ${myBean.doSomething(myVar, execution)}
    

Note that these expressions support resolving primitives (incl. comparing them), beans, lists, arrays and maps.

On top of all process variables, there are a few default objects available to be used in expressions:

  • execution: The DelegateExecution that holds additional information about the ongoing execution.

  • task: The DelegateTask that holds additional information about the current Task. Note: Only works in expressions evaluated from task listeners.

  • authenticatedUserId: The id of the user that is currently authenticated. If no user is authenticated, the variable is not available.

For more concrete usage and examples, check out Expressions in Spring, Java Service tasks, Execution Listeners, Task Listeners or Conditional sequence flows.

Unit testing

Business processes are an integral part of software projects and they should be tested in the same way normal application logic is tested: with unit tests. Since Activiti is an embeddable Java engine, writing unit tests for business processes is as simple as writing regular unit tests.

Activiti supports both JUnit versions 3 and 4 styles of unit testing. In the JUnit 3 style, the org.activiti.engine.test.ActivitiTestCase must be extended. This will make the ProcessEngine and the services available through protected member fields. In the setup() of the test, the processEngine will be initialized by default with the activiti.cfg.xml resource on the classpath. To specify a different configuration file, override the getConfigurationResource() method. Process engines are cached statically over multiple unit tests when the configuration resource is the same.

By extending ActivitiTestCase, you can annotate test methods with org.activiti.engine.test.Deployment. Before the test is run, a resource file of the form testClassName.testMethod.bpmn20.xml in the same package as the test class, will be deployed. At the end of the test, the deployment will be deleted, including all related process instances, tasks, etc. The Deployment annotation also supports setting the resource location explicitly. See the Javadocs for more details.

Taking all that in account, a JUnit 3 style test looks as follows.

public class MyBusinessProcessTest extends ActivitiTestCase {
   
  @Deployment
  public void testSimpleProcess() {
    runtimeService.startProcessInstanceByKey("simpleProcess");
    
    Task task = taskService.createTaskQuery().singleResult();
    assertEquals("My Task", task.getName());
    
    taskService.complete(task.getId());
    assertEquals(0, runtimeService.createProcessInstanceQuery().count());
  }
}      
      

To get the same functionality when using the JUnit 4 style of writing unit tests, the org.activiti.engine.test.ActivitiRule Rule must be used. Through this rule, the process engine and services are available through getters. As with the ActivitiTestCase (see above), including this Rule will enable the use of the org.activiti.engine.test.Deployment annotation (see above for an explanation of its use and configuration) and it will look for the default configuration file on the classpath. Process engines are statically cached over multiple unit tests when using the same configuration resource.

The following code snippet shows an example of using the JUnit 4 style of testing and the usage of the ActivitiRule.

public class MyBusinessProcessTest {
  
  @Rule
  public ActivitiRule activitiRule = new ActivitiRule();
  
  @Test
  @Deployment
  public void ruleUsageExample() {
    RuntimeService runtimeService = activitiRule.getRuntimeService();
    runtimeService.startProcessInstanceByKey("ruleUsage");
    
    TaskService taskService = activitiRule.getTaskService();
    Task task = taskService.createTaskQuery().singleResult();
    assertEquals("My Task", task.getName());
    
    taskService.complete(task.getId());
    assertEquals(0, runtimeService.createProcessInstanceQuery().count());
  }
}
      

Debugging unit tests

When using the in-memory H2 database for unit tests, the following instructions allow to easily inspect the data in the Activiti database during a debugging session. The screenshots here are taken in Eclipse, but the mechanism should be similar for other IDEs.

Suppose we have put a breakpoint somewhere in our unit test. In Eclipse this is done by double-clicking in the left border next to the code:

If we now run the unit test in debug mode (right-click in test class, select 'Run as' and then 'JUnit test'), the test execution halts at our breakpoint, where we can now inspect the variables of our test as shown in the right upper panel.

To inspect the Activiti data, open up the 'Display' window (if this window isn't there, open Window->Show View->Other and select Display.) and type (code completion is available) org.h2.tools.Server.createWebServer("-web").start()

Select the line you've just typed and right-click on it. Now select 'Display' (or execute the shortcut instead of right-clicking)

Now open up a browser and go to http://localhost:8082, and fill in the JDBC URL to the in-memory database (by default this is jdbc:h2:mem:activiti), and hit the connect button.

You can now see the Activiti data and use it to understand how and why your unit test is executing your process in a certain way.

The process engine in a web application

The ProcessEngine is a thread-safe class and can easily be shared among multiple threads. In a web application, this means it is possible to create the process engine once when the container boots and shut down the engine when the container goes down.

The following code snippet shows how you can write a simple ServletContextListener to initialize and destroy process engines in a plain Servlet environment:

public class ProcessEnginesServletContextListener implements ServletContextListener {
  
  public void contextInitialized(ServletContextEvent servletContextEvent) {
    ProcessEngines.init();
  }

  public void contextDestroyed(ServletContextEvent servletContextEvent) {
    ProcessEngines.destroy();
  }

}

The contextInitialized method will delegate to ProcessEngines.init(). That will look for activiti.cfg.xml resource files on the classpath, and create a ProcessEngine for the given configurations (e.g. multiple jars with a configuration file). If you have multiple such resource files on the classpath, make sure they all have different names. When the process engine is needed, it can be fetched using

ProcessEngines.getDefaultProcessEngine()

or

ProcessEngines.getProcessEngine("myName");

Of course, it is also possible to use any of the variants of creating a process engine, as described in the configuration section.

The contextDestroyed method of the context-listener delegates to ProcessEngines.destroy(). That will properly close all initialized process engines.

Chapter 5. Spring integration

While you can definitely use Activiti without Spring, we've provided some very nice integration features that are explained in this chapter.

ProcessEngineFactoryBean

The ProcessEngine can be configured as a regular Spring bean. The starting point of the integration is the class org.activiti.spring.ProcessEngineFactoryBean. That bean takes a process engine configuration and creates the process engine. This means that the creation and configuration of properties for Spring is the same as documented in the configuration section. For Spring integration the configuration and engine beans will look like this:

<bean id="processEngineConfiguration" class="org.activiti.spring.SpringProcessEngineConfiguration">
    ...
</bean>
  
<bean id="processEngine" class="org.activiti.spring.ProcessEngineFactoryBean">
  <property name="processEngineConfiguration" ref="processEngineConfiguration" />
</bean>
  

Note that the processEngineConfiguration bean now uses the org.activiti.spring.SpringProcessEngineConfiguration class.

Transactions

We'll explain the SpringTransactionIntegrationTest found in the Spring examples of the distribution step by step. Below is the Spring configuration file that we use in this example (you can find it in SpringTransactionIntegrationTest-context.xml). The section shown below contains the dataSource, transactionManager, processEngine and the Activiti Engine services.

When passing the DataSource to the SpringProcessEngineConfiguration (using property "dataSource"), Activiti uses a org.springframework.jdbc.datasource.TransactionAwareDataSourceProxy internally, which wraps the passed DataSource. This is done to make sure the SQL connections retrieved from the DataSource and the Spring transactions play well together. This implies that it's no longer needed to proxy the dataSource yourself in Spring configuration, although it's still allowed to pass a TransactionAwareDataSourceProxy into the SpringProcessEngineConfiguration. In this case no additional wrapping will occur.

Make sure when declaring a TransactionAwareDataSourceProxy in Spring configuration yourself, that you don't use it for resources that are already aware of Spring-transactions (e.g. DataSourceTransactionManager and JPATransactionManager need the un-proxied dataSource).

<beans xmlns="http://www.springframework.org/schema/beans" 
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:tx="http://www.springframework.org/schema/tx"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans   http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd
                           http://www.springframework.org/schema/tx      http://www.springframework.org/schema/tx/spring-tx-3.0.xsd">

  <bean id="dataSource" class="org.springframework.jdbc.datasource.SimpleDriverDataSource">
    <property name="driverClass" value="org.h2.Driver" />
    <property name="url" value="jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000" />
    <property name="username" value="sa" />
    <property name="password" value="" />
  </bean>

  <bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
    <property name="dataSource" ref="dataSource" />
  </bean>
  
  <bean id="processEngineConfiguration" class="org.activiti.spring.SpringProcessEngineConfiguration">
    <property name="dataSource" ref="dataSource" />
    <property name="transactionManager" ref="transactionManager" />
    <property name="databaseSchemaUpdate" value="true" />
    <property name="jobExecutorActivate" value="false" />
  </bean>
  
  <bean id="processEngine" class="org.activiti.spring.ProcessEngineFactoryBean">
    <property name="processEngineConfiguration" ref="processEngineConfiguration" />
  </bean>
  
  <bean id="repositoryService" factory-bean="processEngine" factory-method="getRepositoryService" />
  <bean id="runtimeService" factory-bean="processEngine" factory-method="getRuntimeService" />
  <bean id="taskService" factory-bean="processEngine" factory-method="getTaskService" />
  <bean id="historyService" factory-bean="processEngine" factory-method="getHistoryService" />
  <bean id="managementService" factory-bean="processEngine" factory-method="getManagementService" />

...

The remainder of that Spring configuration file contains the beans and configuration that we'll use in this particular example:

<beans>  
  ...
  <tx:annotation-driven transaction-manager="transactionManager"/>

  <bean id="userBean" class="org.activiti.spring.test.UserBean">
    <property name="runtimeService" ref="runtimeService" />
  </bean>

  <bean id="printer" class="org.activiti.spring.test.Printer" />

</beans>

First the application context is created with any of the Spring ways to do that. In this example you could use a classpath XML resource to configure our Spring application context:

ClassPathXmlApplicationContext applicationContext = 
    new ClassPathXmlApplicationContext("org/activiti/examples/spring/SpringTransactionIntegrationTest-context.xml");

or, since it is a test:

@ContextConfiguration("classpath:org/activiti/spring/test/transaction/SpringTransactionIntegrationTest-context.xml")

Then we can get the service beans and invoke methods on them. The ProcessEngineFactoryBean will have added an extra interceptor to the services that applies Propagation.REQUIRED transaction semantics on the Activiti service methods. So, for example, we can use the repositoryService to deploy a process like this:

RepositoryService repositoryService = (RepositoryService) applicationContext.getBean("repositoryService");
String deploymentId = repositoryService
  .createDeployment()
  .addClasspathResource("org/activiti/spring/test/hello.bpmn20.xml")
  .deploy()
  .getId();
    

The other way around also works. In this case, the Spring transaction will be around the userBean.hello() method and the Activiti service method invocation will join that same transaction.

UserBean userBean = (UserBean) applicationContext.getBean("userBean");
userBean.hello();

The UserBean looks like this. Remember from above in the Spring bean configuration we injected the repositoryService into the userBean.

public class UserBean {

  /** injected by Spring */
  private RuntimeService runtimeService;

  @Transactional
  public void hello() {
    // here you can do transactional stuff in your domain model
    // and it will be combined in the same transaction as 
    // the startProcessInstanceByKey to the Activiti RuntimeService
    runtimeService.startProcessInstanceByKey("helloProcess");
  }
  
  public void setRuntimeService(RuntimeService runtimeService) {
    this.runtimeService = runtimeService;
  }
}

Expressions

When using the ProcessEngineFactoryBean, by default, all expressions in the BPMN processes will also 'see' all the Spring beans. It's possible to limit the beans you want to expose in expressions or even exposing no beans at all using a map that you can configure. The example below exposes a single bean (printer), available to use under the key "printer". To have NO beans exposed at all, just pass an empty list as 'beans' property on the SpringProcessEngineConfiguration. When no 'beans' property is set, all Spring beans in the context will be available.

<bean id="processEngineConfiguration" class="org.activiti.spring.SpringProcessEngineConfiguration">
  ...
  <property name="beans">
    <map>
      <entry key="printer" value-ref="printer" />
    </map>
  </property>
</bean>
  
  <bean id="printer" class="org.activiti.examples.spring.Printer" />
    

Now the exposed beans can be used in expressions: for example, the SpringTransactionIntegrationTest hello.bpmn20.xml shows how a method on a Spring bean can be invoked using a UEL method expression:

<definitions id="definitions" ...>
  
  <process id="helloProcess">
  
    <startEvent id="start" />
    <sequenceFlow id="flow1" sourceRef="start" targetRef="print" />
    
    <serviceTask id="print" activiti:expression="#{printer.printMessage()}" />
    <sequenceFlow id="flow2" sourceRef="print" targetRef="end" />
    
    <endEvent id="end" />
    
  </process>

</definitions>

Where Printer looks like this:

public class Printer {

  public void printMessage() {
    System.out.println("hello world");
  }
}

And the Spring bean configuration (also shown above) looks like this:

<beans ...>
  ...

  <bean id="printer" class="org.activiti.examples.spring.Printer" />

</beans>

Automatic resource deployment

Spring integration also has a special feature for deploying resources. In the process engine configuration, you can specify a set of resources. When the process engine is created, all those resources will be scanned and deployed. There is filtering in place that prevents duplicate deployments. Only when the resources actually have changed, will new deployments be deployed to the Activiti DB. This makes sense in a lot of use case, where the Spring container is rebooted often (e.g. testing).

Here's an example:

<bean id="processEngineConfiguration" class="org.activiti.spring.SpringProcessEngineConfiguration">
  ...
  <property name="deploymentResources" value="classpath*:/org/activiti/spring/test/autodeployment/autodeploy.*.bpmn20.xml" />
</bean>
  
<bean id="processEngine" class="org.activiti.spring.ProcessEngineFactoryBean">
  <property name="processEngineConfiguration" ref="processEngineConfiguration" />
</bean>

Unit testing

When integrating with Spring, business processes can be tested very easily using the standard Activiti testing facilities. The following example shows how a business process is tested in a typical Spring-based unit test:

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration("classpath:org/activiti/spring/test/junit4/springTypicalUsageTest-context.xml")
public class MyBusinessProcessTest {
  
  @Autowired
  private RuntimeService runtimeService;
  
  @Autowired
  private TaskService taskService;
  
  @Autowired
  @Rule
  public ActivitiRule activitiSpringRule;
  
  @Test
  @Deployment
  public void simpleProcessTest() {
    runtimeService.startProcessInstanceByKey("simpleProcess");
    Task task = taskService.createTaskQuery().singleResult();
    assertEquals("My Task", task.getName());
  
    taskService.complete(task.getId());
    assertEquals(0, runtimeService.createProcessInstanceQuery().count());
   
  }
}      
      

Note that for this to work, you need to define a org.activiti.engine.test.ActivitiRule bean in the Spring configuration (which is injected by auto-wiring in the example above).

<bean id="activitiRule" class="org.activiti.engine.test.ActivitiRule">
  <property name="processEngine" ref="processEngine" />
</bean>        
      

Annotation-based configuration

[EXPERIMENTAL] The @EnableActiviti annotation is relatively new and could potentially change in the future.

An alternative to XML-based configuration is using the annotation-based way of configuring a Spring environment. This is pretty much similar to doing it the XML-way, except that the @Bean annotation is used and the configuration is written in Java. This has been always possible out-of-the-box with the Activiti-Spring integration.

Building on top of that (available for Spring 3.0+) is the @EnableActiviti annotation. In the simplest form it looks like this:

  @Configuration
  @EnableActiviti
  public static class SimplestConfiguration {
    
  }

This will create a Spring environment with an Activiti Process Engine configured using

  • a default in-memory H2 database, with auto-schema upgrade enabled.

  • a simple DataSourceTransactionManager

  • a default SpringJobExecutor

  • a scanner for bpmn20.xml files residing in the processes/ folder.

In such an environment, getting access to the Activiti Engine and services is simply done by injection:

  @Autowired
  private ProcessEngine processEngine;
  
  @Autowired
  private RuntimeService runtimeService;
  
  @Autowired
  private TaskService taskService;
  
  @Autowired
  private HistoryService historyService;
  
  @Autowired
  private RepositoryService repositoryService;
  
  @Autowired
  private ManagementService managementService;
  
  @Autowired
  private FormService formService;

Of course, these defaults can be customized. For example, if a datasource is configured, that datasource will be used instead of creating the default one. The same applies for the transaction manager, job executor, etc. For example in this piece of configuration:

  @Configuration
  @EnableActiviti
  public static class Config {
    
    @Bean
    public DataSource dataSource() {
        BasicDataSource basicDataSource = new BasicDataSource();
        basicDataSource.setUsername("sa");
        basicDataSource.setUrl("jdbc:h2:mem:anotherDatabase");
        basicDataSource.setDefaultAutoCommit(false);
        basicDataSource.setDriverClassName(org.h2.Driver.class.getName());
        basicDataSource.setPassword("");
        return basicDataSource;
    }
    
  }

Another database will be used instead of constructing the default one.

A more elaborate configuration for reference is shown below. Note the use of an AbstractActivitiConfigurer, which exposes access to the Process Engine configuration and can be used to tweak the configuration in detail.

@Configuration
@EnableActiviti
@EnableTransactionManagement(proxyTargetClass = true)
class JPAConfiguration {

    @Bean
    public OpenJpaVendorAdapter openJpaVendorAdapter() {
        OpenJpaVendorAdapter openJpaVendorAdapter = new OpenJpaVendorAdapter();
        openJpaVendorAdapter.setDatabasePlatform(H2Dictionary.class.getName());
        return openJpaVendorAdapter;
    }

    @Bean
    public DataSource dataSource() {
        BasicDataSource basicDataSource = new BasicDataSource();
        basicDataSource.setUsername("sa");
        basicDataSource.setUrl("jdbc:h2:mem:activiti");
        basicDataSource.setDefaultAutoCommit(false);
        basicDataSource.setDriverClassName(org.h2.Driver.class.getName());
        basicDataSource.setPassword("");
        return basicDataSource;
    }

    @Bean
    public LocalContainerEntityManagerFactoryBean entityManagerFactoryBean(
        OpenJpaVendorAdapter openJpaVendorAdapter, DataSource ds) {
        LocalContainerEntityManagerFactoryBean emf = new LocalContainerEntityManagerFactoryBean();
        emf.setPersistenceXmlLocation("classpath:/org/activiti/spring/test/jpa/custom-persistence.xml");
        emf.setJpaVendorAdapter(openJpaVendorAdapter);
        emf.setDataSource(ds);
        return emf;
    }

    @Bean
    public PlatformTransactionManager jpaTransactionManager(
        EntityManagerFactory entityManagerFactory) {
        return new JpaTransactionManager(entityManagerFactory);
    }

    @Bean
    public AbstractActivitiConfigurer abstractActivitiConfigurer(
        final EntityManagerFactory emf,
        final PlatformTransactionManager transactionManager) {

        return new AbstractActivitiConfigurer() {

            @Override
            public void postProcessSpringProcessEngineConfiguration(SpringProcessEngineConfiguration engine) {
                engine.setTransactionManager(transactionManager);
                engine.setJpaEntityManagerFactory(emf);
                engine.setJpaHandleTransaction(false);
                engine.setJobExecutorActivate(false);
                engine.setJpaCloseEntityManager(false);
                engine.setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_TRUE);
            }
        };
    }

    // A random bean
    @Bean
    public LoanRequestBean loanRequestBean() {
        return new LoanRequestBean();
    }
}

JPA with Hibernate 4.2.x

When using Hibernate 4.2.x JPA in service task or listener logic in the Activiti Engine an additional dependency to Spring ORM is needed. This is not needed for Hibernate 4.1.x or lower. The following dependency should be added:

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-orm</artifactId>
  <version>${org.springframework.version}</version>
</dependency>
      

Chapter 6. Deployment

Business archives

To deploy processes, they have to be wrapped in a business archive. A business archive is the unit of deployment to an Activiti Engine. A business archive is equivalent to a zip file. It can contain BPMN 2.0 processes, task forms, rules and any other type of file. In general, a business archive contains a collection of named resources.

When a business archive is deployed, it is scanned for BPMN files with a .bpmn20.xml or .bpmn extension. Each of those will be parsed and may contain multiple process definitions.

Note

Java classes present in the business archive will not be added to the classpath. All custom classes used in process definitions in the business archive (for example Java service tasks or event listener implementations) should be present on the activiti-engine's classpath in order to run the processes.

Deploying programmatically

Deploying a business archive from a zip file can be done like this:

String barFileName = "path/to/process-one.bar";
ZipInputStream inputStream = new ZipInputStream(new FileInputStream(barFileName));
    
repositoryService.createDeployment()
    .name("process-one.bar")
    .addZipInputStream(inputStream)
    .deploy();
	

It's also possible to build a deployment from individual resources. See the javadocs for more details.

Deploying with Activiti Explorer

The Activiti Explorer webapp allows uploading bar files (and single bpmn20.xml files) through the webapp user interface. Choose the Management tab and click on Deployment:

A popup window now allows you to select a file from your computer, or you can simply drag and drop to the designated area (if your browser supports it).

External resources

Process definitions live in the Activiti database. These process definitions can reference delegation classes when using Service Tasks or execution listeners or Spring beans from the Activiti configuration file. These classes and the Spring configuration file have to be available to all process engines that may execute the process definitions.

Java classes

All custom classes that are used in your process (e.g. JavaDelegates used in Service Tasks or event-listeners, TaskListeners, ...) should be present on the engine's classpath when an instance of the process is started.

During deployment of a business archive however, those classes don't have to be present on the classpath. This means that your delegation classes don't have to be on the classpath when deploying a new business archive with Ant.

When you are using the demo setup and you want to add your custom classes, you should add a jar containing your classes to the activiti-explorer or activiti-rest webapp lib. Don't forget to include the dependencies of your custom classes (if any) as well. Alternatively, you can include your dependencies in the libraries directory of your Tomcat installation, ${tomcat.home}/lib.

Using Spring beans from a process

When expressions or scripts use Spring beans, those beans have to be available to the engine when executing the process definition. If you are building your own webapp and you configure your process engine in your context as described in the spring integration section, that is straightforward. But bear in mind that you also should update the Activiti rest webapp with that context if you use it. You can do that by replacing the activiti.cfg.xml in the activiti-rest/lib/activiti-cfg.jar JAR file with an activiti-context.xml file containing your Spring context configuration.

Creating a single app

Instead of making sure that all process engines have all the delegation classes on their classpath and use the right Spring configuration, you may consider including the Activiti rest webapp inside your own webapp so that there is only a single ProcessEngine.

Versioning of process definitions

BPMN doesn't have a notion of versioning. That is actually good because the executable BPMN process file will probably live in a version control system repository (e.g. Subversion, Git or Mercurial) as part of your development project. Versions of process definitions are created during deployment. During deployment, Activiti will assign a version to the ProcessDefinition before it is stored in the Activiti DB.

For each process definition in a business archive the following steps are performed to initialize the properties key, version, name and id:

  • The process definition id attribute in the XML file is used as the process definition key property.

  • The process definition name attribute in the XML file is used as the process definition name property. If the name attribute is not specified, then id attribute is used as the name.

  • The first time a process with a particular key is deployed, version 1 is assigned. For all subsequent deployments of process definitions with the same key, the version will be set 1 higher then the maximum currently deployed version. The key property is used to distinguish process definitions.

  • The id property is set to {processDefinitionKey}:{processDefinitionVersion}:{generated-id}, where generated-id is a unique number added to guarantee uniqueness of the process id for the process definition caches in a clustered environment.

Take for example the following process

<definitions id="myDefinitions" >
  <process id="myProcess" name="My important process" >
    ...      

When deploying this process definition, the process definition in the database will look like this:

Table 6.1. 

idkeynameversion
myProcess:1:676myProcessMy important process1


Suppose we now deploy an updated version of the same process (e.g. changing some user tasks), but the id of the process definition remains the same. The process definition table will now contain the following entries:

Table 6.2. 

idkeynameversion
myProcess:1:676myProcessMy important process1
myProcess:2:870myProcessMy important process2


When the runtimeService.startProcessInstanceByKey("myProcess") is called, it will now use the process definition with version 2, as this is the latest version of the process definition.

Should we create a second process, as defined below and deploy this to Activiti, a third row will be added to the table.

<definitions id="myNewDefinitions" >
  <process id="myNewProcess" name="My important process" >
    ...      

The table will look like this:

Table 6.3. 

idkeynameversion
myProcess:1:676myProcessMy important process1
myProcess:2:870myProcessMy important process2
myNewProcess:1:1033myNewProcessMy important process1

Note how the key for the new process is different from our first process. Even though the name is the same (we should probably have changed that too), Activiti only considers the id attribute when distinguishing processes. The new process is therefore deployed with version 1.

Providing a process diagram

A process diagram image can be added to a deployment. This image will be stored in the Activiti repository and is accessible through the API. This image is also used to visualize the process in Activiti Explorer.

Suppose we have a process on our classpath, org/activiti/expenseProcess.bpmn20.xml that has a process key 'expense'. The following naming conventions for the process diagram image apply (in this specific order):

  • If an image resource exists in the deployment that has a name of the BPMN 2.0 XML file name concatenated with the process key and an image suffix, this image is used. In our example, this would be org/activiti/expenseProcess.expense.png (or .jpg/gif). In case you have multiple images defined in one BPMN 2.0 XML file, this approach makes most sense. Each diagram image will then have the process key in its file name.

  • If no such image exists, am image resource in the deployment matching the name of the BPMN 2.0 XML file is searched for. In our example this would be org/activiti/expenseProcess.png. Note that this means that every process definition defined in the same BPMN 2.0 file has the same process diagram image. In case there is only one process definition in each BPMN 2.0 XML file, this is obviously not a problem.

Example when deploying programmatically:

repositoryService.createDeployment()
  .name("expense-process.bar")
  .addClasspathResource("org/activiti/expenseProcess.bpmn20.xml")
  .addClasspathResource("org/activiti/expenseProcess.png")
  .deploy();

The image resource can be retrieved through the API afterwards:

  ProcessDefinition processDefinition = repositoryService.createProcessDefinitionQuery()
                                                         .processDefinitionKey("expense")
                                                         .singleResult();
  
  String diagramResourceName = processDefinition.getDiagramResourceName();
  InputStream imageStream = repositoryService.getResourceAsStream(processDefinition.getDeploymentId(), diagramResourceName);
       

Generating a process diagram

In case no image is provided in the deployment, as described in the previous section, the Activiti engine will generate a diagram image if the process definition contains the necessary 'diagram interchange' information.

The resource can be retrieved in exactly the same way as when an image is provided in the deployment.

If, for some reason, it is not necessary or wanted to generate a diagram during deployment the isCreateDiagramOnDeploy property can be set on the process engine configuration:

<property name="createDiagramOnDeploy" value="false" />

No diagram will be generated now.

Category

Both deployments and process definitions have user defined categories. The process definition category is initialized value in attribute in the BPMN file: <definitions ... targetNamespace="yourCategory" ...

The deployment category can be specified in the API like this:

repositoryService
    .createDeployment()
    .category("yourCategory")
    ...
    .deploy();

Chapter 7. BPMN 2.0 Introduction

What is BPMN?

See our FAQ entry on BPMN 2.0.

Defining a process

Note

This introduction is written under the assumption you are using the Eclipse IDE to create and edit files. Very little of this is specific to Eclipse, however. You can use any other tool you prefer to create XML files containing BPMN 2.0.

Create a new XML file (right-click on any project and select New->Other->XML-XML File) and give it a name. Make sure that the file ends with .bpmn20.xml or .bpmn, since otherwise the engine won't pick up this file for deployment.

The root element of the BPMN 2.0 schema is the definitions element. Within this element, multiple process definitions can be defined (although we advise to have only one process definition in each file, since this simplifies maintenance later in the development process). An empty process definition looks as listed below. Note that the minimal definitions element only needs the xmlns and targetNamespace declaration. The targetNamespace can be anything, and is useful for categorizing process definitions.

<definitions 
  xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
  xmlns:activiti="http://activiti.org/bpmn"
  targetNamespace="Examples">

  <process id="myProcess" name="My First Process">
    ..
  </process>

</definitions>

Optionally you can also add the online schema location of the BPMN 2.0 XML schema, as an alternative to the XML catalog configuration in Eclipse.

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.omg.org/spec/BPMN/20100524/MODEL 
                    http://www.omg.org/spec/BPMN/2.0/20100501/BPMN20.xsd

The process element has two attributes:

  • id: this attribute is required and maps to the key property of an Activiti ProcessDefinition object. This id can then be used to start a new process instance of the process definition, through the startProcessInstanceByKey method on the RuntimeService. This method will always take the latest deployed version of the process definition.

    ProcessInstance processInstance = runtimeService.startProcessInstanceByKey("myProcess");

    Important to note here is that this is not the same as calling the startProcessInstanceById method. This method expects the String id that was generated at deploy time by the Activiti engine, and can be retrieved by calling the processDefinition.getId() method. The format of the generated id is 'key:version', and the length is constrained to 64 characters. If you get an ActivitiException stating that the generated id is too long, limit the text in the key field of the process.

  • name: this attribute is optional and maps to the name property of a ProcessDefinition. The engine itself doesn't use this property, so it can be used for displaying a more human-friendly name in a user interface, for example.

Getting started: 10 minute tutorial

In this section we will cover a (very simple) business process that we will use to introduce some basic Activiti concepts and the Activiti API.

Prerequisites

This tutorial assumes that you have the Activiti demo setup running, and that you are using a standalone H2 server. Edit db.properties and set the jdbc.url=jdbc:h2:tcp://localhost/activiti, and then run the standalone server according to H2's documentation.

Goal

The goal of this tutorial is to learn about Activiti and some basic BPMN 2.0 concepts. The end result will be a simple Java SE program that deploys a process definition, and interacts with this process through the Activiti engine API. We'll also touch some of the tooling around Activiti. Of course, what you'll learn in this tutorial can also be used when building your own web applications around your business processes.

Use case

The use case is straightforward: we have a company, let's call it BPMCorp. In BPMCorp, a financial report needs to be written every month for the company shareholders. This is the responsibility of the accountancy department. When the report is finished, one of the members of the upper management needs to approve the document before it is sent to all the shareholders.

Process diagram

The business process as described above can be graphically visualized using the Activiti Designer. However, for this tutorial we'll type the XML ourselves, as we learn the most this way at this point. The graphical BPMN 2.0 notation of our process looks like this:

What we see is a none Start Event (circle on the left), followed by two User Tasks: 'Write monthly financial report' and 'Verify monthly financial report', ending in a none end event (circle with thick border on the right).

XML representation

The XML version of this business process (FinancialReportProcess.bpmn20.xml) looks as shown below. It's easy to recognize the main elements of our process (click on the links for going to the detailed section of that BPMN 2.0 construct):

  • The (none) start event learns us what the entry point to the process is.

  • The User Tasks declarations are the representation of the human tasks of our process. Note that the first task is assigned to the accountancy group, while the second task is assigned to the management group. See the section on user task assignment for more information on how users and groups can be assigned to user tasks.

  • The process ends when the none end event is reached.

  • The elements are connected with each other through sequence flows. These sequence flow have a source and target, defining the direction of the sequence flow.

<definitions id="definitions"
  targetNamespace="http://activiti.org/bpmn20" 
  xmlns:activiti="http://activiti.org/bpmn"
  xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL">
	
	<process id="financialReport" name="Monthly financial report reminder process">
	  
	  <startEvent id="theStart" />
	    
	  <sequenceFlow id='flow1' sourceRef='theStart' targetRef='writeReportTask' />
	    
	  <userTask id="writeReportTask" name="Write monthly financial report" >
	    <documentation>
	      Write monthly financial report for publication to shareholders.
	    </documentation>
	    <potentialOwner>
	      <resourceAssignmentExpression>
	        <formalExpression>accountancy</formalExpression>
	      </resourceAssignmentExpression>
	    </potentialOwner>
	  </userTask>
	    
	  <sequenceFlow id='flow2' sourceRef='writeReportTask' targetRef='verifyReportTask' />
	      
	  <userTask id="verifyReportTask" name="Verify monthly financial report" >
	    <documentation>
	      Verify monthly financial report composed by the accountancy department.
	      This financial report is going to be sent to all the company shareholders.  
	    </documentation>
	    <potentialOwner>
	      <resourceAssignmentExpression>
	        <formalExpression>management</formalExpression>
	      </resourceAssignmentExpression>
	    </potentialOwner>
	  </userTask>
	    
	  <sequenceFlow id='flow3' sourceRef='verifyReportTask' targetRef='theEnd' />
	      
	  <endEvent id="theEnd" />
	      
	</process>
	
</definitions>

Starting a process instance

We have now created the process definition of our business process. From such a process definition, we can create process instances. In this case, one process instance would match with the creation and verification of a single financial report for a particular month. All the process instances share the same process definition.

To be able to create process instances from a given process definition, we must first deploy this process definition. Deploying a process definition means two things:

  • The process definition will be stored in the persistent datastore that is configured for your Activiti engine. So by deploying our business process, we make sure that the engine will find the process definition after an engine reboot.

  • The BPMN 2.0 process file will be parsed to an in-memory object model that can be manipulated through the Activiti API.

More information on deployment can be found in the dedicated section on deployment.

As described in that section, deployment can happen in several ways. One way is through the API as follows. Note that all interaction with the Activiti engine happens through its services.

Deployment deployment = repositoryService.createDeployment()
  .addClasspathResource("FinancialReportProcess.bpmn20.xml")
  .deploy();

Now we can start a new process instance using the id we defined in the process definition (see process element in the XML file). Note that this id in Activiti terminology is called the key.

ProcessInstance processInstance = runtimeService.startProcessInstanceByKey("financialReport");

This will create a process instance that will first go through the start event. After the start event, it follows all the outgoing sequence flows (only one in this case) and the first task ('write monthly financial report') is reached. The Activiti engine will now store a task in the persistent database. At this point, the user or group assignments attached to the task are resolved and also stored in the database. It's important to note that the Activiti engine will continue process execution steps until it reaches a wait state, such as the user task. At such a wait state, the current state of the process instance is stored in the database. It remains in that state until a user decides to complete their task. At that point, the engine will continue until it reaches a new wait state or the end of the process. When the engine reboots or crashes in the meantime, the state of the process is safe and well in the database.

After the task is created, the startProcessInstanceByKey method will return since the user task activity is a wait state. In this case, the task is assigned to a group, which means that every member of the group is a candidate to perform the task.

We can now throw this all together and create a simple Java program. Create a new Eclipse project and add the Activiti jars and dependencies to its classpath (these can be found in the libs folder of the Activiti distribution). Before we can call the Activiti services, we must first construct a ProcessEngine that gives us access to the services. Here we use the 'standalone' configuration, which constructs a ProcessEngine that uses the database also used in the demo setup.

You can download the process definition XML here. This file contains the XML as shown above, but also contains the necessary BPMN diagram interchange information to visualize the process in the Activiti tools.

public static void main(String[] args) {
    
  // Create Activiti process engine
  ProcessEngine processEngine = ProcessEngineConfiguration
    .createStandaloneProcessEngineConfiguration()
    .buildProcessEngine();
  
  // Get Activiti services
  RepositoryService repositoryService = processEngine.getRepositoryService();
  RuntimeService runtimeService = processEngine.getRuntimeService();
  
  // Deploy the process definition
  repositoryService.createDeployment()
    .addClasspathResource("FinancialReportProcess.bpmn20.xml")
    .deploy();
    
  // Start a process instance
  runtimeService.startProcessInstanceByKey("financialReport");
}

Task lists

We can now retrieve this task through the TaskService by adding the following logic:

List<Task> tasks = taskService.createTaskQuery().taskCandidateUser("kermit").list();

Note that the user we pass to this operation needs to be a member of the accountancy group, since that was declared in the process definition:

<potentialOwner>
  <resourceAssignmentExpression>
    <formalExpression>accountancy</formalExpression>
  </resourceAssignmentExpression>
</potentialOwner>

We could also use the task query API to get the same results using the name of the group. We can now add the following logic to our code:

TaskService taskService = processEngine.getTaskService();
List<Task> tasks = taskService.createTaskQuery().taskCandidateGroup("accountancy").list();

Since we've configured our ProcessEngine to use the same database as the demo setup is using, we can now log into Activiti Explorer. By default, no user is in the accountancy group. Login with kermit/kermit, click Groups and then "Create group". Then click Users and add the group to fozzie. Now login with fozzie/fozzie, and we will find that we can start our business process after selecting the Processes page and and clicking on the 'Start Process' link in the 'Actions' column corresponding to the 'Monthly financial report' process.

As explained, the process will execute up to the first user task. Since we're logged in as kermit, we can see that there is a new candidate task available for him after we've started a process instance. Select the Tasks page to view this new task. Note that even if the process was started by someone else, the task would still be visible as a candidate task to everyone in the accountancy group.

Claiming the task

An accountant now needs to claim the task. By claiming the task, the specific user will become the assignee of the task and the task will disappear from every task list of the other members of the accountancy group. Claiming a task is programmatically done as follows:

taskService.claim(task.getId(), "fozzie");

The task is now in the personal task list of the one that claimed the task.

List<Task> tasks = taskService.createTaskQuery().taskAssignee("fozzie").list();

In the Activiti Explorer UI, clicking the claim button will call the same operation. The task will now move to the personal task list of the logged on user. You also see that the assignee of the task changed to the current logged in user.

Completing the task

The accountant can now start working on the financial report. Once the report is finished, he can complete the task, which means that all work for that task is done.

taskService.complete(task.getId());

For the Activiti engine, this is an external signal that the process instance execution must be continued. The task itself is removed from the runtime data. The single outgoing transition out of the task is followed, moving the execution to the second task ('verification of the report'). The same mechanism as described for the first task will now be used to assign the second task, with the small difference that the task will be assigned to the management group.

In the demo setup, completing the task is done by clicking the complete button in the task list. Since Fozzie isn't an accountant, we need to log out of the Activiti Explorer and login in as kermit (who is a manager). The second task is now visible in the unassigned task lists.

Ending the process

The verification task can be retrieved and claimed in exactly the same way as before. Completing this second task will move process execution to the end event, which finishes the process instance. The process instance and all related runtime execution data are removed from the datastore.

When you log into Activiti Explorer you can verify this, since no records will be found in the table where the process executions are stored.

Programmatically, you can also verify that the process is ended using the historyService

HistoryService historyService = processEngine.getHistoryService();
HistoricProcessInstance historicProcessInstance = 
historyService.createHistoricProcessInstanceQuery().processInstanceId(procId).singleResult();
System.out.println("Process instance end time: " + historicProcessInstance.getEndTime());

Code overview

Combine all the snippets from previous sections, and you should have something like this (this code takes in account that you probably will have started a few process instances through the Activiti Explorer UI. As such, it always retrieves a list of tasks instead of one task, so it always works):

public class TenMinuteTutorial {
  
  public static void main(String[] args) {
    
    // Create Activiti process engine
    ProcessEngine processEngine = ProcessEngineConfiguration
      .createStandaloneProcessEngineConfiguration()
      .buildProcessEngine();
    
    // Get Activiti services
    RepositoryService repositoryService = processEngine.getRepositoryService();
    RuntimeService runtimeService = processEngine.getRuntimeService();
    
    // Deploy the process definition
    repositoryService.createDeployment()
      .addClasspathResource("FinancialReportProcess.bpmn20.xml")
      .deploy();
    
    // Start a process instance
    String procId = runtimeService.startProcessInstanceByKey("financialReport").getId();
    
    // Get the first task
    TaskService taskService = processEngine.getTaskService();
    List<Task> tasks = taskService.createTaskQuery().taskCandidateGroup("accountancy").list();
    for (Task task : tasks) {
      System.out.println("Following task is available for accountancy group: " + task.getName());
      
      // claim it
      taskService.claim(task.getId(), "fozzie");
    }
    
    // Verify Fozzie can now retrieve the task
    tasks = taskService.createTaskQuery().taskAssignee("fozzie").list();
    for (Task task : tasks) {
      System.out.println("Task for fozzie: " + task.getName());
      
      // Complete the task
      taskService.complete(task.getId());
    }
    
    System.out.println("Number of tasks for fozzie: " 
            + taskService.createTaskQuery().taskAssignee("fozzie").count());
    
    // Retrieve and claim the second task
    tasks = taskService.createTaskQuery().taskCandidateGroup("management").list();
    for (Task task : tasks) {
      System.out.println("Following task is available for accountancy group: " + task.getName());
      taskService.claim(task.getId(), "kermit");
    }
    
    // Completing the second task ends the process
    for (Task task : tasks) {
      taskService.complete(task.getId());
    }
    
    // verify that the process is actually finished
    HistoryService historyService = processEngine.getHistoryService();
    HistoricProcessInstance historicProcessInstance = 
      historyService.createHistoricProcessInstanceQuery().processInstanceId(procId).singleResult();
    System.out.println("Process instance end time: " + historicProcessInstance.getEndTime());
  }

}

This code is also available as a unit test shipped with the examples (yes, you should unit test your processes! Read all about it in the unit testing section).

Future enhancements

It's easy to see that this business process is too simple to be usable in reality. However, as you are going through the BPMN 2.0 constructs available in Activiti, you will be able to enhance the business process by :

  • defining gateways that act as decisions. This way, a manager could reject the financial report which would recreate the task for the accountant.

  • declaring and using variables, such that we can store or reference the report so that it can be visualized in the form.

  • defining a service task at the end of the process that will send the report to every shareholder.

  • etc.

Chapter 8. BPMN 2.0 Constructs

This chapter covers the BPMN 20 constructs supported by Activiti as well as custom extensions to the BPMN standard.

Custom extensions

The BPMN 2.0 standard is a good thing for all parties involved. End-users don't suffer from a vendor lock-in that comes by depending on a proprietary solution. Frameworks, and particularly open-source frameworks such as Activiti, can implement a solution that has the same (and often better implemented ;-) features as those of a big vendor. Due to the BPMN 2.0 standard, the transition from such a big vendor solution towards Activiti is an easy and smooth path.

The downside of a standard however, is the fact that it is always the result of many discussions and compromises between different companies (and often visions). As a developer reading the BPMN 2.0 XML of a process definition, sometimes it feels like certain constructs or way to do things are too cumbersome. Since Activiti puts ease of development as a top-priority, we introduced something called the 'Activiti BPMN extensions'. These 'extensions' are new constructs or ways to simplify certain constructs, that are not in the BPMN 2.0 specification.

Although the BPMN 2.0 specification clearly states that it was made for custom extension, we make sure that:

  • The prerequisite of such a custom extension is that there always must be a simple transformation to the standard way of doing things. So when you decide to use a custom extension, you don't have to be afraid that there is no way back.

  • When using a custom extension, this is always clearly indicated by giving the new XML element, attribute, etc. the activiti: namespace prefix.

  • The goal of these extensions is to eventually push them back into a next version of the BPMN specification, or at least trigger a discussion that can lead to a revision of that specific BPMN construct.

So whether you want to use a custom extension or not, is completely up to you. Several factors will influence this decision (graphical editor usage, company policy, etc.). We only provide them since we believe that some points in the standard can be done simpler or more efficient. Feel free to give us (positive and/or negative) feedback on our extensions, or to post new ideas for custom extensions. Who knows, some day your idea might pop up in the specification!.

Events

Events are used to model something that happens during the lifetime process. Events are always visualized as a circle. In BPMN 2.0, there exist two main event categories: catching or throwing event.

  • Catching: when process execution arrives in the event, it will wait for a trigger to happen. The type of trigger is defined by the inner icon or the type declaration in the XML. Catching events are visually differentiated from a throwing event by the inner icon that is not filled (i.e. it is white).

  • Throwing: when process execution arrives in the event, a trigger is fired. The type of trigger is defined by the inner icon or the type declaration in the XML. Throwing events are visually differentiated from a catching event by the inner icon that is filled with black.

Event Definitions

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).

Timer Event Definitions

Timer events are events which are triggered by defined timer. They can be used as start event, intermediate event or boundary event

Timer definition must have exactly one element from the following:

  • timeDate. This format specifies fixed date in ISO 8601 format, when trigger will be fired. Example:

    <timerEventDefinition>
        <timeDate>2011-03-11T12:13:14</timeDate>
    </timerEventDefinition>

  • timeDuration. To specify how long the timer should run before it is fired, a timeDuration can be specified as sub-element of timerEventDefinition. The format used is the ISO 8601 format (as required by the BPMN 2.0 specification). Example (interval lasting 10 days):

    <timerEventDefinition>
        <timeDuration>P10D</timeDuration>
    </timerEventDefinition>

  • timeCycle. Specifies repeating interval, which can be useful for starting process periodically, or for sending multiple reminders for overdue user task. Time cycle element can be in two formats. First is the format of recurring time duration, as specified by ISO 8601 standard. Example (3 repeating intervals, each lasting 10 hours):

    <timerEventDefinition>
        <timeCycle>R3/PT10H</timeCycle>
    </timerEventDefinition>

    Additionally, you can specify time cycle using cron expressions, example below shows trigger firing every 5 minutes, starting at full hour:

    0 0/5 * * * ?

    Please see tutorial for using cron expressions.

    Note: The first symbol denotes seconds, not minutes as in normal Unix cron.

    The recurring time duration is better suited for handling relative timers, which are calculated with respect to some particular point in time (e.g. time when user task was started), while cron expressions can handle absolute timers - which is particularly useful for timer start events.

You can use expressions for the timer event definitions, by doing so you can influence the timer definition based on process variables. The process variables must contain the ISO 8601 (or cron for cycle type) string for appropriate timer type.

  <boundaryEvent id="escalationTimer" cancelActivity="true" attachedToRef="firstLineSupport">
     <timerEventDefinition>
      <timeDuration>${duration}</timeDuration>
    </timerEventDefinition>
  </boundaryEvent>
  

Note: timers are only fired when the job executor is enabled (i.e. jobExecutorActivate needs to be set to true in the activiti.cfg.xml, since the job executor is disabled by default).

Error Event Definitions

Error events are events which are triggered by a defined error.

Important note: a BPMN error is NOT the same as a Java exception. In fact, the two have nothing in common. BPMN error events are a way of modeling business exceptions. Java exceptions are handled in their own specific way.

An error event definition references an error element. The following is an example of an error end event, referencing an error declaration:
<endEvent id="myErrorEndEvent">
  <errorEventDefinition errorRef="myError" />
</endEvent>     
         
An error event handler references the same error element to declare that it catches the error.

Signal Event Definitions

Signal events are events which reference a named signal. A signal is an event of global scope (broadcast semantics) and is delivered to all active handlers.

A signal event definition is declared using the signalEventDefinition element. The attribute signalRef references a signal element declared as a child element of the definitions root element. The following is an excerpt of a process where a signal event is thrown and caught by intermediate events.

<definitions... >
	<!-- declaration of the signal -->
	<signal id="alertSignal" name="alert" />
	
	<process id="catchSignal">
		<intermediateThrowEvent id="throwSignalEvent" name="Alert">
			<!-- signal event definition -->
			<signalEventDefinition signalRef="alertSignal" />
		</intermediateThrowEvent>
		...
		<intermediateCatchEvent id="catchSignalEvent" name="On Alert">
			<!-- signal event definition -->
			<signalEventDefinition signalRef="alertSignal" />
		</intermediateCatchEvent>
		...		
	</process>
</definitions>

The signalEventDefinitions reference the same signal element.

Throwing a Signal Event

A signal can either be thrown by a process instance using a bpmn construct or programmatically using java API. The following methods on the org.activiti.engine.RuntimeService can be used to throw a signal programmatically:

RuntimeService.signalEventReceived(String signalName);
RuntimeService.signalEventReceived(String signalName, String executionId);  
	  			

The difference between signalEventReceived(String signalName); and signalEventReceived(String signalName, String executionId); is that the first method throws the signal globally to all subscribed handlers (broadcast semantics) and the second method delivers the signal to a specific execution only.

Catching a Signal Event

A signal event can be caught by an intermediate catch signal event or a signal boundary event.

Querying for Signal Event subscriptions

It is possible to query for all executions which have subscribed to a specific signal event:

 List<Execution> executions = runtimeService.createExecutionQuery()
      .signalEventSubscriptionName("alert")
      .list();
	    	

We could then use the signalEventReceived(String signalName, String executionId) method to deliver the signal to these executions.

Signal event scope

By default, signals are broadcast process engine wide. This means that you can throw a signal event in a process instance, and other process instances with different process definitions can react on the occurrence of this event.

However, sometimes it is wanted to react to a signal event only within the same process instance. A use case for example is a synchronization mechanism in the process instance, if two or more activities are mutually exclusive.

To restrict the scope of the signal event, add the (non-BPMN 2.0 standard!) scope attribute to the signal event definition:

<signal id="alertSignal" name="alert" activiti:scope"processInstance"/>

The default value for this is attribute is "global".

Signal Event example(s)

The following is an example of two separate processes communicating using signals. The first process is started if an insurance policy is updated or changed. After the changes have been reviewed by a human participant, a signal event is thrown, signaling that a policy has changed:

This event can now be caught by all process instances which are interested. The following is an example of a process subscribing to the event.

Note: it is important to understand that a signal event is broadcast to all active handlers. This means in the case of the example given above, that all instances of the process catching the signal would receive the event. In this case this is what we want. However, there are also situations where the broadcast behavior is unintended. Consider the following process:

The pattern described in the process above is not supported by Activiti. The idea is that the error thrown while performing the "do something" task is caught by the boundary error event and would be propagated to the parallel path of execution using the signal throw event and then interrupt the "do something in parallel" task. So far Activiti would perform as expected. The signal would be propagated to the catching boundary event and interrupt the task. However, due to the broadcast semantics of the signal, it would also be propagated to all other process instances which have subscribed to the signal event. In this case, this might not be what we want.

Note: the signal event does not perform any kind of correlation to a specific process instance. On the contrary, it is broadcast to all process instances. If you need to deliver a signal to a specific process instance only, perform correlation manually and use signalEventReceived(String signalName, String executionId) and the appropriate query mechanisms.

Message Event Definitions

Message events are events which reference a named message. A message has a name and a payload. Unlike a signal, a message event is always directed at a single receiver.

A message event definition is declared using the messageEventDefinition element. The attribute messageRef references a message element declared as a child element of the definitions root element. The following is an excerpt of a process where two message events is declared and referenced by a start event and an intermediate catching message event.

<definitions id="definitions" 
  xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
  xmlns:activiti="http://activiti.org/bpmn"
  targetNamespace="Examples"
  xmlns:tns="Examples">
  
  <message id="newInvoice" name="newInvoiceMessage" />
  <message id="payment" name="paymentMessage" />
  
  <process id="invoiceProcess">  
  
    <startEvent id="messageStart" >
    	<messageEventDefinition messageRef="newInvoice" />
    </startEvent>
    ...    
    <intermediateCatchEvent id="paymentEvt" >
    	<messageEventDefinition messageRef="payment" />
    </intermediateCatchEvent>
    ...
  </process>

</definitions>

Throwing a Message Event

As an embeddable process engine, activiti is not concerned with actually receiving a message. This would be environment dependent and entail platform-specific activities like connecting to a JMS (Java Messaging Service) Queue/Topic or processing a Webservice or REST request. The reception of messages is therefore something you have to implement as part of the application or infrastructure into which the process engine is embedded.

After you have received a message inside your application, you must decide what to do with it. If the message should trigger the start of a new process instance, choose between the following methods offered by the runtime service:

ProcessInstance startProcessInstanceByMessage(String messageName);
ProcessInstance startProcessInstanceByMessage(String messageName, Map<String, Object> processVariables);
ProcessInstance startProcessInstanceByMessage(String messageName, String businessKey, Map<String, Object> processVariables); 		

These methods allow starting a process instance using the referenced message.

If the message needs to be received by an existing process instance, you first have to correlate the message to a specific process instance (see next section) and then trigger the continuation of the wating execution. The runtime service offers the following methods for triggering an execution based on a message event subscription:

void messageEventReceived(String messageName, String executionId);
void messageEventReceived(String messageName, String executionId, HashMap<String, Object> processVariables);	

Querying for Message Event subscriptions

Activiti supports message start events and intermediate message events.
  • In the case of a message start event, the message event subscription is associated with a particular process definition. Such message subscriptions can be queried using a ProcessDefinitionQuery:

    ProcessDefinition processDefinition = repositoryService.createProcessDefinitionQuery()
          .messageEventSubscription("newCallCenterBooking")
          .singleResult();
    	    	

    Since there can only be one process definition for a specific message subscription, the query always returns zero or one results. If a process definition is updated, only the newest version of the process definition has a subscription to the message event.

  • In the case of an intermediate catch message event, the message event subscription is associated with a particular execution. Such message event subscriptions can be queried using a ExecutionQuery:

    Execution execution = runtimeService.createExecutionQuery()
          .messageEventSubscriptionName("paymentReceived")
          .variableValueEquals("orderId", message.getOrderId())
          .singleResult();

    Such queries are called correlation queries and usually require knowledge about the processes (in this case that there will be at most one process instance for a given orderId).

Message Event example(s)

The following is an example of a process which can be started using two different messages:

This is useful if the process needs alternative ways to react to different start events but eventually continues in a uniform way.

Start Events

A start event indicates where a process starts. The type of start event (process starts on arrival of message, on specific time intervals, etc.), defining how the process is started is shown as a small icon in the visual representation of the event. In the XML representation, the type is given by the declaration of a sub-element.

Start events are always catching: conceptually the event is (at any time) waiting until a certain trigger happens.

In a start event, following Activiti-specific properties can be specified:

  • initiator: identifies the variable name in which the authenticated user id will be stored when the process is started. Example:

    <startEvent id="request" activiti:initiator="initiator" />

    The authenticated user must be set with the method IdentityService.setAuthenticatedUserId(String) in a try-finally block like this:

    try {
      identityService.setAuthenticatedUserId("bono");
      runtimeService.startProcessInstanceByKey("someProcessKey");
    } finally {
      identityService.setAuthenticatedUserId(null);
    }
    

    This code is baked into the Activiti Explorer application. So it works in combination with Chapter 9, Forms

None Start Event

Description

A 'none' start event technically means that the trigger for starting the process instance is unspecified. This means that the engine cannot anticipate when the process instance must be started. The none start event is used when the process instance is started through the API by calling one of the startProcessInstanceByXXX methods.

ProcessInstance processInstance = runtimeService.startProcessInstanceByXXX();

Note: a subprocess always has a none start event.

Graphical notation

A none start event is visualized as a circle with no inner icon (i.e. no trigger type).

XML representation

The XML representation of a none start event is the normal start event declaration, without any sub-element (other start event types all have a sub-element declaring the type).

<startEvent id="start" name="my start event" />

Custom extensions for the none start event

formKey: references to a form template that users have to fill in when starting a new process instance. More information can be found in the forms section Example:

<startEvent id="request" activiti:formKey="org/activiti/examples/taskforms/request.form" />

Timer Start Event

Description

A timer start event is used to create process instance at given time. It can be used both for processes which should start only once and for processes that should start in specific time intervals.

Note: a subprocess cannot have a timer start event.

Note: start timer event is scheduled as soon as process is deployed. There is no need to call startProcessInstanceByXXX, although calling start process methods is not restricted and will cause one more starting of the process at the time of startProcessInstanceByXXX Invocation.

Note: when a new version of a process with a start timer event is deployed, the job corresponding with the previous timer will be removed. The reasoning is that normally it is not wanted to keep automatically starting new process instances of this old version of the process.

Graphical notation

A none start event is visualized as a circle with clock inner icon.

XML representation

The XML representation of a timer start event is the normal start event declaration, with timer definition sub-element. Please refer to timer definitions for configuration details. for details on configuration details.

Example: process will start 4 times, in 5 minute intervals, starting on 11th march 2011, 12:13

        <startEvent id="theStart">
            <timerEventDefinition>
                <timeCycle>R4/2011-03-11T12:13/PT5M</timeCycle>
            </timerEventDefinition>
        </startEvent>
           

Example: process will start once, on selected date

        <startEvent id="theStart">
            <timerEventDefinition>
                <timeDate>2011-03-11T12:13:14</timeDate>
            </timerEventDefinition>
        </startEvent>
           

Message Start Event

Description

A message start event can be used to start a process instance using a named message. This effectively allows us to select the right start event from a set of alternative start events using the message name.

When deploying a process definition with one or more message start events, the following considerations apply:

  • The name of the message start event must be unique across a given process definition. A process definition must not have multiple message start events with the same name. Activiti throws an exception upon deployment of a process definition such that two or more message start events reference the same message of if two or more message start events reference messages with the same message name.

  • The name of the message start event must be unique across all deployed process definitions. Activiti throws an exception upon deployment of a process definition such that one or more message start events reference a message with the same name as a message start event already deployed by a different process definition.

  • Process versioning: Upon deployment of a new version of a process definition, the message subscriptions of the previous version are cancelled. This is also true for message events that are not present in the new version.

When starting a process instance, a message start event can be triggered using the following methods on the RuntimeService:

ProcessInstance startProcessInstanceByMessage(String messageName);
ProcessInstance startProcessInstanceByMessage(String messageName, Map<String, Object> processVariables);
ProcessInstance startProcessInstanceByMessage(String messageName, String businessKey, Map<String, Object< processVariables); 
	  			

The messageName is the name given in the name attribute of the message element referenced by the messageRef attribute of the messageEventDefinition. The following considerations apply when starting a process instance:

  • Message start events are only supported on top-level processes. Message start events are not supported on embedded sub processes.

  • If a process definition has multiple message start events, runtimeService.startProcessInstanceByMessage(...) allows to select the appropriate start event.

  • If a process definition has multiple message start events and a single none start event, runtimeService.startProcessInstanceByKey(...) and runtimeService.startProcessInstanceById(...) starts a process instance using the none start event.

  • If a process definition has multiple message start events and no none start event, runtimeService.startProcessInstanceByKey(...) and runtimeService.startProcessInstanceById(...) throw an exception.

  • If a process definition has a single message start event, runtimeService.startProcessInstanceByKey(...) and runtimeService.startProcessInstanceById(...) start a new process instance using the message start event.

  • If a process is started from a call activity, message start event(s) are only supported if

    • in addition to the message start event(s), the process has a single none start event

    • the process has a single message start event and no other start events.

Graphical notation

A message start event is visualized as a circle with a message event symbol. The symbol is unfilled, to visualize the catching (receiving) behavior.

XML representation

The XML representation of a message start event is the normal start event declaration with a messageEventDefinition child-element:

<definitions id="definitions" 
  xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
  xmlns:activiti="http://activiti.org/bpmn"
  targetNamespace="Examples"
  xmlns:tns="Examples">
  
  <message id="newInvoice" name="newInvoiceMessage" />
  
  <process id="invoiceProcess">  
  
    <startEvent id="messageStart" >
    	<messageEventDefinition messageRef="tns:newInvoice" />
    </startEvent>
    ...    
  </process>

</definitions>

Signal Start Event

Description

A signal start event can be used to start a process instance using a named signal. The signal can be 'fired' from within a process instance using the intermediary signal throw event or through the API (runtimService.signalEventReceivedXXX methods). In both cases, all process definitions that have a signal start event with the same name will be started.

Note that in both cases, it is also possible to chose between a synchronous and asynchronous starting of the process instances.

The signalName that must be passed in the API is the name given in the name attribute of the signal element referenced by the signalRef attribute of the signalEventDefinition.

Graphical notation

A signal start event is visualized as a circle with a signal event symbol. The symbol is unfilled, to visualize the catching (receiving) behavior.

XML representation

The XML representation of a message start event is the normal start event declaration with a messageEventDefinition child-element:

    <signal id="theSignal" name="The Signal" />

    <process id="processWithSignalStart1">
        <startEvent id="theStart">
          <signalEventDefinition id="theSignalEventDefinition" signalRef="theSignal"  />
        </startEvent>
        <sequenceFlow id="flow1" sourceRef="theStart" targetRef="theTask" />
        <userTask id="theTask" name="Task in process A" />
        <sequenceFlow id="flow2" sourceRef="theTask" targetRef="theEnd" />
        <endEvent id="theEnd" />
    </process>

Error Start Event

Description

An error start event can be used to trigger an Event Sub-Process. An error start event cannot be used for starting a process instance.

An error start event is always interrupting.

Graphical notation

A error start event is visualized as a circle with an error event symbol. The symbol is unfilled, to visualize the catching (receiving) behavior.

XML representation

The XML representation of an error start event is the normal start event declaration with an errorEventDefinition child-element:

<startEvent id="messageStart" >
	<errorEventDefinition errorRef="someError" />
</startEvent>

End Events

An end event signifies the end (of a path) of a (sub)process. An end event is always throwing. This means that when process execution arrives in the end event, a result is thrown. The type of result is depicted by the inner black icon of the event. In the XML representation, the type is given by the declaration of a sub-element.

None End Event

Description

A 'none' end event means that the result thrown when the event is reached is unspecified. As such, the engine will not do anything extra besides ending the current path of execution.

Graphical notation

A none end event is visualized as a circle with a thick border with no inner icon (no result type).

XML representation

The XML representation of a none end event is the normal end event declaration, without any sub-element (other end event types all have a sub-element declaring the type).

<endEvent id="end" name="my end event" />

Error End Event

Description

When process execution arrives in an error end event, the current path of execution is ended and an error is thrown. This error can caught by a matching intermediate boundary error event. In case no matching boundary error event is found, an exception will be thrown.

Graphical notation

An error end event is visualized as a typical end event (circle with thick border), with the error icon inside. The error icon is completely black, to indicate the throwing semantics.

XML representation

And error end event is represented as an end event, with a errorEventDefinition child element.

<endEvent id="myErrorEndEvent">
  <errorEventDefinition errorRef="myError" />
</endEvent>          
          

The errorRef attribute can reference an error element that is defined outside the process:

<error id="myError" errorCode="123" />
...
<process id="myProcess">  
...        
          

The errorCode of the error will be used to find the matching catching boundary error event. If the errorRef does not match any defined error, then the errorRef is used as a shortcut for the errorCode. This is an Activiti specific shortcut. More concretely, following snippets are equivalent in functionality.

<error id="myError" errorCode="error123" />
...
<process id="myProcess">  
...  
  <endEvent id="myErrorEndEvent">
    <errorEventDefinition errorRef="myError" />
  </endEvent>          
          

is equivalent with

<endEvent id="myErrorEndEvent">
  <errorEventDefinition errorRef="error123" />
</endEvent>          
          

Note that the errorRef must comply with the BPMN 2.0 schema, and must be a valid QName.

Cancel End Event

[EXPERIMENTAL]

Description

The cancel end event can only be used in combination with a bpmn transaction subprocess. When the cancel end event is reached, a cancel event is thrown which must be caught by a cancel boundary event. The cancel boundary event then cancels the transaction and triggers compensation.

Graphical notation

A cancel end event visualized as a typical end event (circle with thick outline), with the cancel icon inside. The cancel icon is completely black, to indicate the throwing semantics.

XML representation

A cancel end event is represented as an end event, with a cancelEventDefinition child element.

<endEvent id="myCancelEndEvent">
  <cancelEventDefinition />
</endEvent>          
          

Boundary Events

Boundary events are catching events that are attached to an activity (a boundary event can never be throwing). This means that while the activity is running, the 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 are followed.

All boundary events are defined in the same way:

<boundaryEvent id="myBoundaryEvent" attachedToRef="theActivity">
      <XXXEventDefinition/>
</boundaryEvent>

A boundary event is defined with

  • A unique identifier (process-wide)

  • A reference to the activity to which the event is attached through the attachedToRef attribute. Note that a boundary event is defined on the same level as the activities to which they are attached (i.e. no inclusion of the boundary event inside the activity).

  • An XML sub-element of the form XXXEventDefinition (e.g. TimerEventDefinition, ErrorEventDefinition, etc.) defining the type of the boundary event. See the specific boundary event types for more details.

Timer Boundary Event

Description

A timer boundary event acts as a stopwatch and alarm clock. When an execution arrives in the activity where the boundary event is attached to, a timer is started. When the timer fires (e.g. after a specified interval), the activity is interrupted and the sequence flow going out of the timer boundary event are followed.

Graphical Notation

A timer boundary event is visualized as a typical boundary event (i.e. circle on the border), with the timer icon on the inside.

XML Representation

A timer boundary event is defined as a regular boundary event. The specific type sub-element is in this case a timerEventDefinition element.

<boundaryEvent id="escalationTimer" cancelActivity="true" attachedToRef="firstLineSupport">
   <timerEventDefinition>
    <timeDuration>PT4H</timeDuration>
  </timerEventDefinition>
</boundaryEvent>          

Please refer to timer event definition for details on timer configuration.

In the graphical representation, the line of the circle is dotted as you can see in this example above:

A typical use case is sending an escalation email additionally but not interrupt the normal process flow.

Since BPMn 2.0 there is the difference between the interrupting and non interrupting timer event. The interrupting is the default. The non-interrupting leads to the original activity is not interrupted but the activity stays there. Instead an additional executions is created and send over the outgoing transition of the event. In the XML representation, the cancelActivity attribute is set to false:

<boundaryEvent id="escalationTimer" cancelActivity="false" attachedToRef="firstLineSupport"/>

Note: boundary timer events are only fired when the job executor is enabled (i.e. jobExecutorActivate needs to be set to true in the activiti.cfg.xml, since the job executor is disabled by default).

Known issue with boundary events

There is a known issue regarding concurrency when using boundary events of any type. Currently, it is not possible to 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.

Error Boundary Event

Description

An intermediate catching error on the boundary of an activity, or boundary error event for short, catches errors that are thrown within the scope of the activity on which it is defined.

Defining a boundary error event makes most sense on an embedded subprocess, or a call activity, as a subprocess creates a scope for all activities inside the subprocess. Errors are thrown by error end events. Such an error will propagate its parent scopes upwards until a scope is found on which a boundary error event is defined that matches the error event definition.

When an error event is caught, the activity on which the boundary event is defined is destroyed, also destroying all current executions within (e.g. concurrent activities, nested subprocesses, etc.). Process execution continues following the outgoing sequence flow of the boundary event.

Graphical notation

A boundary error event is visualized as a typical intermediate event (Circle with smaller circle inside) on the boundary, with the error icon inside. The error icon is white, to indicate the catch semantics.

Xml representation

A boundary error event is defined as a typical boundary event:

<boundaryEvent id="catchError" attachedToRef="mySubProcess">
  <errorEventDefinition errorRef="myError"/>
</boundaryEvent>
          

As with the error end event, the errorRef references an error defined outside the process element:

<error id="myError" errorCode="123" />
...
<process id="myProcess">  
...              
          

The errorCode is used to match the errors that are caught:

  • If errorRef is omitted, the boundary error event will catch any error event, regardless of the errorCode of the error.

  • In case an errorRef is provided and it references an existing error, the boundary event will only catch errors with the same error code.

  • In case an errorRef is provided, but no error is defined in the BPMN 2.0 file, then the errorRef is used as errorCode (similar for with error end events).

Example

Following example process shows how an error end event can be used. When the 'Review profitability' user task is completed by stating that not enough information is provided, an error is thrown. When this error is caught on the boundary of the subprocess, all active activities within the 'Review sales lead' subprocess are destroyed (even if 'Review customer rating' was not yet completed), and the 'Provide additional details' user task is created.

This process is shipped as example in the demo setup. The process XML and unit test can be found in the org.activiti.examples.bpmn.event.error package.

Signal Boundary Event

Description

An attached intermediate catching signal on the boundary of an activity, or boundary signal event for short, catches signals with the same signal name as the referenced signal definition.

Note: contrary to other events like the boundary error event, a boundary signal event does not only catch signal events thrown from the scope it is attached to. On the contrary, a signal event has global scope (broadcast semantics) meaning that the signal can be thrown from any place, even from a different process instance.

Note: contrary to other events like an error event, a signal is not consumed if it is caught. If you have two active signal boundary events catching the same signal event, both boundary events are triggered, event if they are part of different process instances.

Graphical notation

A boundary signal event is visualized as a typical intermediate event (Circle with smaller circle inside) on the boundary, with the signal icon inside. The signal icon is white (unfilled), to indicate the catch semantics.

XML representation

A boundary signal event is defined as a typical boundary event:

<boundaryEvent id="boundary" attachedToRef="task" cancelActivity="true">       
          <signalEventDefinition signalRef="alertSignal"/>
</boundaryEvent>
          		

Example

See section on signal event definitions.

Message Boundary Event

Description

An attached intermediate catching message on the boundary of an activity, or boundary message event for short, catches messages with the same message name as the referenced message definition.

Graphical notation

A boundary message event is visualized as a typical intermediate event (Circle with smaller circle inside) on the boundary, with the message icon inside. The message icon is white (unfilled), to indicate the catch semantics.

Note that boundary message event can be both interrupting (right hand side) and non interrupting (left hand side).

XML representation

A boundary message event is defined as a typical boundary event:

<boundaryEvent id="boundary" attachedToRef="task" cancelActivity="true">       
          <messageEventDefinition messageRef="newCustomerMessage"/>
</boundaryEvent>
          		

Example

See section on message event definitions.

Cancel Boundary Event

[EXPERIMENTAL]

Description

An attached intermediate catching cancel on the boundary of a transaction subprocess, or boundary cancel event for short, is triggered when a transaction is cancelled. When the cancel boundary event is triggered, it first interrupts all executions active in the current scope. Next, it starts compensation of all active compensation boundary events in the scope of the transaction. Compensation is performed synchronously, i.e. the boundary event waits before compensation is completed before leaving the transaction. When compensation is completed, the transaction subprocess is left using the sequence flow(s) running out of the cancel boundary event.

Note: Only a single cancel boundary event is allowed for a transaction subprocess.

Note: If the transaction subprocess hosts nested subprocesses, compensation is only triggered for subprocesses that have completed successfully.

Note: If a cancel boundary event is placed on a transaction subprocess with multi instance characteristics, if one instance triggers cancellation, the boundary event cancels all instances.

Graphical notation

A cancel boundary event is visualized as a typical intermediate event (Circle with smaller circle inside) on the boundary, with the cancel icon inside. The cancel icon is white (unfilled), to indicate the catching semantics.

XML representation

A cancel boundary event is defined as a typical boundary event:

<boundaryEvent id="boundary" attachedToRef="transaction" >       
          <cancelEventDefinition />
</boundaryEvent>
          		

Since the cancel boundary event is always interrupting, the cancelActivity attribute is not required.

Compensation Boundary Event

[EXPERIMENTAL]

Description

An attached intermediate catching compensation on the boundary of an activity or compensation boundary event for short, can be used to attach a compensation handler to an activity.

The compensation boundary event must reference a single compensation handler using a directed association.

A compensation boundary event has a different activation policy from other boundary events. Other boundary events like for instance the signal boundary event are activated when the activity they are attached to is started. When the activity is left, they are deactivated and the corresponding event subscription is cancelled. The compensation boundary event is different. The compensation boundary event is activated when the activity it is attached to completes successfully. At this point, the corresponding subscription to the compensation events is created. The subscription is removed either when a compensation event is triggered or when the corresponding process instance ends. From this, it follows:

  • When compensation is triggered, the compensation handler associated with the compensation boundary event is invoked the same number of times the activity it is attached to completed successfully.

  • If a compensation boundary event is attached to an activity with multiple instance characteristics, a compensation event subscription is created for each instance.

  • If a compensation boundary event is attached to an activity which is contained inside a loop, a compensation event subscription is created for each time the activity is executed.

  • If the process instance ends, the subscriptions to compensation events are cancelled.

Note: the compensation boundary event is not supported on embedded subprocesses.

Graphical notation

A compensation boundary event is visualized as a typical intermediate event (Circle with smaller circle inside) on the boundary, with the compensation icon inside. The compensation icon is white (unfilled), to indicate the catching semantics. In addition to a compensation boundary event, the following figure shows a compensation handler associated with the boundary event using a unidirectional association:

XML representation

A compensation boundary event is defined as a typical boundary event:

<boundaryEvent id="compensateBookHotelEvt" attachedToRef="bookHotel" >       
          <compensateEventDefinition />
</boundaryEvent>

<association associationDirection="One" id="a1"  sourceRef="compensateBookHotelEvt" targetRef="undoBookHotel" />

<serviceTask id="undoBookHotel" isForCompensation="true" activiti:class="..." />

Since the compensation boundary event is activated after the activity has completed successfully, the cancelActivity attribute is not supported.

Intermediate Catching Events

All intermediate catching events events are defined in the same way:

<intermediateCatchEvent id="myIntermediateCatchEvent" >
      <XXXEventDefinition/>
</intermediateCatchEvent>

An intermediate catching event is defined with

  • A unique identifier (process-wide)

  • An XML sub-element of the form XXXEventDefinition (e.g. TimerEventDefinition, etc.) defining the type of the intermediate catching event. See the specific catching event types for more details.

Timer Intermediate Catching Event

Description

A timer intermediate event acts as a stopwatch. When an execution arrives in catching event activity, a timer is started. When the timer fires (e.g. after a specified interval), the sequence flow going out of the timer intermediate event is followed.

Graphical Notation

A timer intermediate event is visualized as a intermediate catching event, with the timer icon on the inside.

XML Representation

A timer intermediate event is defined as a intermediate catching event. The specific type sub-element is in this case a timerEventDefinition element.

        <intermediateCatchEvent id="timer">
            <timerEventDefinition>
                <timeDuration>PT5M</timeDuration>
            </timerEventDefinition>
        </intermediateCatchEvent>
                 

See timer event definitions for configuration details.

Signal Intermediate Catching Event

Description

An intermediate catching signal event catches signals with the same signal name as the referenced signal definition.

Note: contrary to other events like an error event, a signal is not consumed if it is caught. If you have two active signal boundary events catching the same signal event, both boundary events are triggered, event if they are part of different process instances.

Graphical notation

An intermediate signal catch event is visualized as a typical intermediate event (Circle with smaller circle inside), with the signal icon inside. The signal icon is white (unfilled), to indicate the catch semantics.

XML representation

A signal intermediate event is defined as a intermediate catching event. The specific type sub-element is in this case a signalEventDefinition element.

<intermediateCatchEvent id="signal">
	<signalEventDefinition signalRef="newCustomerSignal" />
</intermediateCatchEvent>
                 

Example

See section on signal event definitions.

Message Intermediate Catching Event

Description

An intermediate catching message event catches messages with a specified name.

Graphical notation

An intermediate catching message event is visualized as a typical intermediate event (Circle with smaller circle inside), with the message icon inside. The message icon is white (unfilled), to indicate the catch semantics.

XML representation

A message intermediate event is defined as a intermediate catching event. The specific type sub-element is in this case a messageEventDefinition element.

<intermediateCatchEvent id="message">
	<messageEventDefinition signalRef="newCustomerMessage" />
</intermediateCatchEvent>
                 

Example

See section on message event definitions.

Intermediate Throwing Event

All intermediate throwing events events are defined in the same way:

<intermediateThrowEvent id="myIntermediateThrowEvent" >
      <XXXEventDefinition/>
</intermediateThrowEvent>

An intermediate throwing event is defined with

  • A unique identifier (process-wide)

  • An XML sub-element of the form XXXEventDefinition (e.g. signalEventDefinition, etc.) defining the type of the intermediate throwing event. See the specific throwing event types for more details.

Intermediate Throwing None Event

The following process diagram shows a simple example of an intermediate none event, which is often used to indicate some state achieved in the process.

This can be a good hook to monitor some KPI's, basically by adding an execution listener

<intermediateThrowEvent id="noneEvent">
  <extensionElements>
    <activiti:executionListener class="org.activiti.engine.test.bpmn.event.IntermediateNoneEventTest$MyExecutionListener" event="start" />
  </extensionElements>
</intermediateThrowEvent>

There you can add some own code to maybe send some event to your BAM tool or DWH. The engine itself doesn't do anything in that event, it just passes through.

Signal Intermediate Throwing Event

Description

An intermediate throwing signal event throws a signal event for a defined signal.

In Activiti, the signal is broadcast to all active handlers (i.e. all catching signal events). Signals can be published synchronous or asynchronous.

  • In the default configuration, the signal is delivered synchronously. This means that the throwing process instance waits until the signal is delivered to all catching process instances. The catching process instances are also notified in the same transaction as the throwing process instance, which means that if one of the notified instances produces a technical error (throws an exception), all involved instances fail.

  • A signal can also be delivered asynchronously. In that case it is determined which handlers are active at the time the throwing signal event is reached. For each active handler, an asynchronous notification message (Job) is stored and delivered by the JobExecutor.

Graphical notation

An intermediate signal throw event is visualized as a typical intermediate event (Circle with smaller circle inside), with the signal icon inside. The signal icon is black (filled), to indicate the throw semantics.

XML representation

A signal intermediate event is defined as a intermediate throwing event. The specific type sub-element is in this case a signalEventDefinition element.

<intermediateThrowEvent id="signal">
	<signalEventDefinition signalRef="newCustomerSignal" />
</intermediateThrowEvent>
                 

An asynchronous signal event would look like this:

<intermediateThrowEvent id="signal">
	<signalEventDefinition signalRef="newCustomerSignal" activiti:async="true" />
</intermediateThrowEvent>
                 

Example

See section on signal event definitions.

Compensation Intermediate Throwing Event

[EXPERIMENTAL]

Description

An intermediate throwing compensation event can be used to trigger compensation.

Triggering compensation: Compensation can either be triggered for a designated activity or for the scope which hosts the compensation event. Compensation is performed through execution of the compensation handler associated with an activity.

  • When compensation is thrown for an activity, the associated compensation handler is executed the same number of times the activity competed successfully.

  • If compensation is thrown for the current scope, all activities withing the current scope are compensated, which includes activities on concurrent branches.

  • Compensation is triggered hierarchically: if an activity to be compensated is a subprocess, compensation is triggered for all activities contained in the subprocess. If the subprocess has nested activities, compensation is thrown recursively. However, compensation is not propagated to the "upper levels" of the process: if compensation is triggered within a subprocess, it is not propagated to activities outside of the subprocess scope. The bpmn specification states that compensation is triggered for activities at "the same level of subprocess".

  • In Activiti compensation is performed in reverse order of execution. This means that whichever activity completed last is compensated first, etc.

  • The intermediate throwing compensation event can be used to compensate transaction subprocesses which competed successfully.

Note: If compensation is thrown within a scope which contains a subprocess and the subprocess contains activities with compensation handlers, compensation is only propagated to the subprocess if it has completed successfully when compensation is thrown. If some of the activities nested inside the subprocess have completed and have attached compensation handlers, the compensation handlers are not executed if the subprocess containing these activities is not completed yet. Consider the following example:

In this process we have two concurrent executions, one executing the embedded subprocess and one executing the "charge credit card" activity. Lets assume both executions are started and the first concurrent execution is waiting for a user to complete the "review bookings" task. The second execution performs the "charge credit card" activity and an error is thrown, which causes the "cancel reservations" event to trigger compensation. At this point the parallel subprocess is not yet completed which means that the compensation event is not propagated to the subprocess and thus the "cancel hotel reservation" compensation handler is not executed. If the user task (and thus the embedded subprocess) completes before the "cancel reservations" is performed, compensation is propagated to the embedded subprocess.

Process variables: When compensating an embedded subprocess, the execution used for executing the compensation handlers has access to the local process variables of the subprocess in the state they were in when the subprocess completed execution. To achieve this, a snapshot of the process variables associated with the scope execution (execution created for executing the subprocess) is taken. Form this, a couple of implications follow:

  • The compensation handler does not have access to variables added to concurrent executions created inside the subprocess scope.

  • Process variables associated with executions higher up in the hierarchy, (for instance process variables associated with the process instance execution are not contained in the snapshot: the compensation handler has access to these process variables in the state they are in when compensation is thrown.

  • A variable snapshot is only taken for embedded subprocesses, not for other activities.

Current limitations:

  • waitForCompletion="false" is currently unsupported. When compensation is triggered using the intermediate throwing compensation event, the event is only left, after compensation completed successfully.

  • Compensation itself is currently performed by concurrent executions. The concurrent executions are started in reverse order in which the compensated activities completed. Future versions of activity might include an option to perform compensation sequentially.

  • Compensation is not propagated to sub process instances spawned by call activities.

Graphical notation

An intermediate compensation throw event is visualized as a typical intermediate event (Circle with smaller circle inside), with the compensation icon inside. The compensation icon is black (filled), to indicate the throw semantics.

Xml representation

A compensation intermediate event is defined as a intermediate throwing event. The specific type sub-element is in this case a compensateEventDefinition element.

<intermediateThrowEvent id="throwCompensation">
	<compensateEventDefinition />
</intermediateThrowEvent>

In addition, the optional argument activityRef can be used to trigger compensation of a specific scope / activity:

<intermediateThrowEvent id="throwCompensation">
	<compensateEventDefinition activityRef="bookHotel" />
</intermediateThrowEvent>

Sequence Flow

Description

A sequence flow is the connector between two elements of a process. After an element is visited during process execution, all outgoing sequence flow will be followed. This means that the default nature of BPMN 2.0 is to be parallel: two outgoing sequence flow will create two separate, parallel paths of execution.

Graphical notation

A sequence flow is visualized as an arrow going from the source element towards the target element. The arrow always points towards the target.

XML representation

Sequence flow need to have a process-unique id, and a reference to an existing source and target element.

<sequenceFlow id="flow1" sourceRef="theStart" targetRef="theTask" />

Conditional sequence flow

Description

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.

Note: the above holds for BPMN 2.0 activities (and events), but not for gateways. Gateways will handle sequence flow with conditions in specific ways, depending on the gateway type.

Graphical notation

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.

XML representation

A conditional sequence flow is represented in XML as a regular sequence flow, containing a conditionExpression sub-element. Note that for the moment only tFormalExpressions are supported, Omitting the xsi:type="" definition will simply default to this only supported type of expressions.

<sequenceFlow id="flow" sourceRef="theStart" targetRef="theTask">
  <conditionExpression xsi:type="tFormalExpression">
    <![CDATA[${order.price > 100 && order.price < 250}]]>
  </conditionExpression>
</sequenceFlow>

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

  • The example below references data of a process variable, in the typical JavaBean style through getters.

    <conditionExpression xsi:type="tFormalExpression">
      <![CDATA[${order.price > 100 && order.price < 250}]]>
    </conditionExpression>

  • This example invokes a method that resolves to a boolean value.

    <conditionExpression xsi:type="tFormalExpression">
      <![CDATA[${order.isStandardOrder()}]]>
    </conditionExpression>

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

Default sequence flow

Description

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.

Graphical notation

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

XML representation

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.

<exclusiveGateway id="exclusiveGw" name="Exclusive Gateway" default="flow2" />
<sequenceFlow id="flow1" sourceRef="exclusiveGw" targetRef="task1">
  <conditionExpression xsi:type="tFormalExpression">${conditionA}</conditionExpression>
</sequenceFlow>
<sequenceFlow id="flow2" sourceRef="exclusiveGw" targetRef="task2"/>
<sequenceFlow id="flow3" sourceRef="exclusiveGw" targetRef="task3">
  <conditionExpression xsi:type="tFormalExpression">${conditionB}</conditionExpression>
</sequenceFlow>          
          

Which corresponds with the following graphical representation:

Gateways

A gateway is used to control the flow of execution (or as the BPMN 2.0 describes, the tokens of execution). A gateway is capable of consuming or generating tokens.

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

Exclusive Gateway

Description

An exclusive gateway (also called the XOR gateway or more technical the exclusive data-based gateway), is used to model a decision in the process. When the execution arrives at this gateway, all outgoing sequence flow are evaluated in the order in which they are defined. The sequence flow which condition evaluates to true (or which doesn't have a condition set, conceptually having a 'true' defined on the sequence flow) is selected for continuing the process.

Note that the semantics of outgoing sequence flow is different to that of the general case in BPMN 2.0. While in general all sequence flow which condition evaluates to true are selected to continue in a parallel way, only one sequence flow is selected when using the exclusive gateway. In case multiple sequence flow have a condition that evaluates to true, the first one defined in the XML (and only that one!) is selected for continuing the process. If no sequence flow can be selected, an exception will be thrown.

Graphical notation

An exclusive gateway is visualized as a typical gateway (i.e. a diamond shape) with an 'X' icon inside, referring to the XOR semantics. Note that a gateway without an icon inside defaults to an exclusive gateway. The BPMN 2.0 specification does not allow mixing the diamond with and without an X in the same process definition.

XML representation

The XML representation of an exclusive gateway is straight-forward: one line defining the gateway and condition expressions defined on the outgoing sequence flow. See the section on conditional sequence flow to see which options are available for such expressions.

Take for example the following model:

Which is represented in XML as follows:

<exclusiveGateway id="exclusiveGw" name="Exclusive Gateway" />
    
<sequenceFlow id="flow2" sourceRef="exclusiveGw" targetRef="theTask1">
  <conditionExpression xsi:type="tFormalExpression">${input == 1}</conditionExpression>
</sequenceFlow>
    
<sequenceFlow id="flow3" sourceRef="exclusiveGw" targetRef="theTask2">
  <conditionExpression xsi:type="tFormalExpression">${input == 2}</conditionExpression>
</sequenceFlow>
    
<sequenceFlow id="flow4" sourceRef="exclusiveGw" targetRef="theTask3">
  <conditionExpression xsi:type="tFormalExpression">${input == 3}</conditionExpression>
</sequenceFlow>

Parallel Gateway

Description

Gateways can also be used to model concurrency in a process. The most straightforward gateway to introduce concurrency in a process model, is the Parallel Gateway, which allows to fork into multiple paths of execution or join multiple incoming paths of execution.

The functionality of the parallel gateway is based on the incoming and outgoing sequence flow:

  • fork: all outgoing sequence flow are followed in parallel, creating one concurrent execution for each sequence flow.

  • join: all concurrent executions arriving at the parallel gateway wait in the gateway until an execution has arrived for each of the incoming sequence flow. Then the process continues past the joining gateway.

Note that a parallel gateway can have both fork and join behavior, if there are multiple incoming and outgoing sequence flow for the same parallel gateway. In that case, the gateway will first join all incoming sequence flow, before splitting into multiple concurrent paths of executions.

An important difference with other gateway types is that the parallel gateway does not evaluate conditions. If conditions are defined on the sequence flow connected with the parallel gateway, they are simply neglected.

Graphical Notation

A parallel gateway is visualized as a gateway (diamond shape) with the 'plus' symbol inside, referring to the 'AND' semantics.

XML representation

Defining a parallel gateway needs one line of XML:

<parallelGateway id="myParallelGateway" />

The actual behavior (fork, join or both), is defined by the sequence flow connected to the parallel gateway.

For example, the model above comes down to the following XML:

    <startEvent id="theStart" />
    <sequenceFlow id="flow1" sourceRef="theStart" targetRef="fork" />
    
    <parallelGateway id="fork" />
    <sequenceFlow sourceRef="fork" targetRef="receivePayment" />
    <sequenceFlow sourceRef="fork" targetRef="shipOrder" />
    
    <userTask id="receivePayment" name="Receive Payment" />  
    <sequenceFlow sourceRef="receivePayment" targetRef="join" />
    
    <userTask id="shipOrder" name="Ship Order" /> 
    <sequenceFlow sourceRef="shipOrder" targetRef="join" />
    
    <parallelGateway id="join" />
    <sequenceFlow sourceRef="join" targetRef="archiveOrder" />
    
    <userTask id="archiveOrder" name="Archive Order" /> 
    <sequenceFlow sourceRef="archiveOrder" targetRef="theEnd" />
    
    <endEvent id="theEnd" />

In the above example, after the process is started, two tasks will be created:

ProcessInstance pi = runtimeService.startProcessInstanceByKey("forkJoin");
TaskQuery query = taskService.createTaskQuery()
                         .processInstanceId(pi.getId())
                         .orderByTaskName()
                         .asc();

List<Task> tasks = query.list();
assertEquals(2, tasks.size());

Task task1 = tasks.get(0);
assertEquals("Receive Payment", task1.getName());
Task task2 = tasks.get(1);
assertEquals("Ship Order", task2.getName());

When these two tasks are completed, the second parallel 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 a parallel gateway does not need to be 'balanced' (i.e. a matching number of incoming/outgoing sequence flow for corresponding parallel gateways). A parallel gateway will simply 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. So, the following process is legal in BPMN 2.0:

Inclusive Gateway

Description

The Inclusive Gateway can be seen as a combination of an exclusive and a parallel gateway. Like an exclusive gateway you can define conditions on outgoing sequence flows and the inclusive gateway will evaluate them. But the main difference is that the inclusive gateway can take more than one sequence flow, like the parallel gateway.

The functionality of the inclusive gateway is based on the incoming and outgoing sequence flow:

  • fork: all outgoing sequence flow conditions are evaluated and for the sequence flow conditions that evaluate to true the flows are followed in parallel, creating one concurrent execution for each sequence flow.

  • join: all concurrent executions arriving at the inclusive gateway wait in the gateway until an execution has arrived for each of the incoming sequence flows that have a process token. This is an important difference with the parallel gateway. So in other words, 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, if there are multiple incoming and outgoing sequence flow for the same inclusive gateway. In that case, the gateway will first 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

A parallel gateway is visualized as a gateway (diamond shape) with the 'circle' symbol inside.

XML representation

Defining an inclusive gateway needs one line of XML:

<inclusiveGateway id="myInclusiveGateway" />

The actual behavior (fork, join or both), is defined by the sequence flows connected to the inclusive gateway.

For example, the model above comes down to the following XML:

    <startEvent id="theStart" />
    <sequenceFlow id="flow1" sourceRef="theStart" targetRef="fork" />
    
    <inclusiveGateway id="fork" />
    <sequenceFlow sourceRef="fork" targetRef="receivePayment" >
    <conditionExpression xsi:type="tFormalExpression">${paymentReceived == false}</conditionExpression>
    </sequenceFlow>
    <sequenceFlow sourceRef="fork" targetRef="shipOrder" >
    <conditionExpression xsi:type="tFormalExpression">${shipOrder == true}</conditionExpression>
    </sequenceFlow>
    
    <userTask id="receivePayment" name="Receive Payment" />  
    <sequenceFlow sourceRef="receivePayment" targetRef="join" />
    
    <userTask id="shipOrder" name="Ship Order" /> 
    <sequenceFlow sourceRef="shipOrder" targetRef="join" />
    
    <inclusiveGateway id="join" />
    <sequenceFlow sourceRef="join" targetRef="archiveOrder" />
    
    <userTask id="archiveOrder" name="Archive Order" /> 
    <sequenceFlow sourceRef="archiveOrder" targetRef="theEnd" />
    
    <endEvent id="theEnd" />

In the above example, after the process is started, two tasks will be created if the process variables paymentReceived == false and shipOrder == true. In case only one of these process variables equals to true only one task will be created. If no condition evaluates to true and exception is thrown. This can be prevented by specifying a default outgoing sequence flow. In the following example one task will be created, the ship order task:

HashMap<String, Object> variableMap = new HashMap<String, Object>();
          variableMap.put("receivedPayment", true);
          variableMap.put("shipOrder", true);
          ProcessInstance pi = runtimeService.startProcessInstanceByKey("forkJoin");
TaskQuery query = taskService.createTaskQuery()
                         .processInstanceId(pi.getId())
                         .orderByTaskName()
                         .asc();

List<Task> tasks = query.list();
assertEquals(1, tasks.size());

Task task = tasks.get(0);
assertEquals("Ship Order", task.getName());

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 simply 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.

Event-based Gateway

Description

The Event-based Gateway allows to take a decision based on events. Each outgoing sequence flow of the gateway needs to be connected to an intermediate catching event. When process execution reaches an Event-based Gateway, the gateway acts like a wait state: execution is suspended. In addition, for each outgoing sequence flow, an event subscription is created.

Note the sequence flows running out of an Event-based Gateway are different from ordinary sequence flows. These sequence flows are never actually "executed". On the contrary, they allow the process engine to determine which events an execution arriving at an Event-based Gateway needs to subscribe to. The following restrictions apply:

  • An Event-based Gateway must have two or more outgoing sequence flows.

  • An Event-based Gateway must only be to elements of type intermediateCatchEvent only. (Receive Tasks after an Event-based Gateway are not supported by Activiti.)

  • An intermediateCatchEvent connected to an Event-based Gateway must have a single incoming sequence flow.

Graphical notation

An Event-based Gateway is visualized as a diamond shape like other BPMN gateways with a special icon inside.

XML representation

The XML element used to define an Event-based Gateway is eventBasedGateway.

Example(s)

The following process is an example of a process with an Event-based Gateway. When the execution arrives at the Event-based Gateway, process execution is suspended. In addition, the process instance subscribes to the alert signal event and created a timer which fires after 10 minutes. This effectively causes the process engine to wait for ten minutes for a signal event. If the signal occurs within 10 minutes, the timer is cancelled and execution continues after the signal. If the signal is not fired, execution continues after the timer and the signal subscription is cancelled.

      	
<definitions id="definitions"
	xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
	xmlns:activiti="http://activiti.org/bpmn" 
	targetNamespace="Examples">

	<signal id="alertSignal" name="alert" />

	<process id="catchSignal">

		<startEvent id="start" />

		<sequenceFlow sourceRef="start" targetRef="gw1" />

		<eventBasedGateway id="gw1" />
		
		<sequenceFlow sourceRef="gw1" targetRef="signalEvent" />		
		<sequenceFlow sourceRef="gw1" targetRef="timerEvent" />

		<intermediateCatchEvent id="signalEvent" name="Alert">
			<signalEventDefinition signalRef="alertSignal" />
		</intermediateCatchEvent>
		
		<intermediateCatchEvent id="timerEvent" name="Alert">
			<timerEventDefinition>
				<timeDuration>PT10M</timeDuration>
			</timerEventDefinition>		
		</intermediateCatchEvent>
		
		<sequenceFlow sourceRef="timerEvent" targetRef="exGw1" />
		<sequenceFlow sourceRef="signalEvent" targetRef="task" />
			
		<userTask id="task" name="Handle alert"/>
		
		<exclusiveGateway id="exGw1" />
		
		<sequenceFlow sourceRef="task" targetRef="exGw1" />
		<sequenceFlow sourceRef="exGw1" targetRef="end" />

		<endEvent id="end" />
</process>
</definitions>

Tasks

User Task

Description

A 'user task' is used to model work that needs to be done by a human actor. When the process execution arrives at such a user task, a new task is created in the task list of the user(s) or group(s) assigned to that task.

Graphical notation

A user task is visualized as a typical task (rounded rectangle), with a small user icon in the left upper corner.

XML representation

A user task is defined in XML as follows. The id attribute is required, the name attribute is optional.

<userTask id="theTask" name="Important task" />			  
				  

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.

<userTask id="theTask" name="Schedule meeting" >
  <documentation>
	  Schedule an engineering meeting for next week with the new hire.
  </documentation>

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

task.getDescription()

Due Date

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 (eg. 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.

<userTask id="theTask" name="Important task" activiti:dueDate="${dateVariable}"/>

The due date of a task can also be altered using the TaskService or in TaskListeners using the passed DelegateTask.

User assignment

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.

<process ... >
  
  ...
  
  <userTask id='theTask' name='important task' >
    <humanPerformer>
      <resourceAssignmentExpression>
        <formalExpression>kermit</formalExpression>
      </resourceAssignmentExpression>
    </humanPerformer>
  </userTask>

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:

List<Task> tasks = taskService.createTaskQuery().taskAssignee("kermit").list();

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).

<process ... >
  
  ...
  
  <userTask id='theTask' name='important task' >
    <potentialOwner>
      <resourceAssignmentExpression>
        <formalExpression>user(kermit), group(management)</formalExpression>
      </resourceAssignmentExpression>
    </potentialOwner>
  </userTask>

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

 List<Task> tasks = taskService.createTaskQuery().taskCandidateUser("kermit");

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 IdentityService.

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.

<formalExpression>accountancy</formalExpression>

Activiti extensions for task assignment

It is clear that user and group assignments are quite cumbersome for use cases where the assignment is not complex. To avoid these complexities, custom extensions on the user task are possible.

  • assignee attribute: this custom extension allows to directly assign a user task to a given user.

    <userTask id="theTask" name="my task" activiti:assignee="kermit" />

    This is exactly the same as using a humanPerformer construct as defined above.

  • candidateUsers attribute: this custom extension allows to make a user a candidate for a task.

    <userTask id="theTask" name="my task" activiti:candidateUsers="kermit, gonzo" />

    This is exactly the same as using a potentialOwner construct as defined above. Note that it is not required to use the user(kermit) declaration as is the case with the potential owner construct, since the attribute can only be used for users.

  • candidateGroups attribute: this custom extension allows to make a group a candidate for a task.

    <userTask id="theTask" name="my task" activiti:candidateGroups="management, accountancy" />

    This is exactly the same as using a potentialOwner construct as defined above. Note that it is not required to use the group(management) declaration as is the case with the potential owner construct, since the attribute can only be used for groups.

  • candidateUsers and candidateGroups can both be defined on the same user task.

Note: Although Activiti provides an identity management component, which is exposed through the IdentityService, 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.

In case the previous approaches are not sufficient, it is possible to delegate to custom assignment logic using a task listener on the create event:

<userTask id="task1" name="My task" >
  <extensionElements>
    <activiti:taskListener event="create" class="org.activiti.MyAssignmentHandler" />
  </extensionElements>
</userTask>

The DelegateTask that is passed to the TaskListener implementation, allows to set the assignee and candidate-users/groups:

public class MyAssignmentHandler implements TaskListener {

  public void notify(DelegateTask delegateTask) {
    // Execute custom identity lookups here
    
    // and then for example call following methods:
    delegateTask.setAssignee("kermit");
    delegateTask.addCandidateUser("fozzie");
    delegateTask.addCandidateGroup("management");
    ...
  }
  
}

When using Spring it is possible to use the custom assignment attributes as described in the section above, and delegate to a Spring bean using a task listener with an expression that listens to task create events. In the following example, the assignee will be set by calling the findManagerOfEmployee on the ldapService Spring bean. The emp parameter that is passed, is a process variable>.

<userTask id="task" name="My Task" activiti:assignee="${ldapService.findManagerForEmployee(emp)}"/>

This also works similar for candidate users and groups:

<userTask id="task" name="My Task" activiti:candidateUsers="${ldapService.findAllSales()}"/>

Note that this will only work if the return type of the invoked methods is String or Collection<String> (for candidate users and groups):

            
public class FakeLdapService {
  
  public String findManagerForEmployee(String employee) {
    return "Kermit The Frog";
  }
  
  public List<String> findAllSales() {
    return Arrays.asList("kermit", "gonzo", "fozzie");
  }

}

Script Task

Description

A script task is an automatic activity. When a process execution arrives at the script task, the corresponding script is executed.

Graphical Notation

A script task is visualized as a typical BPMN 2.0 task (rounded rectangle), with a small 'script' icon in the top-left corner of the rectangle.

XML representation

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

<scriptTask id="theScriptTask" name="Execute script" scriptFormat="groovy">
  <script>
    sum = 0
    for ( i in inputArray ) {
      sum += i
    }
  </script>
</scriptTask>

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, it is sufficient to 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.

Do note that the Groovy scripting engine is bundled with the groovy-all jar. Before version 2.0, the scripting engine was part of the regular Groovy jar. As such, one must now add following dependency:

<dependency>
      <groupId>org.codehaus.groovy</groupId>
      <artifactId>groovy-all</artifactId>
      <version>2.x.x<version>
</dependency>

Variables in scripts

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).

<script>
    sum = 0
    for ( i in inputArray ) {
      sum += i
    }
</script>

It's also possible to set process variables in a script, simply by calling execution.setVariable("variableName", variableValue). By default, no variables are stored automatically (Note: before Activiti 5.12 this was the case!). It is possible to automatically store any variable defined in the script (eg. 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.

<scriptTask id="script" scriptFormat="JavaScript" activiti:autoStoreVariables="false">

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.

Example on how to set a variable in a script:

<script>
    def scriptVar = "test123"
    execution.setVariable("myVar", scriptVar)
</script>

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

Script results

The return value of a script task 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 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.

<scriptTask id="theScriptTask" name="Execute script" scriptFormat="juel" activiti:resultVariable="myVar">
  <script>#{echo}</script>
</scriptTask>

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.

Java Service Task

Description

A Java service task is used to invoke an external Java class.

Graphical Notation

A service task is visualized as a rounded rectangle with a small gear icon in the top-left corner.

XML representation

There are 4 ways of declaring how to invoke Java logic:

  • Specifying a class that implements JavaDelegate or ActivityBehavior

  • Evaluating an expression that resolves to a delegation object

  • Invoking a method expression

  • Evaluating a value expression

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

<serviceTask id="javaService" 
             name="My Java Service Task" 
             activiti:class="org.activiti.MyJavaDelegate" />

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

It is also possible to 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).

 <serviceTask id="serviceTask" activiti:delegateExpression="${delegateExpressionBean}" />

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.

<serviceTask id="javaService" 
             name="My Java Service Task" 
             activiti:expression="#{printer.printMessage()}" />

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

It's also possible to pass parameters with an method used in the expression.

<serviceTask id="javaService" 
             name="My Java Service Task" 
             activiti:expression="#{printer.printMessage(execution, myVar)}" />

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.

<serviceTask id="javaService" 
             name="My Java Service Task" 
             activiti:expression="#{split.ready}" />

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.

Implementation

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's 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).

public class ToUppercase implements JavaDelegate {
  
  public void execute(DelegateExecution execution) throws Exception {
    String var = (String) execution.getVariable("input");
    var = var.toUpperCase();
    execution.setVariable("input", var);
  }
  
}

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 Field injection 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] It is also possible to 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 however that this is not a very good practice, and should be avoided as much as possible. So, it is advised to use the ActivityBehavior interface only for advanced use cases and if you know exactly what you're doing.

Field Injection

It's possible to inject values into the fields of the delegated classes. The following types of injection are supported:

  • Fixed string values

  • Expressions

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's 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.

<serviceTask id="javaService" 
    name="Java service invocation" 
    activiti:class="org.activiti.examples.bpmn.servicetask.ToUpperCaseFieldInjected">
    <extensionElements>
      <activiti:field name="text" stringValue="Hello World" />
  </extensionElements>           
</serviceTask>        
          

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:

<serviceTask id="javaService" 
    name="Java service invocation" 
    activiti:class="org.activiti.examples.bpmn.servicetask.ToUpperCaseFieldInjected">
  <extensionElements>   
    <activiti:field name="text">
        <activiti:string>
          Hello World
      </activiti:string>
    </activiti:field>
  </extensionElements>        
</serviceTask>        
          

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.

<serviceTask id="javaService" name="Java service invocation" 
  activiti:class="org.activiti.examples.bpmn.servicetask.ReverseStringsFieldInjected">
  
  <extensionElements>
    <activiti:field name="text1">
      <activiti:expression>${genderBean.getGenderString(gender)}</activiti:expression>
    </activiti:field>
    <activiti:field name="text2">
       <activiti:expression>Hello ${gender == 'male' ? 'Mr.' : 'Mrs.'} ${name}</activiti:expression>
    </activiti:field>
  </ extensionElements>
</ serviceTask>

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


public class ReverseStringsFieldInjected implements JavaDelegate {

  private Expression text1;
  private Expression text2;

  public void execute(DelegateExecution execution) {
    String value1 = (String) text1.getValue(execution);
    execution.setVariable("var1", new StringBuffer(value1).reverse().toString());

    String value2 = (String) text2.getValue(execution);
    execution.setVariable("var2", new StringBuffer(value2).reverse().toString());
  }
}

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

<activiti:field name="text1" expression="${genderBean.getGenderString(gender)}" />
<activiti:field name="text1" expression="Hello ${gender == 'male' ? 'Mr.' : 'Mrs.'} ${name}" />

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.

Service task results

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.

<serviceTask id="aMethodExpressionServiceTask"
    activiti:expression="#{myService.doSomething()}"
    activiti:resultVariable="myVar" />

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.

Handling exceptions

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.

Throwing BPMN Errors

It is possible to throw BPMN Errors 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.

public class ThrowBpmnErrorDelegate implements JavaDelegate {

  public void execute(DelegateExecution execution) throws Exception {
    try {
      executeBusinessLogic();
    } catch (BusinessException e) {
      throw new BpmnError("BusinessExceptionOccurred");
    }
  }

}

The constructor argument is an error code, which will be used to determine the error handler that is responsible for the error. See Boundary Error Event 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.

Exception Sequence Flow

[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.

<serviceTask id="javaService" 
  name="Java service invocation" 
  activiti:class="org.activiti.ThrowsExceptionBehavior">            
</serviceTask>
    
<sequenceFlow id="no-exception" sourceRef="javaService" targetRef="theEnd" />
<sequenceFlow id="exception" sourceRef="javaService" targetRef="fixException" />

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:

public class ThrowsExceptionBehavior implements ActivityBehavior {

  public void execute(ActivityExecution execution) throws Exception {
    String var = (String) execution.getVariable("var");

    PvmTransition transition = null;
    try {
      executeLogic(var);
      transition = execution.getActivity().findOutgoingTransition("no-exception");
    } catch (Exception e) {
      transition = execution.getActivity().findOutgoingTransition("exception");
    }
    execution.take(transition);
  }
  
}

Using an Activiti service from within a JavaDelegate

For some use cases, it might be needed to use the Activiti services from within a Java service task (eg. 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:

public class StartProcessInstanceTestDelegate implements JavaDelegate {

  public void execute(DelegateExecution execution) throws Exception {
    RuntimeService runtimeService = execution.getEngineServices().getRuntimeService();
    runtimeService.startProcessInstanceByKey("myProcess");
  }

}            
            

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.

@Component("startProcessInstanceDelegate")
public class StartProcessInstanceTestDelegateWithInjection {
  
    @Autowired
    private RuntimeService runtimeService;
    
    public void startProcess() {
      runtimeService.startProcessInstanceByKey("oneTaskProcess");
    }
    
}
            

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.

Web Service Task

[EXPERIMENTAL]

Description

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

Graphical Notation

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

XML representation

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:

<import importType="http://schemas.xmlsoap.org/wsdl/"
	location="http://localhost:63081/counter?wsdl"
	namespace="http://webservice.activiti.org/" />

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:

<message id="prettyPrintCountRequestMessage" itemRef="tns:prettyPrintCountRequestItem" />
<message id="prettyPrintCountResponseMessage" itemRef="tns:prettyPrintCountResponseItem" />
  
<itemDefinition id="prettyPrintCountRequestItem" structureRef="counter:prettyPrintCount" />
<itemDefinition id="prettyPrintCountResponseItem" structureRef="counter:prettyPrintCountResponse" />

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:

<interface name="Counter Interface" implementationRef="counter:Counter">
	<operation id="prettyPrintCountOperation" name="prettyPrintCount Operation" 
			implementationRef="counter:prettyPrintCount">
		<inMessageRef>tns:prettyPrintCountRequestMessage</inMessageRef>
		<outMessageRef>tns:prettyPrintCountResponseMessage</outMessageRef>
	</operation>
</interface>

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

<serviceTask id="webService" 
	name="Web service invocation"
	implementation="##WebService"
	operationRef="tns:prettyPrintCountOperation">

Web Service Task IO Specification

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:

<ioSpecification>
	<dataInput itemSubjectRef="tns:prettyPrintCountRequestItem" id="dataInputOfServiceTask" />
	<dataOutput itemSubjectRef="tns:prettyPrintCountResponseItem" id="dataOutputOfServiceTask" />
	<inputSet>
		<dataInputRefs>dataInputOfServiceTask</dataInputRefs>
	</inputSet>
	<outputSet>
		<dataOutputRefs>dataOutputOfServiceTask</dataOutputRefs>
	</outputSet>
</ioSpecification>

Web Service Task data input associations

There are 2 ways of specifying data input associations:

  • Using expressions

  • Using the simplistic approach

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:

<dataInputAssociation>
	<sourceRef>dataInputOfProcess</sourceRef>
	<targetRef>dataInputOfServiceTask</targetRef>
	<assignment>
		<from>${dataInputOfProcess.prefix}</from>
		<to>${dataInputOfServiceTask.prefix}</to>
	</assignment>
	<assignment>
		<from>${dataInputOfProcess.suffix}</from>
		<to>${dataInputOfServiceTask.suffix}</to>
	</assignment>
</dataInputAssociation>

On the other hand we 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'.

<dataInputAssociation>
	<sourceRef>PrefixVariable</sourceRef>
	<targetRef>prefix</targetRef>
</dataInputAssociation>
<dataInputAssociation>
	<sourceRef>SuffixVariable</sourceRef>
	<targetRef>suffix</targetRef>
</dataInputAssociation>

Web Service Task data output associations

There are 2 ways of specifying data out associations:

  • Using expressions

  • Using the simplistic approach

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:

<dataOutputAssociation>
	<targetRef>dataOutputOfProcess</targetRef>
	<transformation>${dataOutputOfServiceTask.prettyPrint}</transformation>
</dataOutputAssociation>

On the other hand we 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:

<dataOutputAssociation>
	<sourceRef>prettyPrint</sourceRef>
	<targetRef>OutputVariable</targetRef>
</dataOutputAssociation>

Business Rule Task

[EXPERIMENTAL]

Description

A Business Rule task is used to synchronously execute one or more rules. Activiti uses Drools Expert, the Drools rule engine to execute business rules. Currently, the .drl files containing the business rules have to be deployed together with the process definition that defines a 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 ServiceTask

Graphical Notation

A Business Rule task is visualized the with a table icon.

XML representation

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:

<process id="simpleBusinessRuleProcess">
  
  <startEvent id="theStart" />
  <sequenceFlow sourceRef="theStart" targetRef="businessRuleTask" />
  
  <businessRuleTask id="businessRuleTask" activiti:ruleVariablesInput="${order}"
      activiti:resultVariable="rulesOutput" />
 	
  <sequenceFlow sourceRef="businessRuleTask" targetRef="theEnd" />

  <endEvent id="theEnd" />
 
</process>
			  

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.

<businessRuleTask id="businessRuleTask" activiti:ruleVariablesInput="${order}"
      activiti:rules="rule1, rule2" />
			  

In this case only rule1 and rule2 are executed.

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

<businessRuleTask id="businessRuleTask" activiti:ruleVariablesInput="${order}"
      activiti:rules="rule1, rule2" exclude="true" />
			  

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:

<businessRuleTask id="businessRuleTask" activiti:class="${MyRuleServiceDelegate}" />
			  

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

Email Task

Activiti allows to enhance business processes with automatic mail service tasks that send e-mails to one or more recipients, including support for cc, bcc, HTML content, ... etc. Note that the mail task is not an 'official' task of the BPMN 2.0 spec (and it does not have a dedicated icon as a consequence). Hence, in Activiti the mail task is implemented as a dedicated service task.

Mail server configuration

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. Following properties can be set in the activiti.cfg.xml configuration file:

Table 8.1. Mail server configuration

PropertyRequired?Description
mailServerHostnoThe hostname of your mail server (e.g. mail.mycorp.com). Default is localhost
mailServerPortyes, if not on the default portThe port for SMTP traffic on the mail server. The default is 25
mailServerDefaultFromnoThe default e-mail address of the sender of e-mails, when none is provided by the user. By default this is activiti@activiti.org
mailServerUsernameif applicable for your serverSome mail servers require credentials for sending e-mail. By default not set.
mailServerPasswordif applicable for your serverSome mail servers require credentials for sending e-mail. By default not set.
mailServerUseSSLif applicable for your serverSome mail servers require ssl communication. By default set to false.
mailServerUseTLSif applicable for your serverSome mail servers (for instance gmail) require TLS communication. By default set to false.


Defining an Email Task

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

<serviceTask id="sendMail" activiti:type="mail">		      
		      

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

Table 8.2. Mail server configuration

PropertyRequired?Description
toyesThe recipients if the e-mail. Multiple recipients are defined in a comma-separated list
fromnoThe sender e-mail address. If not provided, the default configured from address is used.
subjectnoThe subject of the e-mail.
ccnoThe cc's of the e-mail. Multiple recipients are defined in a comma-separated list
bccnoThe bcc's of the e-mail. Multiple recipients are defined in a comma-separated list
charsetnoAllows to change the charset of the email, which is necessary for many non-English languages.
htmlnoA piece of HTML that is the content of the e-mail.
textnoThe content of the e-mail, in case one needs to send plain none-rich e-mails. Can be used in combination with html, for e-mail clients that don't support rich content. The client will then fall back to this text-only alternative.
htmlVarnoThe name of a process variable that holds the HTML that is the content of the e-mail. The key difference between this and html is that this content will have expressions replaced before being sent by the mail task.
textVarnoThe name of a process variable that holds the plain text content of the e-mail. The key difference between this and html is that this content will have expressions replaced before being sent by the mail task.


Example usage

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

<serviceTask id="sendMail" activiti:type="mail">
  <extensionElements>
    <activiti:field name="from" stringValue="order-shipping@thecompany.com" />
    <activiti:field name="to" expression="${recipient}" />
    <activiti:field name="subject" expression="Your order ${orderId} has been shipped" />
    <activiti:field name="html">
      <activiti:expression>
        <![CDATA[
          <html>
            <body>
              Hello ${male ? 'Mr.' : 'Mrs.' } ${recipientName},<br/><br/>
                 
              As of ${now}, your order has been <b>processed and shipped</b>.<br/><br/>
                  
              Kind regards,<br/>
                  
              TheCompany.
            </body>
          </html>
        ]]>
      </activiti:expression>
    </activiti:field>      
  </extensionElements>
</serviceTask>		      
		      

with the following result:

Mule Task

The mule task allows to send messages to Mule enhancing the integration features of Activiti. Note that the mule task is not an 'official' task of the BPMN 2.0 spec (and it does not have a dedicated icon as a consequence). Hence, in Activiti the mule task is implemented as a dedicated service task.

Defining an Mule Task

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

<serviceTask id="sendMule" activiti:type="mule">		      
		      

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

Table 8.3. Mule server configuration

PropertyRequired?Description
endpointUrlyesThe Mule endpoint you want to invoke.
languageyesThe language you want to use to evaluate the payloadExpression field.
payloadExpressionyesAn expression that will be the message's payload.
resultVariablenoThe name of the variable which will store the result of the invocation.


Example usage

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

  <extensionElements>
    <activiti:field name="endpointUrl">
      <activiti:string>vm://in</activiti:string>
    </activiti:field>
    <activiti:field name="language">
      <activiti:string>juel</activiti:string>
    </activiti:field>
    <activiti:field name="payloadExpression">
      <activiti:string>"hi"</activiti:string>
    </activiti:field>
    <activiti:field name="resultVariable">
      <activiti:string>theVariable</activiti:string>
    </activiti:field>
  </extensionElements>	      
		      

Camel Task

The Camel task allows to send messages to and receive messages from Camel and thereby enhances the integration features of Activiti. Note that the Camel task is not an 'official' task of the BPMN 2.0 spec (and it does not have a dedicated icon as a consequence). Hence, in Activiti the Camel task is implemented as a dedicated service task. Also note to include the Activiti Camel module in your project to use the Camel task functionality.

Defining a Camel Task

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

<serviceTask id="sendCamel" activiti:type="camel">         
          

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.

<camelContext id="camelContext" xmlns="http://camel.apache.org/schema/spring">
  <packageScan>
    <package>org.activiti.camel.route</package>
  </packageScan>
</camelContext>

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:

<serviceTask id="serviceTask1" activiti:type="camel">
  <extensionElements>
    <activiti:field name="camelContext" stringValue="customCamelContext" />
  </extensionElements>
</serviceTask>
		

Simple Camel Call example

All the files related to this example can be found in org.activiti.camel.examples.simpleCamelCall package of activiti-camel module. The target is simply 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:

<camelContext id="camelContext" xmlns="http://camel.apache.org/schema/spring">
  <packageScan>
    <package>org.activiti.camel.examples.simpleCamelCall</package>
  </packageScan>
</camelContext>
         
The route itself is configured in a file named SimpleCamelCallRoute located in the directory mentioned in PackageScan tag above. Here is the route:
public class SimpleCamelCallRoute extends RouteBuilder {

  @Override
  public void configure() throws Exception {
    from("activiti:SimpleCamelCallProcess:simpleCall").to("log:org.activiti.camel.examples.SimpleCamelCall");
  }
}
The route just logs the message body and nothing more. Notice the format of the from endpoint. It is consisted of three parts:

Table 8.4. Endpoint URL parts:

Endpoint Url PartDescription
activitirefers to Activiti endpoint
SimpleCamelCallProcessname of the process
simpleCallname of the Camel service in the process

Ok, our route is now properly configured and accessible to the Camel. Now comes the workflow part. The workflow looks like:
<process id="SimpleCamelCallProcess">
  <startEvent id="start"/>
  <sequenceFlow id="flow1" sourceRef="start" targetRef="simpleCall"/>
  
  <serviceTask id="simpleCall" activiti:type="camel"/>
  
  <sequenceFlow id="flow2" sourceRef="simpleCall" targetRef="end"/>      
  <endEvent id="end"/>
</process>	  
          
In the service task, it is just mentioned that type of service is Camel and the target route should be named as simpleCall. This matches what was mentioned in the Activiti endpoint. By instantiating the process we will see an empty log entry. Great we are done for the simplest case.

Ping Pong example

Our example worked but nothing is really transferred between Camel and Activiti and there is not much merit in it. In this example we try to send and receive data to and from Camel. We send a string, camel concatenates something to it and returns back the result. The sender part is trivial, we send our message in form of a variable to Camel Task. Here is our caller code:

@Deployment
public void testPingPong() {
  Map<String, Object> variables = new HashMap<String, Object>();

  variables.put("input", "Hello");
  Map<String, String> outputMap = new HashMap<String, String>();
  variables.put("outputMap", outputMap);
  
  runtimeService.startProcessInstanceByKey("PingPongProcess", variables);
  assertEquals(1, outputMap.size());
  assertNotNull(outputMap.get("outputValue"));
  assertEquals("Hello World", outputMap.get("outputValue"));
}         
	

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:

<process id="PingPongProcess">
  <startEvent id="start"/>
  <sequenceFlow id="flow1" sourceRef="start" targetRef="ping"/>
  <serviceTask id="ping" activiti:type="camel"/>
  <sequenceFlow id="flow2" sourceRef="ping" targetRef="saveOutput"/>
  <serviceTask id="saveOutput"  activiti:class="org.activiti.camel.examples.pingPong.SaveOutput" />
  <sequenceFlow id="flow3" sourceRef="saveOutput" targetRef="end"/>
  <endEvent id="end"/>
</process>
    

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 behaviour into the play. The way variables are communicated to Camel is configurable via CamelBehavior. Here we use Default one in our sample, a short description of the other ones comes afterwards. With such a code you can configure the desired camel behaviour:

<serviceTask id="serviceTask1" activiti:type="camel">
  <extensionElements>
    <activiti:field name="camelBehaviorClass" stringValue="org.activiti.camel.impl.CamelBehaviorCamelBodyImpl" />
  </extensionElements>
</serviceTask>
	

If you do not specify and specific behaviour then, org.activiti.camel.impl.CamelBehaviorDefaultImpl will be set. This behaviour copies the variables to Camel properties of the same name. In return regardless of selected behaviour, 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 our second example:

@Override
public void configure() throws Exception {
  from("activiti:PingPongProcess:ping").transform().simple("${property.input} World");
}
	

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 behaviour 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 behaviours already available out of the box in Activiti. The behaviour can be overwritten by a specific phrase in the route URL. Here is an example of overriding the already defined behaviour in URL:

from("activiti:asyncCamelProcess:serviceTaskAsync2?copyVariablesToProperties=true").
		

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

Table 8.5. Existing camel behaviours:

BehaviourIn UrlDescription
CamelBehaviorDefaultImplcopyVariablesToPropertiesCopy Activiti variables as Camel properties
CamelBehaviorCamelBodyImplcopyCamelBodyToBodyCopy only Activiti variable named "camelBody" as camel message body
CamelBehaviorBodyAsMapImplcopyVariablesToBodyAsMapCopy all the activiti variables in a map as Camel message body


the above table explains how activiti variables are going to be transfered to Camel. The following table explains how the Camel variables are returned back to Activiti. This can only be configured in route URLs.

Table 8.6. Existing camel behaviours:

UrlDescription 
DefaultIf Camel body is a map, copy each element as Activiti variable, otherwise copy the whole Camel body as "camelBody" activiti variable 
copyVariablesFromPropertiesCopy Camel properties as Activiti variables of the same name 
copyCamelBodyToBodyAsStringlike default, but if camel Body is not a map, first convert it to String and then copy it in "camelBody" 
isCopyVariablesFromHeaderAdditionally copy camel headers to Activiti variables of the same names 


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

Asynchronous Ping Pong example

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.

<serviceTask id="serviceAsyncPing" activiti:type="camel" activiti:async="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.

<receiveTask id="receiveAsyncPing" name="Wait State" />
		

The process instance will wait until a signal is received, for example from Camel. In Camel you can send a signal to the process instance by sending a message to the proper activiti endpoint.
 from("activiti:asyncPingProcess:serviceAsyncPing").to("activiti:asyncPingProcess:receiveAsyncPing");		
		
As usual endpoint consists of three parts separated by colons:
  • constant string "activiti"

  • process name

  • receive task name

Instantiate workflow from Camel route

In our all previous examples Activiti workflow started first and the Camel route was started within workflow. It is also possible from the other side. It is possible that a workflow is instantiated from an already started camel route. It is very similar to signalling receive task, except that the last part is not there. Here is a sample route:

from("direct:start").to("activiti:camelProcess");
	

as you see the url has two parts, the first is constant string "activiti" and the second name is the name of the process. Obviously the process should already be deployed and startable by engine configuration.

Manual Task

Description

A Manual Task defines a task that is external to the BPM engine. It is used to model work that is done by somebody, which the engine does not need to know of, nor is there a system or UI interface. For the engine, a manual task is handled as a pass-through activity, automatically continuing the process from the moment process execution arrives into it.

Graphical Notation

A manual task is visualized as a rounded rectangle, with a little 'hand' icon in the upper left corner

XML representation

<manualTask id="myManualTask" name="Call client for more information" />

Java Receive Task

Description

A Receive Task is a simple task that waits for the arrival of a certain message. Currently, we have only implemented Java semantics for this task. When process execution arrives at a Receive Task, the process state is committed to the persistence store. This means that the process will stay in this wait state, until a specific message is received by the engine, which triggers the continuation of the process past the Receive Task.

Graphical notation

A Receive Task is visualized as a task (rounded rectangle) with a message icon in the top left corner. The message is white (a black message icon would have send semantics)

XML representation

<receiveTask id="waitState" name="wait" />    

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:

ProcessInstance pi = runtimeService.startProcessInstanceByKey("receiveTask");
Execution execution = runtimeService.createExecutionQuery()
  .processInstanceId(pi.getId())
  .activityId("waitState")
  .singleResult();
assertNotNull(execution);
    
runtimeService.signal(execution.getId());   
          

Shell Task

Description

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).

defining a shell task

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

<serviceTask id="shellEcho" activiti:type="shell">		      
		      

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

Table 8.7. Shell task parameter configuration

PropertyRequired?TypeDescriptionDefault
commandyesStringShell command to execute. 
arg0-5noStringParameter 0 to Parameter 5 
waitnotrue/falsewait if necessary, until the shell process has terminated.true
redirectErrornotrue/falseMerge standard error with the standard output.false
cleanEnvnotrue/falseShell process does not inherit current environment.false
outputVariablenoStringName of variable to contain the outputOutput is not recorded.
errorCodeVariablenoStringName of variable to contain result error codeError level is not registered.
directorynoStringDefault directory of shell processCurrent directory


Example usage

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

<serviceTask id="shellEcho" activiti:type="shell" >
  <extensionElements>
    <activiti:field name="command" stringValue="cmd" />  
    <activiti:field name="arg1" stringValue="/c" />  
    <activiti:field name="arg2" stringValue="echo" />  
    <activiti:field name="arg3" stringValue="EchoTest" />  
    <activiti:field name="wait" stringValue="true" />  
    <activiti:field name="outputVariable" stringValue="resultVar" />  
  </extensionElements>
</serviceTask>		      
		      

Execution listener

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:

  • Start and ending of a process instance.

  • Taking a transition.

  • Start and ending of an activity.

  • Start and ending of a gateway.

  • Start and ending of intermediate events.

  • Ending an start event or starting an end event.

The following process definition contains 3 execution listeners:

  <process id="executionListenersProcess">
  
    <extensionElements>
      <activiti:executionListener class="org.activiti.examples.bpmn.executionlistener.ExampleExecutionListenerOne" event="start" />
    </extensionElements>
    
    <startEvent id="theStart" />
    <sequenceFlow sourceRef="theStart" targetRef="firstTask" />
    
    <userTask id="firstTask" />
    <sequenceFlow sourceRef="firstTask" targetRef="secondTask">
    <extensionElements>
      <activiti:executionListener class="org.activiti.examples.bpmn.executionListener.ExampleExecutionListenerTwo" />
    </extensionElements>
    </sequenceFlow>
    
    <userTask id="secondTask" >
    <extensionElements>
      <activiti:executionListener expression="${myPojo.myMethod(execution.event)}" event="end" />
    </extensionElements>
    </userTask>
    <sequenceFlow sourceRef="secondTask" targetRef="thirdTask" />
       
    <userTask id="thirdTask" />
    <sequenceFlow sourceRef="thirdTask" targetRef="theEnd" />

    <endEvent id="theEnd" />
    
  </process>

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.

public class ExampleExecutionListenerOne implements ExecutionListener {

  public void notify(ExecutionListenerExecution execution) throws Exception {
    execution.setVariable("variableSetInExecutionListener", "firstValue");
    execution.setVariable("eventReceived", execution.getEventName());
  }
}

It is also possible to 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.

<activiti:executionListener expression="${myPojo.myMethod(execution.eventName)}" event="end" />

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's possible to pass the event-name to your methods using execution.eventName.

Execution listeners also support using a delegateExpression, similar to a service task.

<activiti:executionListener event="start" delegateExpression="${myExecutionListenerBean}" />

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.

<activiti:executionListener event="start" class="org.activiti.engine.impl.bpmn.listener.ScriptExecutionListener" >
  <activiti:field name="script">
    <activiti:string>
      def bar = "BAR";  // local variable
      foo = "FOO"; // pushes variable to execution context
      execution.setVariable("var1", "test"); // test access to execution instance
      bar // implicit return value
    </activiti:string>
  </activiti:field>
  <activiti:field name="language" stringValue="groovy" />
  <activiti:field name="resultVariable" stringValue="myVar" />
<activiti:executionListener>

Field injection on execution listeners

When using an execution listener that is configured with the class attribute, field injection can be applied. This is exactly the same mechanism as used Service task field injection, which contains an overview of the possibilities provided by field injection.

The fragment below shows a simple example process with an execution listener with fields injected.

 <process id="executionListenersProcess">
    <extensionElements>
      <activiti:executionListener class="org.activiti.examples.bpmn.executionListener.ExampleFieldInjectedExecutionListener" event="start">
        <activiti:field name="fixedValue" stringValue="Yes, I am " />
        <activiti:field name="dynamicValue" expression="${myVar}" />
      </activiti:executionListener>
    </extensionElements>
    
    <startEvent id="theStart" />
    <sequenceFlow sourceRef="theStart" targetRef="firstTask" />
    
    <userTask id="firstTask" />
    <sequenceFlow sourceRef="firstTask" targetRef="theEnd" />
    
    <endEvent id="theEnd" />
  </process>
        

public class ExampleFieldInjectedExecutionListener implements ExecutionListener {

  private Expression fixedValue;

  private Expression dynamicValue;

  public void notify(ExecutionListenerExecution execution) throws Exception {
    execution.setVariable("var", fixedValue.getValue(execution).toString() + dynamicValue.getValue(execution).toString());
  }
}
          

The class ExampleFieldInjectedExecutionListener concatenates the 2 injected fields (one fixed an the other dynamic) and stores this in the process variable 'var'.

@Deployment(resources = {"org/activiti/examples/bpmn/executionListener/ExecutionListenersFieldInjectionProcess.bpmn20.xml"})
public void testExecutionListenerFieldInjection() {
  Map<String, Object> variables = new HashMap<String, Object>();
  variables.put("myVar", "listening!");
    
  ProcessInstance processInstance = runtimeService.startProcessInstanceByKey("executionListenersProcess", variables);
    
  Object varSetByListener = runtimeService.getVariable(processInstance.getId(), "var");
  assertNotNull(varSetByListener);
  assertTrue(varSetByListener instanceof String);
    
  // Result is a concatenation of fixed injected field and injected expression
  assertEquals("Yes, I am listening!", varSetByListener);
}
        

Task listener

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 user task. 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.

<userTask id="myTask" name="My Task" >
  <extensionElements>
    <activiti:taskListener event="create" class="org.activiti.MyTaskCreateListener" />
  </extensionElements>
</userTask>

A task listener supports following attributes:

  • event (required): the type of task event on which the task listener will be invoked. Possible events are

    • create: occurs when the task has been created an all task properties are set.

    • assignment: occurs when the task is assigned to somebody. Note: when process execution arrives in a userTask, first an assignment event will be fired, before the create event is fired. This might seem an unnatural order, but the reason is pragmatic: when receiving the create event, we usually want to inspect all properties of the task including the assignee.

    • complete: occurs when the task is completed and just before the task is deleted from the runtime data.

    • delete: occurs just before the task is going to be deleted. Notice that it will also be executed when task is normally finished via completeTask.

  • class: the delegation class that must be called. This class must implement the org.activiti.engine.impl.pvm.delegate.TaskListener interface.

    public class MyTaskCreateListener implements TaskListener {
    
      public void notify(DelegateTask delegateTask) {
        // Custom logic goes here
      }
    
    }

    It is also possible to use field injection to pass process variables or the execution to the delegation class. Note that an instance of the delegation class is created upon process deployment (as is the case with any class delegation in Activiti), which means that the instance is shared between all process instance executions.

  • expression: (cannot be used together with the class attribute): specifies an expression that will be executed when the event happens. It is possible to pass the DelegateTask object and the name of the event (using task.eventName) as parameter to the called object.

    <activiti:taskListener event="create" expression="${myObject.callMethod(task, task.eventName)}" />

  • delegateExpression allows to specify an expression that resolves to an object implementing the TaskListener interface, similar to a service task.

    <activiti:taskListener event="create" delegateExpression="${myTaskListenerBean}" />

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

    <activiti:taskListener event="complete" class="org.activiti.engine.impl.bpmn.listener.ScriptTaskListener" >
      <activiti:field name="script">
        <activiti:string>
          def bar = "BAR";  // local variable
          foo = "FOO"; // pushes variable to execution context
          task.setOwner("kermit"); // test access to task instance
          bar // implicit return value
        </activiti:string>
      </activiti:field>
      <activiti:field name="language" stringValue="groovy" />
      <activiti:field name="resultVariable" stringValue="myVar" />
    <activiti:taskListener>

Multi-instance (for each)

Description

A multi-instance activity is a way of defining repetition for a certain 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 subprocess for each item in a given collection, sequentially or in parallel.

A multi-instance is a regular activity that has extra properties defined (so-called 'multi-instance characteristics'') which will cause the activity to be executed multiple times at runtime. Following activities can become a multi-instance activity:

A Gateway or Event can not become multi-instance.

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

  • nrOfInstances: the total number of instances

  • nrOfActiveInstances: the number of currently active, i.e. not yet finished, instances. For a sequential multi-instance, this will always be 1.

  • nrOfCompletedInstances: the number of already completed instances.

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) :

  • loopCounter: indicates the index in the for-each loop of that particular instance. loopCounter variable can be renamed by activiti elementIndexVariable attribute.

Graphical notation

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.

Xml representation

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

<multiInstanceLoopCharacteristics isSequential="false|true">
 ...
</multiInstanceLoopCharacteristics>

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.

<multiInstanceLoopCharacteristics isSequential="false|true">
  <loopCardinality>5</loopCardinality>
</multiInstanceLoopCharacteristics>

Expressions that resolve to a positive number are also possible:

<multiInstanceLoopCharacteristics isSequential="false|true">
  <loopCardinality>${nrOfOrders-nrOfCancellations}</loopCardinality>
</multiInstanceLoopCharacteristics>

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, it is possible to set that specific item of the collection for the instance using the inputDataItem child element. This is shown in the following XML example:

<userTask id="miTasks" name="My Task ${loopCounter}" activiti:assignee="${assignee}">
  <multiInstanceLoopCharacteristics isSequential="false">
    <loopDataInputRef>assigneeList</loopDataInputRef>
    <inputDataItem name="assignee" />
  </multiInstanceLoopCharacteristics>
</userTask>

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:

<userTask id="miTasks" name="My Task" activiti:assignee="${assignee}">
  <multiInstanceLoopCharacteristics isSequential="true" 
     activiti:collection="${myService.resolveUsersForTask()}" activiti:elementVariable="assignee" >
  </multiInstanceLoopCharacteristics>
</userTask>

A multi-instance activity ends when all instances are finished. However, it is possible to 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.

<userTask id="miTasks" name="My Task" activiti:assignee="${assignee}">
  <multiInstanceLoopCharacteristics isSequential="false" 
     activiti:collection="assigneeList" activiti:elementVariable="assignee" >
    <completionCondition>${nrOfCompletedInstances/nrOfInstances >= 0.6 }</completionCondition>
  </multiInstanceLoopCharacteristics>
</userTask>

In this example, there will be parallel instances 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.

Boundary events and multi-instance

Since a multi-instance is a regular activity, it is possible to define a boundary event 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 subprocess:

Here, all instances of the subprocess will be destroyed when the timer fires, regardless of how many instances there are or which inner activities are currently not yet completed.

Compensation Handlers

Description

[EXPERIMENTAL]

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.

Graphical notation

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

XML representation

In order to declare an activity to be a compensation handler, we need to set the attribute isForCompensation to true:
<serviceTask id="undoBookHotel" isForCompensation="true" activiti:class="...">
</serviceTask>

Sub-Processes and Call Activities

Sub-Process

Description

A Sub-Process is an activity that contains other activities, gateways, events, etc. which on itself form a process that is part of the bigger process. A Sub-Process is completely defined inside a parent process (that's why it's often called an embedded Sub-Process).

Sub-Processes have two major use cases:

  • Sub-Processes allow hierarchical modeling. Many modeling tools allow that Sub-Processes can be collapsed, hiding all the details of the Sub-Process and displaying a high-level end-to-end overview of the business process.

  • A Sub-Process creates a new scope for events. Events that are thrown during execution of the Sub-Process, can be caught by a boundary event on the boundary of the Sub-Process, thus creating a scope for that event limited to the Sub-Process.

Using a Sub-Process does impose some constraints:

  • A Sub-Process can only have one none start event, no other start event types are allowed. A Sub-Process must at least have one end event. Note that the BPMN 2.0 specification allows to omit the start and end events in a Sub-Process, but the current Activiti implementation does not support this.

  • Sequence flow can not cross Sub-Process boundaries.

Graphical Notation

A Sub-Process is visualized as a typical activity, i.e. a rounded rectangle. In case the Sub-Process is collapsed, only the name and a plus-sign are displayed, giving a high-level overview of the process:

In case the Sub-Process is expanded, the steps of the Sub-Process are displayed within the Sub-Process boundaries:

One of the main reasons to use a Sub-Process, is to define a scope for a certain event. The following process model shows this: both the investigate software/investigate hardware tasks need to be done in parallel, but both tasks need to be done within a certain time, before Level 2 support is consulted. Here, the scope of the timer (i.e. which activities must be done in time) is constrained by the Sub-Process.

XML representation

A Sub-Process is defined by the subprocess element. All activities, gateways, events, etc. that are part of the Sub-Process, need to be enclosed within this element.

<subProcess id="subProcess">
    
  <startEvent id="subProcessStart" />
  
  ... other Sub-Process elements ...

  <endEvent id="subProcessEnd" />
    
 </subProcess>          
          

Event Sub-Process

Description

The Event Sub-Process is new in BPMN 2.0. An Event Sub-Process is a subprocess that is triggered by an event. An Event Sub-Process can be added at the process level or at any subprocess level. The event used to trigger an event subprocess is configured using a start event. From this, it follows that none start events are not supported for Event Sub-Processes. An Event Sub-Process might be triggered using events like message events, error events, signal events, timer events, or compensation events. The subscription to the start event is created when the scope (process instance or subprocess) hosting the Event Sub-Process is created. The subscription is removed when the scope is destroyed.

An Event Sub-Process may be interrupting or non-interrupting. An interrupting subprocess cancels any executions in the current scope. A non-interrupting Event Sub-Process spawns a new concurrent execution. While an interrupting Event Sub-Process can only be triggered once for each activation of the scope hosting it, a non-interrupting Event Sub-Process can be triggered multiple times. The fact whether the subprocess is interrupting is configured using the start event triggering the Event Sub-Process.

An Event Sub-Process must not have any incoming or outgoing sequence flows. Since an Event Sub-Process is triggered by an event, an incoming sequence flow makes no sense. When an Event Sub-Process is ended, either the current scope is ended (in case of an interrupting Event Sub-Process), or the concurrent execution spawned for the non-interrupting subprocess is ended.

Current limitations:

  • Activiti only supports interrupting Event Sub-Processes.

  • Activiti only supports Event Sub-Process triggered using an Error Start Event or Message Start Event.

Graphical Notation

An Event Sub-Process might be visualized as a an embedded subprocess with a dotted outline.

XML representation

An Event Sub-Process is represented using XML in the same way as a an embedded subprocess. In addition the attribute triggeredByEvent must have the value true:

<subProcess id="eventSubProcess" triggeredByEvent="true">
	...
</subProcess>

Example

The following is an example of an Event Sub-Process triggered using an Error Start Event. The Event Sub-Process is located at the "process level", i.e. is scoped to the process instance:

This is how the Event Sub-Process would look like in XML:

<subProcess id="eventSubProcess" triggeredByEvent="true">
	<startEvent id="catchError">
		<errorEventDefinition errorRef="error" /> 
	</startEvent>
	<sequenceFlow id="flow2" sourceRef="catchError" targetRef="taskAfterErrorCatch" />
	<userTask id="taskAfterErrorCatch" name="Provide additional data" />
</subProcess>

As already stated, an Event Sub-Process can also be added to an embedded subprocess. If it is added to an embedded subprocess, it becomes an alternative to a boundary event. Consider the two following process diagrams. In both cases the embedded subprocess throws an error event. Both times the error is caught and handled using a user task.

as opposed to:

In both cases the same tasks are executed. However, there are differences between both modelling alternatives:

  • The embedded subprocess is executed using the same execution which executed the scope it is hosted in. This means that an embedded subprocess has access to the variables local to it's scope. When using a boundary event, the execution created for executing the embedded subprocess is deleted by the sequence flow leaving the boundary event. This means that the variables created by the embedded subprocess are not available anymore.

  • When using an Event Sub-Process, the event is completely handled by the subprocess it is added to. When using a boundary event, the event is handled by the parent process.

These two differences can help you decide whether a boundary event or an embedded subprocess is better suited for solving a particular process modeling / implementation problem.

Transaction subprocess

[EXPERIMENTAL]

Description

A transaction subprocess is an embedded subprocess, 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:

  • A transaction is successful, if it is neither cancelled not terminated by a hazard. If a transaction subprocess is successful, it is left using the outgoing sequenceflow(s). A successful transaction might be compensated if a compensation event is thrown later in the process.

    Note: just as "ordinary" embedded subprocesses, a transaction may be compensated after successful completion using an intermediary throwing compensation event.

  • A transaction is cancelled, if an execution reaches the cancel end event. In that case, all executions are terminated and removed. A single remaining execution is then set to the cancel boundary event, which triggers compensation. After compensation is completed, the transaction subprocess is left using the outgoing sequence flow(s) of the cancel boundary event.

  • A transaction is ended by a hazard, if an error event is thrown, that is not caught within the scope of the transaction subprocess. (This also applies if the error is caught on the boundary of the transaction subprocess.) In this case, compensation is not performed.

The following diagram illustrates the three different outcomes:

Relation to ACID transactions: it is important not to confuse the bpmn transaction subprocess with technical (ACID) transactions. The bpmn transaction subprocess is not a way to scope technical transactions. In order to understand transaction management in Activiti, read the section on concurrency and transactions. A bpmn transaction is different from a technical transaction in the following ways:

  • While an ACID transaction is typically short lived, a bpmn transaction may take hours, days or even months to complete. (Consider the case where one of the activities grouped by a transaction is a usertask, typically people have longer response times than applications. Or, in another situation, a bpmn transaction might wait for some business event to occur, like the fact that a particular order has been fulfilled.) Such operations usually take considerably longer to complete than updating a record in a database, or storing a message using a transactional queue.

  • Because it is impossible to scope a technical transaction to the duration of a business activity, a bpmn transaction typically spans multiple ACID transactions.

  • Since a bpmn transaction spans multiple ACID transactions, we loose ACID properties. For example, consider the example given above. Let's assume the "book hotel" and the "charge credit card" operations are performed in separate ACID transactions. Let's also assume that the "book hotel" activity is successful. Now we have an intermediary inconsistent state, because we have performed an hotel booking but have not yet charged the credit card. Now, in an ACID transaction, we would also perform different operations sequentially and thus also have an intermediary inconsistent state. What is different here, is that the inconsistent state is visible outside of the scope of the transaction. For example, if the reservations are made using an external booking service, other parties using the same booking service might already see that the hotel is booked. This means, that when implementing business transactions, we completely loose the isolation property (Granted: we usually also relax isolation when working with ACID transactions to allow for higher levels of concurrency, but there we have fine grained control and intermediary inconsistencies are only present for very short periods of times).

  • A bpmn business transaction can also not be rolled back in the traditional sense. Since it spans multiple ACID transactions, some of these ACID transactions might already be committed at the time the bpmn transaction is cancelled. At this point, they cannot be rolled back anymore.

Since bpmn transactions 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:

  • The rollback is performed using compensation. If a cancel event is thrown in the scope of a transaction, the effects of all activities that executed successfully and have a compensation handler are compensated.

  • The lack of isolation is also often dealt with using domain specific solutions. For instance, in the example above, an hotel room might appear to be booked to a second customer, before we have actually made sure that the first customer can pay for it. Since this might be undesirable from a business perspective, a booking service might choose to allow for a certain amount of overbooking.

  • In addition, since the transaction can be aborted in case of a hazard, the booking service has to deal with the situation where a hotel room is booked but payment is never attempted (since the transaction was aborted). In that case the booking service might choose a strategy where a hotel room is reserved for a maximum period of time and if payment is not received until then, the booking is cancelled.

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:

  • The bpmn specification requires that the process engine reacts to events issued by the underlying transaction protocol and for instance that a transaction is cancelled, if a cancel event occurs in the underlying protocol. As an embeddable engine, Activiti does currently not support this. (For some ramifications of this, see paragraph on consistency below.)

Consistency on top of ACID transactions and optimistic concurrency: A bpmn transaction 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. However, it is important to recognize that in Activiti, the consistency model for bpmn transactions 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, bpmn error, 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 implementing bpmn transactions in Activiti, the same set of rules apply as when implementing "ordinary" processes and subprocesses. So to effectively guarantee consistency, it is important to implement processes in a way that does take the optimistic, transactional execution model into consideration.

Graphical Notation

An transaction subprocess might be visualized as a an embedded subprocess with a double outline.

XML representation

A transaction subprocess is represented using xml using the transaction tag:

<transaction id="myTransaction" >
	...
</transaction>

Example

The following is an example of a transaction subprocess:

Call activity (subprocess)

Description

BPMN 2.0 makes a distinction between a regular subprocess, often also called embedded subprocess, and the call activity, which looks very similar. From a conceptual point of view, both will call a subprocess 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 subprocess 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 subprocess, potentially creating parallel child execution as within a regular process. The super-execution waits until the subprocess is completely ended, and continues the original process afterwards.

Graphical Notation

A call activity is visualized the same as a subprocess, however 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 subprocess representation.

XML 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.

<callActivity id="callCheckCreditProcess" name="Check credit" calledElement="checkCreditProcess" />

Note that the process definition of the subprocess is resolved at runtime. This means that the subprocess can be deployed independently from the calling process, if needed.

Passing variables

You can pass process variables to the sub process and vice versa. The data is copied into the subprocess when it is started and copied back into the main process when it ends.

<callActivity id="callSubProcess" calledElement="checkCreditProcess" >
  <extensionElements>
	  <activiti:in source="someVariableInMainProcess" target="nameOfVariableInSubProcess" />
	  <activiti:out source="someVariableInSubProcss" target="nameOfVariableInMainProcess" />
  </extensionElements>
</callActivity>

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.

It is possible to use expressions here as well:

<callActivity id="callSubProcess" calledElement="checkCreditProcess" >
	<extensionElements>
	  <activiti:in sourceExpression="${x+5}"" target="y" />
	  <activiti:out source="${y+5}" target="z" />
	</extensionElements>
</callActivity>

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

Example

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:

<startEvent id="theStart" />
<sequenceFlow id="flow1" sourceRef="theStart" targetRef="receiveOrder" />

<manualTask id="receiveOrder" name="Receive Order" />
<sequenceFlow id="flow2" sourceRef="receiveOrder" targetRef="callCheckCreditProcess" />
    
<callActivity id="callCheckCreditProcess" name="Check credit" calledElement="checkCreditProcess" />
<sequenceFlow id="flow3" sourceRef="callCheckCreditProcess" targetRef="prepareAndShipTask" />
   
<userTask id="prepareAndShipTask" name="Prepare and Ship" />
<sequenceFlow id="flow4" sourceRef="prepareAndShipTask" targetRef="end" />
    
<endEvent id="end" />

The subprocess looks as follows:

There is nothing special to the process definition of the subprocess. It could as well be used without being called from another process.

Transactions and Concurrency

Asynchronous Continuations

Activiti executes processes in a transactional way which can be configured to suite your needs. Lets start by looking at how Activiti scopes transactions normally. If you trigger Activiti (i.e. start a process, complete a task, signal an execution), Activiti is going to advance in the process, until it reaches wait states on each active path of execution. More concretely speaking it performs a depth-first search through the process graph and returns if it has reached wait states on every branch 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 picture:

We see a segment of a BPMN processes with a usertask, a service task and a timer event. Completing the usertask 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 also the default behavior of 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 we want. Sometimes we 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 come into play. Consider the following process (fragment):

This time we are completing the user task, generating an invoice and then send that invoice to the customer. This time 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 usertask if generating an invoice fails. So what we want Activiti to do is complete the user task (1), commit the transaction and return the control to the calling application. Then we want to 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 behind the scenes, when we reach the "generate invoice" task, we are creating a job "message" for Activiti to continue the process later and persisting it into the database. This job is then picked up by the job executor and executed. We are also giving the local job executor a little hint that there is a new job, to improve performance.

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

<serviceTask id="service1" name="Generate Invoice" activiti:class="my.custom.Delegate" activiti:async="true" /> 
        

activiti:async ca 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, the async continuation allows us to execute the start execution listeners in a separate thread/transaction.

Exclusive Jobs

Since Activiti 5.9, the JobExecutor makes sure that jobs from a single process instance are never executed concurrently. Why is this?

Why exclusive Jobs?

Consider the following process definition:

We have a parallel gateway followed by three service tasks which all perform an asynchronous continuation. As a result of this, three jobs are added to the database. Once such a job is present in the database it can be processes by the JobExecutor. The JobExecutor acquires the jobs and delegates them to a thread pool of worker threads which actually process the jobs. 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 is usually a good thing. However it also bears an inherent problem: consistency. Consider the parallel join after the service tasks. When execution of a service tasks is completed, we arrive at the parallel join and need to decide whether to wait for the other executions or whether we can move forward. That means, for each branch arriving at the parallel join, we need to take a decision whether we can continue or whether we need to wait for one or more other executions on the other branches.

Why is this a problem? 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 consequence is that the transactions in which the services are executed and in which the 3 individual executions arrive at the parallel join can overlap. And 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.

How does Activiti address this problem? Activiti performs optimistic locking. Whenever we take a decision based on data that might not be current (because another transaction might modify it before we commit, we make sure to increment the version of the same database row in both transactions). This way, 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 hopefully this time pass the synchronizing gateway.

Is this a good solution? As we have seen, optimistic locking allows Activiti to prevent inconsistencies. It makes sure that we do not "keep stuck at the joining gateway", meaning: either all executions have passed the gateway or, there are jobs in the database making sure that we retry passing it. However, while this is a perfectly fine solution from the point of view of persistence and consistency, this might not always be desirable behavior at an higher level:

  • Activiti will retry the same job for a fixed maximum number of times only ('3' in the default configuration). After that, the job will still be present in the database but not be retried actively anymore. That means that an operator would need to trigger the job manually.

  • If a job has non-transactional side effects, those will not be rolled back by the failing transaction. For instance, if the "book concert tickets" service does not share the same transaction as Activiti, we might book multiple tickets if we retry the job.

In Activiti 5.9 we thus introduced a concept, which was already present in jBPM 4 and is called 'exclusive jobs'.

What are exclusive jobs?

An exclusive job cannot be performed at the same time as another exclusive job from the same process instance. Consider the process shown above: if we declare the service tasks to be exclusive, the JobExecutor will make sure that the corresponding jobs are not executed concurrently. Instead, it will make sure that whenever it acquires an exclusive job from a certain process instance, it acquires all other exclusive jobs from the same process instance and delegates them to the same worker thread. This ensures sequential execution execution of the jobs.

How can I enable this feature? Since Activiti 5.9, exclusive jobs are the default configuration. All asynchronous continuations and timer events are thus exclusive by default. In addition, if you want a job to be non-exclusive, you can configure it as such using activiti:exclusive="false". For example, the following servicetask would be asynchronous but non-exclusive.

<serviceTask id="service" activiti:expression="${myService.performBooking(hotel, dates)}" activiti:async="true" activiti:exclusive="false" />        		
        		

Is this a good solution? We had some people asking whether this was a good solution. Their concern was that this would to prevent you from "doing things" in parallel and would thus be a performance problem. Again, two things have to be taken into consideration:

  • It can be turned off if you are an expert and know what you are doing (and have understood the section named "Why exclusive Jobs?"). Other than that, it is more intuitive for most users if things like asynchronous continuations and timers just work.

  • It is actually not a performance issue. Performance is an issue under heavy load. Heavy load means that all worker threads of the job executor are busy all the time. With exclusive jobs, Activiti will simply distribute the load differently. Exclusive jobs means that jobs from a single process instance are performed by the same thread sequentially. But consider: you have more than one single process instance. And jobs from other process instances are delegated to other threads and executed concurrently. This means that with exclusive jobs Activiti will not execute jobs from the same process instance concurrently, but it will still execute multiple instances concurrently. From an overall throughput perspective this is desirable in most scenarios as it usually leads to individual instances being done more quickly. Furthermore, data that is required for executing subsequent jobs of the same process instance will already be in the cache of the executing cluster node. If the jobs do not have this node affinity, that data might need to be fetched from the database again.

Process Initiation Authorization

By default everyone is allowed to start a new process instance of deployed process definitions. The process initiation authorization functionality allows to define users and groups so that web clients can optionally restrict users to start a new process instance. NOTE that the authorization definition is NOT validated by the Activiti Engine in any way. This functionality is only meant for developers to ease the implementation of authorization rules in a web client. The syntax is similar to the syntax of user assignment for a user task. A user or group can be assigned as potential initiator of a process using <activiti:potentialStarter> tag. Here is an example:
   <process id="potentialStarter">
     <extensionElements>
       <activiti:potentialStarter>
         <resourceAssignmentExpression>
           <formalExpression>group2, group(group3), user(user3)</formalExpression>
         </resourceAssignmentExpression>
       </activiti:potentialStarter>
     </extensionElements>
   <startEvent id="theStart"/>
   ...
 
In the above xml excerpt user(user3) refers directly to user user3 and group(group3) to group group3. No indicator will default to a group type. It is also possible to use attributes of the <process> tag, namely <activiti:candidateStarterUsers> and <activiti:candidateStarterGroups>. Here is an example:
      <process id="potentialStarter" activiti:candidateStarterUsers="user1, user2"  
                                        activiti:candidateStarterGroups="group1">
      ...
  

It is possible to use both attributes simultaneously.

After the process initiation authorizations are defined, a developer can retrieve the authorization definition using the following methods. This code retrieves the list of process definitions which can be initiated by the given user:

      processDefinitions = repositoryService.createProcessDefinitionQuery().startableByUser("userxxx").list();
   

It's also possible to retrieve all identity links that are defined as potential starter for a specific process definition

      identityLinks = repositoryService.getIdentityLinksForProcessDefinition("processDefinitionId");
   

The following example shows how to get list of users who can initiate the given process:

      List<User> authorizedUsers =  identityService().createUserQuery().potentialStarter("processDefinitionId").list();
   

Exactly the same way, the list of groups that is configured as a potential starter to a given process definition can be retrieved:

     
      List<Group> authorizedGroups =  identityService().createGroupQuery().potentialStarter("processDefinitionId").list();
   

Data objects

[EXPERIMENTAL]

BPMN provides the possibility to define data objects as part of a process or sub process element. According to the BPMN specification it's possible to include complex XML structures that might be imported from XSD definitions. As a first start to support data objects in Activiti the folowing XSD types are supported:

        <dataObject id="dObj1" name="StringTest" itemSubjectRef="xsd:string"/>
      
        <dataObject id="dObj2" name="BooleanTest" itemSubjectRef="xsd:boolean"/>
      
        <dataObject id="dObj3" name="DateTest" itemSubjectRef="xsd:datetime"/>
      
        <dataObject id="dObj4" name="DoubleTest" itemSubjectRef="xsd:double"/>
      
        <dataObject id="dObj5" name="IntegerTest" itemSubjectRef="xsd:int"/>
      
        <dataObject id="dObj6" name="LongTest" itemSubjectRef="xsd:long"/>
      

    The data object definitions will be automatically converted to process variables using the 'name' attribute value as the name for the new variable. In addition to the definition of the data object Activiti also provides an extension element to assign a default value to the variable. The following BPMN snippet provides an example:

            <process id="dataObjectScope" name="Data Object Scope" isExecutable="true">
              <dataObject id="dObj123" name="StringTest123" itemSubjectRef="xsd:string">
                <extensionElements>
                  <activiti:value>Testing123</activiti:value>
                </extensionElements>
              </dataObject>
          

    Chapter 9. Forms

    Activiti provides a convenient and flexible way to add forms for the manual steps of your business processes. We support two strategies to work with forms: Build-in form rendering with form properties and external form rendering.

    Form properties

    All information relevant to a business process is either included in the process variables themselves or referenced through the process variables. Activiti supports complex Java objects to be stored as process variables like Serializable objects, JPA entities or whole XML documents as Strings.

    Starting a process and completing user tasks is where people are involved into a process. Communicating with people requires forms to be rendered in some UI technology. In order to facilitate multiple UI technologies easy, the process definition can include the logic of transforming of the complex Java typed objects in the process variables to a Map<String,String> of 'properties'.

    Any UI technology can then build a form on top of those properties, using the Activiti API methods that expose the property information. The properties can provide a dedicated (and more limited) view on the process variables. The properties needed to display a form are available in the FormData return values of for example

    StartFormData FormService.getStartFormData(String processDefinitionId)

    or

    TaskFormdata FormService.getTaskFormData(String taskId)

    .

    By default, the build-in form engines, 'sees' the properties as well as the process variables. So there is no need to declare task form properties if they match 1-1 with the process variables. For example, with the following declaration:

    <startEvent id="start" />

    All process variables are available when execution arrives in the startEvent, but

    formService.getStartFormData(String processDefinitionId).getFormProperties()

    will be empty since no specific mapping was defined.

    In the above case, all the submitted properties will be stored as process variables. This means that by simply adding a new input field in the form, a new variable can be stored.

    Properties are derived from process variables, but they don't have to be stored as process variables. For example, a process variable could be a JPA entity of class Address. And a form property StreetName used by the UI technology could be linked with an expression #{address.street}

    Analogue, the properties that a user is supposed to submit in a form can be stored as a process variable or as a nested property in one of the process variables with a UEL value expression like e.g. #{address.street} .

    Analogue the default behavior of properties that are submitted is that they will be stored as process variables unless a formProperty declaration specifies otherwise.

    Also type conversions can be applied as part of the processing between form properties and process variables.

    For example:

    <userTask id="task">
      <extensionElements>
        <activiti:formProperty id="room" />
        <activiti:formProperty id="duration" type="long"/>
        <activiti:formProperty id="speaker" variable="SpeakerName" writable="false" />
        <activiti:formProperty id="street" expression="#{address.street}" required="true" />
      </extensionElements>
    </userTask>
    • Form property room will be mapped to process variable room as a String.

    • Form property duration will be mapped to process variable duration as a java.lang.Long

    • Form property speaker will be mapped to process variable SpeakerName. It will only be available in the TaskFormData object. If property speaker is submitted, an ActivitiException will be thrown. Analogue, with attribute readable="false", a property can be excluded from the FormData, but still be processed in the submit.

    • Form property street will be mapped to Java bean property street in process variable address as a String. And required="true" will throw an exception during the submit if the property is not provided.

    It's also possible to provide type meta data as part of the FormData that is returned from methods StartFormData FormService.getStartFormData(String processDefinitionId) and TaskFormdata FormService.getTaskFormData(String taskId)

    We support the following form property types:

    • string (org.activiti.engine.impl.form.StringFormType)

    • long (org.activiti.engine.impl.form.LongFormType)

    • enum (org.activiti.engine.impl.form.EnumFormType)

    • date (org.activiti.engine.impl.form.DateFormType)

    • boolean (org.activiti.engine.impl.form.BooleanFormType)

    For each form property declared, the following FormProperty information will be made available through List<FormProperty> formService.getStartFormData(String processDefinitionId).getFormProperties() and List<FormProperty> formService.getTaskFormData(String taskId).getFormProperties()

    public interface FormProperty {
      /** the key used to submit the property in {@link FormService#submitStartFormData(String, java.util.Map)} 
       * or {@link FormService#submitTaskFormData(String, java.util.Map)} */
      String getId();
      /** the display label */
      String getName();
      /** one of the types defined in this interface like e.g. {@link #TYPE_STRING} */
      FormType getType();
      /** optional value that should be used to display in this property */
      String getValue();
      /** is this property read to be displayed in the form and made accessible with the methods 
       * {@link FormService#getStartFormData(String)} and {@link FormService#getTaskFormData(String)}. */
      boolean isReadable();
      /** is this property expected when a user submits the form? */
      boolean isWritable();
      /** is this property a required input field */
      boolean isRequired();
    }

    For example:

    <startEvent id="start">
      <extensionElements>
        <activiti:formProperty id="speaker" 
          name="Speaker"
          variable="SpeakerName" 
          type="string" />
    
        <activiti:formProperty id="start" 
          type="date" 
          datePattern="dd-MMM-yyyy" />
    
        <activiti:formProperty id="direction" type="enum">
          <activiti:value id="left" name="Go Left" />
          <activiti:value id="right" name="Go Right" />
          <activiti:value id="up" name="Go Up" />
          <activiti:value id="down" name="Go Down" />
        </activiti:formProperty>
        
      </extensionElements>
    </startEvent>

    All that information is accessible through the API. The type names can be obtained with formProperty.getType().getName(). And even the date pattern is available with formProperty.getType().getInformation("datePattern") and the enumeration values are accessible with formProperty.getType().getInformation("values")

    Activiti explorer supports the form properties and will render the form accordingly to the form definition. The following XML snippet

    <startEvent ... >
      <extensionElements>
        <activiti:formProperty id="numberOfDays" name="Number of days" value="${numberOfDays}" type="long" required="true"/>
        <activiti:formProperty id="startDate" name="First day of holiday (dd-MM-yyy)" value="${startDate}" datePattern="dd-MM-yyyy hh:mm" type="date" required="true" />
        <activiti:formProperty id="vacationMotivation" name="Motivation" value="${vacationMotivation}" type="string" />
      </extensionElements>
    </userTask>
          

    will render to a process start form when used in Activiti Explorer

    External form rendering

    The API also allows for you to perform your own task form rendering outside of the Activiti Engine. These steps explain the hooks that you can use to render your task forms yourself.

    Essentially, all the data that's needed to render a form is assembled in one of these two service methods: StartFormData FormService.getStartFormData(String processDefinitionId) and TaskFormdata FormService.getTaskFormData(String taskId).

    Submitting form properties can be done with ProcessInstance FormService.submitStartFormData(String processDefinitionId, Map<String,String> properties) and void FormService.submitStartFormData(String taskId, Map<String,String> properties)

    To learn about how form properties map to process variables, see the section called “Form properties”

    You can place any form template resource inside the business archives that you deploy (in case you want to store them versioned with the process). It will be available as a resource in the deployment, which you can retrieve using: String ProcessDefinition.getDeploymentId() and InputStream RepositoryService.getResourceAsStream(String deploymentId, String resourceName); This could be your template definition file, which you can use to render/show the form in your own application.

    You can use this capability of accessing the deployment resources beyond task forms for any other purposes as well.

    The attribute <userTask activiti:formKey="..." is exposed by the API through String FormService.getStartFormData(String processDefinitionId).getFormKey() and String FormService.getTaskFormData(String taskId).getFormKey(). You could use this to store the full name of the template within your deployment (e.g. org/activiti/example/form/my-custom-form.xml), but this is not required at all. For instance, you could also store a generic key in the form attribute and apply an algorithm or transformation to get to the actual template that needs to be used. This might be handy when you want to render different forms for different UI technologies like e.g. one form for usage in a web app of normal screen size, one form for mobile phone's small screens and maybe even a template for an IM form or an email form.

    Chapter 10. JPA

    You can use JPA-Entities as process variables, allowing you to:

    • Updating existing JPA-entities based on process variables, that can be filled in on a form in a userTask or generated in a serviceTask.

    • Reusing existing domain model without having to write explicit services to fetch the entities and update the values

    • Make decisions (gateways) based on properties of existing entities.

    • ...

    Requirements

    Only entities that comply to the following are supported:

    • Entities should be configured using JPA-annotations, we support both field and property-access. Mapped super classes can also be used.

    • Entity should have a primary key annotated with @Id, compound primary keys are not supported (@EmbeddedId and @IdClass). The Id field/property can be of any type supported in the JPA-spec: Primitive types and their wrappers (excluding boolean), String, BigInteger, BigDecimal, java.util.Date and java.sql.Date.

    Configuration

    To be able to use JPA-entities, the engine must have a reference to an EntityManagerFactory. This can be done by configuring a reference or by supplying a persistence-unit name. JPA-entities used as variables will be detected automatically and will be handled accordingly.

    The example configuration below uses the jpaPersistenceUnitName:

    <bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration">
      
        <!-- Database configurations -->
        <property name="databaseSchemaUpdate" value="true" />
        <property name="jdbcUrl" value="jdbc:h2:mem:JpaVariableTest;DB_CLOSE_DELAY=1000" />
    
        <property name="jpaPersistenceUnitName" value="activiti-jpa-pu" />
        <property name="jpaHandleTransaction" value="true" />
        <property name="jpaCloseEntityManager" value="true" />
        
        <!-- job executor configurations -->
        <property name="jobExecutorActivate" value="false" />
        
        <!-- mail server configurations -->
        <property name="mailServerPort" value="5025" />    
    </bean>
            

    The next example configuration below provides a EntityManagerFactory which we define ourselves (in this case, an open-jpa entity manager). Note that the snippet only contains the beans that are relevant for the example, the others are omitted. Full working example with open-jpa entity manager can be found in the activiti-spring-examples (/activiti-spring/src/test/java/org/activiti/spring/test/jpa/JPASpringTest.java)

    <bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
      <property name="persistenceUnitManager" ref="pum"/>
      <property name="jpaVendorAdapter">
        <bean class="org.springframework.orm.jpa.vendor.OpenJpaVendorAdapter">
          <property name="databasePlatform" value="org.apache.openjpa.jdbc.sql.H2Dictionary" />
        </bean>
      </property>
    </bean>
    
    <bean id="processEngineConfiguration" class="org.activiti.spring.SpringProcessEngineConfiguration">
      <property name="dataSource" ref="dataSource" />
      <property name="transactionManager" ref="transactionManager" />
      <property name="databaseSchemaUpdate" value="true" />
      <property name="jpaEntityManagerFactory" ref="entityManagerFactory" />
      <property name="jpaHandleTransaction" value="true" />
      <property name="jpaCloseEntityManager" value="true" />
      <property name="jobExecutorActivate" value="false" />
    </bean>
            

    The same configurations can also be done when building an engine programmatically, example:

    ProcessEngine processEngine = ProcessEngineConfiguration
      .createProcessEngineConfigurationFromResourceDefault()
      .setJpaPersistenceUnitName("activiti-pu")
      .buildProcessEngine();
            

    Configuration properties:

    • jpaPersistenceUnitName: The name of the persistence-unit to use. (Make sure the persistence-unit is available on the classpath. According to the spec, the default location is /META-INF/persistence.xml). Use either jpaEntityManagerFactory or jpaPersistenceUnitName.

    • jpaEntityManagerFactory: An reference to a bean implementing javax.persistence.EntityManagerFactory that will be used to load the Entities and flushing the updates. Use either jpaEntityManagerFactory or jpaPersistenceUnitName.

    • jpaHandleTransaction: Flag indicating that the engine should begin and commit/rollback the transaction on the used EntityManager instances. Set to false when Java Transaction API (JTA) is used.

    • jpaCloseEntityManager: Flag indicating that the engine should close the EntityManager instance that was obtained from the EntityManagerFactory. Set to false when the EntityManager is container-managed (e.g. when using an Extended Persistence Context which isn't scoped to a single transaction').

    Usage

    Simple Example

    Examples for using JPA variables can be found in JPAVariableTest. We'll explain JPAVariableTest.testUpdateJPAEntityValues step by step.

    First of all, we create a EntityManagerFactory for our persistence-unit, which is based on META-INF/persistence.xml. This contains classes which should be included in the persistence unit and some vendor-specific configuration.

    We are using a simple entity in the test, having an id and String value property, which is also persisted. Before running the test, we create an entity and save this.

    @Entity(name = "JPA_ENTITY_FIELD")
    public class FieldAccessJPAEntity {
    
      @Id
      @Column(name = "ID_")
      private Long id;
    
      private String value;
    
      public FieldAccessJPAEntity() {
        // Empty constructor needed for JPA
      }
    
      public Long getId() {
        return id;
      }
    
      public void setId(Long id) {
        this.id = id;
      }
    
      public String getValue() {
        return value;
      }
    
      public void setValue(String value) {
        this.value = value;
      }
    }       
            

    We start a new process instance, adding the entity as a variable. As with other variables, they are stored in the persistent storage of the engine. When the variable is requested the next time, it will be loaded from the EntityManager based on the class and Id stored.

    Map<String, Object> variables = new HashMap<String, Object>();
    variables.put("entityToUpdate", entityToUpdate);
        
    ProcessInstance processInstance = runtimeService.startProcessInstanceByKey("UpdateJPAValuesProcess", variables);
            

    The first node in our process definition contains a serviceTask that will invoke the method setValue on entityToUpdate, which resolves to the JPA variable we set earlier when starting the process instance and will be loaded from the EntityManager associated with the current engine's context'.

    <serviceTask id='theTask' name='updateJPAEntityTask' activiti:expression="${entityToUpdate.setValue('updatedValue')}" />        
            

    When the service-task is finished, the process instance waits in a userTask defined in the process definition, which allows us to inspect the process instance. At this point, the EntityManager has been flushed and the changes to the entity have been pushed to the database. When we get the value of the variable entityToUpdate, it's loaded again and we get the entity with it's value property set to updatedValue.

    // Servicetask in process 'UpdateJPAValuesProcess' should have set value on entityToUpdate.
    Object updatedEntity = runtimeService.getVariable(processInstance.getId(), "entityToUpdate");
    assertTrue(updatedEntity instanceof FieldAccessJPAEntity);
    assertEquals("updatedValue", ((FieldAccessJPAEntity)updatedEntity).getValue());
            

    Query JPA process variables

    You can query for ProcessInstances and Executions that have a certain JPA-entity as variable value. Note that only variableValueEquals(name, entity) is supported for JPA-Entities on ProcessInstanceQuery and ExecutionQuery. Methods variableValueNotEquals, variableValueGreaterThan, variableValueGreaterThanOrEqual, variableValueLessThan and variableValueLessThanOrEqual are unsupported and will throw an ActivitiException when an JPA-Entity is passed as value.

     ProcessInstance result = runtimeService.createProcessInstanceQuery().variableValueEquals("entityToQuery", entityToQuery).singleResult();
            

    Advanced example using Spring beans and JPA

    A more advanced example, JPASpringTest, can be found in activiti-spring-examples. It describes the following simple use case:

    • An existing Spring-bean which uses JPA entities already exists which allows for Loan Requests to be stored.

    • Using Activiti, we can use the existing entities, obtained through the existing bean, and use them as variable in our process.

      Process is defined in the following steps:

      • Service task that creates a new LoanRequest, using the existing LoanRequestBean using variables received when starting the process (e.g. could come from a start form). The created entity is stored as a variable, using activiti:resultVariable which stores the expression result as a variable.

      • UserTask that allows a manager to review the request and approve/disapprove, which is stored as a boolean variable approvedByManager

      • ServiceTask that updates the loan request entity so the entity is in sync with the process.

      • Depending on the value of the entity property approved, an exclusive gateway is used to make a decision about what path to take next: When the request is approved, process ends, otherwise, an extra task will become available (Send rejection letter), so the customer can be notified manually by a rejection letter.

    Please note that the process doesn't contain any forms, since it is only used in a unit test.

    <?xml version="1.0" encoding="UTF-8"?>
    <definitions id="taskAssigneeExample" 
      xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:activiti="http://activiti.org/bpmn"
      targetNamespace="org.activiti.examples">
      
      <process id="LoanRequestProcess" name="Process creating and handling loan request">
        <startEvent id='theStart' />
        <sequenceFlow id='flow1' sourceRef='theStart' targetRef='createLoanRequest' />
        
        <serviceTask id='createLoanRequest' name='Create loan request' 
          activiti:expression="${loanRequestBean.newLoanRequest(customerName, amount)}" 
          activiti:resultVariable="loanRequest"/>    
        <sequenceFlow id='flow2' sourceRef='createLoanRequest' targetRef='approveTask' />
        
        <userTask id="approveTask" name="Approve request" />
        <sequenceFlow id='flow3' sourceRef='approveTask' targetRef='approveOrDissaprove' />
        
        <serviceTask id='approveOrDissaprove' name='Store decision' 
          activiti:expression="${loanRequest.setApproved(approvedByManager)}" />
        <sequenceFlow id='flow4' sourceRef='approveOrDissaprove' targetRef='exclusiveGw' />
        
        <exclusiveGateway id="exclusiveGw" name="Exclusive Gateway approval" /> 
        <sequenceFlow id="endFlow1" sourceRef="exclusiveGw" targetRef="theEnd">
          <conditionExpression xsi:type="tFormalExpression">${loanRequest.approved}</conditionExpression>
        </sequenceFlow>
        <sequenceFlow id="endFlow2" sourceRef="exclusiveGw" targetRef="sendRejectionLetter">
          <conditionExpression xsi:type="tFormalExpression">${!loanRequest.approved}</conditionExpression>
        </sequenceFlow>
        
        <userTask id="sendRejectionLetter" name="Send rejection letter" />
        <sequenceFlow id='flow5' sourceRef='sendRejectionLetter' targetRef='theOtherEnd' />
        
        <endEvent id='theEnd' />
        <endEvent id='theOtherEnd' />
      </process>
    
    </definitions>
    
            

    Although the example above is quite simple, it shows the power of using JPA combined with Spring and parametrized method-expressions. The process requires no custom java-code at all (except for the Spring-bean off course) and speeds up development drastically.

    Chapter 11. History

    History is the component that captures what happened during process execution and stores it permanently. In contrast to the runtime data, the history data will remain present in the DB also after process instances have completed.

    There are 5 history entities:

    • HistoricProcessInstances containing information about current and past process instances.

    • HistoricVariableInstances containing the latest value of a process variable or task variable.

    • HistoricActivityInstances containing information about a single execution of an activity (node in the process).

    • HistoricTaskInstances containing information about current and past (completed and deleted) task instances.

    • HistoricDetails containing various kinds of information related to either a historic process instances, an activity instance or a task instance.

    Since the DB contains historic entities for past as well as ongoing instances, you might want to consider querying these tables in order to minimize access to the runtime process instance data and that way keeping the runtime execution performant.

    Later on, this information will be exposed in Activiti Explorer. Also, it will be the information from which the reports will be generated.

    Querying history

    In the API, it's possible to query all 5 of the History entities. The HistoryService exposes the the methods createHistoricProcessInstanceQuery(), createHistoricVariableInstanceQuery(), createHistoricActivityInstanceQuery(), createHistoricDetailQuery() and createHistoricTaskInstanceQuery().

    Below are a couple of examples that show some of the possibilities of the query API for history. Full description of the possibilities can be found in the the javadocs, in the org.activiti.engine.history package.

    HistoricProcessInstanceQuery

    Get 10 HistoricProcessInstances that are finished and which took the most time to complete (the longest duration) of all finished processes with definition 'XXX'.

    historyService.createHistoricProcessInstanceQuery()
      .finished()
      .processDefinitionId("XXX")
      .orderByProcessInstanceDuration().desc()
      .listPage(0, 10);

    HistoricVariableInstanceQuery

    Get all HistoricVariableInstances from a finished process instance with id 'xxx' ordered by variable name.

    historyService.createHistoricVariableInstanceQuery()
      .processInstanceId("XXX")
      .orderByVariableName.desc()
      .list();

    HistoricActivityInstanceQuery

    Get the last HistoricActivityInstance of type 'serviceTask' that has been finished in any process that uses the processDefinition with id XXX.

    historyService.createHistoricActivityInstanceQuery()
      .activityType("serviceTask")
      .processDefinitionId("XXX")
      .finished()
      .orderByHistoricActivityInstanceEndTime().desc()
      .listPage(0, 1);

    HistoricDetailQuery

    The next example, gets all variable-updates that have been done in process with id 123. Only HistoricVariableUpdates will be returned by this query. Note that it's possible that a certain variable name has multiple HistoricVariableUpdate entries, for each time the variable was updated in the process. You can use orderByTime (the time the variable update was done) or orderByVariableRevision (revision of runtime variable at the time of updating) to find out in what order they occurred.

    historyService.createHistoricDetailQuery()
      .variableUpdates()
      .processInstanceId("123")
      .orderByVariableName().asc()
      .list()

    This example gets all form-properties that were submitted in any task or when starting the process with id "123". Only HistoricFormPropertiess will be returned by this query.

    historyService.createHistoricDetailQuery()
      .formProperties()
      .processInstanceId("123")
      .orderByVariableName().asc()
      .list()

    The last example gets all variable updates that were performed on the task with id "123". This returns all HistoricVariableUpdates for variables that were set on the task (task local variables), and NOT on the process instance.

    historyService.createHistoricDetailQuery()
      .variableUpdates()
      .taskId("123")
      .orderByVariableName().asc()
      .list()
      

    Task local variables can be set using the TaskService or on a DelegateTask, inside TaskListener:

    taskService.setVariableLocal("123", "myVariable", "Variable value");

    public void notify(DelegateTask delegateTask) {
      delegateTask.setVariableLocal("myVariable", "Variable value");
    }

    HistoricTaskInstanceQuery

    Get 10 HistoricTaskInstances that are finished and which took the most time to complete (the longest duration) of all tasks.

    historyService.createHistoricTaskInstanceQuery()
      .finished()
      .orderByHistoricTaskInstanceDuration().desc()
      .listPage(0, 10);

    Get HistoricTaskInstances that are deleted with a delete reason that contains "invalid", which were last assigned to user 'kermit'.

    historyService.createHistoricTaskInstanceQuery()
      .finished()
      .taskDeleteReasonLike("%invalid%")
      .taskAssignee("kermit")
      .listPage(0, 10);

    History configuration

    The history level can be configured programmatically, using the enum org.activiti.engine.impl.history.HistoryLevel (or HISTORY_*constants defined on ProcessEngineConfiguration for versions prior to 5.11):

    ProcessEngine processEngine = ProcessEngineConfiguration
      .createProcessEngineConfigurationFromResourceDefault()
      .setHistory(HistoryLevel.AUDIT.getKey())
      .buildProcessEngine();
          

    The level can also be configured in activiti.cfg.xml or in a spring-context:

    <bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration">
      <property name="history" value="audit" />
      ...
    </bean>

    Following history levels can be configured:

    • none: skips all history archiving. This is the most performant for runtime process execution, but no historical information will be available.

    • activity: archives all process instances and activity instances. At the end of the process instance, the latest values of the top level process instance variables will be copied to historic variable instances. No details will be archived.

    • audit: This is the default. It archives all process instances, activity instances, keeps variable values continuously in sync and all form properties that are submitted so that all user interaction through forms is traceable and can be audited.

    • full: This is the highest level of history archiving and hence the slowest. This level stores all information as in the audit level plus all other possible details, mostly this are process variable updates.

    Prior to Activiti 5.11, the history level was stored in the database (table ACT_GE_PROPERTY, property with name historyLevel). Starting from 5.11, this value is not used anymore and is ignored/deleted from the database. The history can now be changed between 2 boots of the engine, without an exception being thrown in case the level changed from the previous engine-boot.

    History for audit purposes

    When configuring at least audit level for configuration. Then all properties submitted through methods FormService.submitStartFormData(String processDefinitionId, Map<String, String> properties) and FormService.submitTaskFormData(String taskId, Map<String, String> properties) are recorded.

    Form properties can be retrieved with the query API like this:

    historyService
          .createHistoricDetailQuery()
          .formProperties()
          ...
          .list();

    In that case only historic details of type HistoricFormProperty are returned.

    If you've set the authenticated user before calling the submit methods with IdentityService.setAuthenticatedUserId(String) then that authenticated user who submitted the form will be accessible in the history as well with HistoricProcessInstance.getStartUserId() for start forms and HistoricActivityInstance.getAssignee() for task forms.

    Chapter 12. Eclipse Designer

    Activiti comes with an Eclipse plugin, the Activiti Eclipse Designer, that can be used to graphically model, test and deploy BPMN 2.0 processes.

    Installation

    The following installation instructions are verified on Eclipse Indigo. Note that Eclipse Helio is NOT supported.

    Go to Help -> Install New Software. In the following panel, click on Add button and fill in the following fields:

    • Name: Activiti BPMN 2.0 designer

    • Location: http://activiti.org/designer/update/

    Make sure the "Contact all updates sites.." checkbox is checked, because all the necessary plugins will then be downloaded by Eclipse.

    Activiti Designer editor features

    • Create Activiti projects and diagrams.

    • The Activiti Designer creates a .bpmn file when creating a new Activiti diagram. When opened with the Activiti Diagram Editor view this will provide a graphical modeling canvas and palette. The same file can however be opened with an XML editor and it then shows the BPMN 2.0 XML elements of the process definition. So the Activiti Designer works with only one file for both the graphical diagram as well as the BPMN 2.0 XML. Note that in Activiti 5.9 the .bpmn extension is not yet supported as deployment artifact for a process definition. Therefore the "create deployment artifacts" feature of the Activiti Designer generates a BAR file with a .bpmn20.xml file that contains the content of the .bpmn file. You can also do a quick file rename yourself. Also note that you can open a .bpmn20.xml file with the Activiti Diagram Editor view as well.

    • BPMN 2.0 XML files can be imported into the Activiti Designer and a diagram will be created. Just copy the BPMN 2.0 XML file to your project and open the file with the Activiti Diagram Editor view. The Activiti Designer uses the BPMN DI information of the file to create the diagram. If you have a BPMN 2.0 XML file without BPMN DI information, no diagram can be created.

    • For deployment a BAR file and optionally a JAR file is created by the Activiti Designer by right-clicking on an Activiti project in the package explorer and choosing the Create deployment artifacts option at the bottom of the popup menu. For more information about the deployment functionality of the Designer look a the deployment section.

    • Generate a unit test (right click on a BPMN 2.0 XML file in the package explorer and select generate unit test) A unit test is generated with an Activiti configuration that runs on an embedded H2 database. You can now run the unit test to test your process definition.

    • The Activiti project is generated as a Maven project. To configure the dependencies you need to run mvn eclipse:eclipse and the Maven dependencies will be configured as expected. Note that for process design Maven dependencies are not needed. They are only needed to run unit tests.

    Activiti Designer BPMN features

    • Support for start none event, start error event, timer start event, end none event, end error event, sequence flow, parallel gateway, exclusive gateway, inclusive gateway, event gateway, embedded subprocess, event sub process, call activity, pool, lane, script task, user task, service task, mail task, manual task, business rule task, receive task, timer boundary event, error boundary event, signal boundary event, timer catching event, signal catching event, signal throwing event, none throwing event and four Alfresco specific elements (user, script, mail tasks and start event).

    • You can quickly change the type of a task by hovering over the element and choosing the new task type.

    • You can quickly add new elements hovering over an element and choosing a new element type.

    • Java class, expression or delegate expression configuration is supported for the Java service task. In addition field extensions can be configured.

    • Support for pools and lanes. Because Activiti reads different pools as different process definition, it makes the most sense to use only one pool. If you use multiple pools, be aware that drawing sequence flows between the pools will result in problems when deploying the process in the Activiti Engine. You can add as much lanes to a pool as you want.

    • You can add labels to sequence flows by filling the name property. You can position the labels yourself as the position is saved as part of the BPMN 2.0 XML DI information.

    • Support for event sub processes.

    • Support for expanded embedded sub processes. You can also add an embedded sub process in another embedded sub process.

    • Support for timer boundary events on tasks and embedded sub processes. Although, the timer boundary event makes the most sense when using it on a user task or an embedded sub process in the Activiti Designer.

    • Support for additional Activiti extensions like the Mail task, the candidate configuration of User tasks and Script task configuration.

    • Support for the Activiti execution and task listeners. You can also add field extensions for execution listeners.

    • Support for conditions on sequence flows.

    Activiti Designer deployment features

    Deploying process definitions and task forms on the Activiti Engine is not hard. You need a BAR file containing the process definition BPMN 2.0 XML file and optionally task forms and an image of the process that can be viewed in the Activiti Explorer. In the Activiti Designer it's made very easy to create a BAR file. When you've finished your process implementation just right-click on your Activiti project in the package explorer and choose for the Create deployment artifacts option at the bottom of the popup menu.

    Then a deployment directory is created containing the BAR file and optionally a JAR file with the Java classes of your Activiti project.

    This file can now be uploaded to the Activiti Engine using the deployments tab in Activiti Explorer, and you are ready to go.

    When your project contains Java classes, the deployment is a bit more work. In that case the Create deployment artifacts step in the Activiti Designer will also generate a JAR file containing the compiled classes. This JAR file must be deployed to the activiti-XXX/WEB-INF/lib directory in your Activiti Tomcat installation directory. This makes the classes available on the classpath of the Activiti Engine.

    Extending Activiti Designer

    You can extend the default functionality offered by Activiti Designer. This section documents which extensions are available, how they can be used and provides some usage examples. Extending Activiti Designer is useful in cases where the default functionality doesn't suit your needs, you require additional capabilities or have domain specific requirements when modeling business processes. Extension of Activiti Designer falls into two distinct categories, extending the palette and extending output formats. Each of these extension ways requires a specific approach and different technical expertise.

    Note

    Extending Activiti Designer requires technical knowledge and more specifically, knowledge of programming in Java. Depending on the type of extension you want to create, you might also need to be familiar with Maven, Eclipse, OSGi, Eclipse extensions and SWT.

    Customizing the palette

    You can customize the palette that is offered to users when modeling processes. The palette is the collection of shapes that can be dragged onto the canvas in a process diagram and is displayed to the right hand side of the canvas. As you can see in the default palette, the default shapes are grouped into compartments (these are called "drawers") for Events, Gateways and so on. There are two options built-in to Activiti Designer to customize the drawers and shapes in the palette:

    • Adding your own shapes / nodes to existing or new drawers

    • Disabling any or all of the default BPMN 2.0 shapes offered by Activiti Designer, with the exception of the connection and selection tools

    In order to customize the palette, you create a JAR file that is added to a specific installation of Activiti Designer (more on how to do that later). Such a JAR file is called an extension. By writing classes that are included in your extension, Activiti Designer understands which customizations you wish to make. In order for this to work, your classes should implement certain interfaces. There is an integration library available with those interfaces and base classes to extend which you should add to your project's classpath.

    You can find the code examples listed below in source control with Activiti Designer. Take a look in the examples/money-tasks directory in the projects/designer directory of Activiti's source code.

    Note

    You can setup your project in whichever tool you prefer and build the JAR with your build tool of choice. For the instructions below, a setup is assumed with Eclipse Helios, using Maven (3.x) as build tool, but any setup should enable you to create the same results.

    Extension setup (Eclipse/Maven)

    Download and extract Eclipse (most recent versions should work) and a recent version (3.x) of Apache Maven. If you use a 2.x version of Maven, you will run into problems when building your project, so make sure your version is up to date. We assume you are familiar with using basic features and the Java editor in Eclipse. It's up to you whether your prefer to use Eclipse's features for Maven or run Maven commands from a command prompt.

    Create a new project in Eclipse. This can be a general project type. Create a pom.xml file at the root of the project to contain the Maven project setup. Also create folders for the src/main/java and src/main/resources folders, which are Maven conventions for your Java source files and resources respectively. Open the pom.xml file and add the following lines:

    <project 
      xmlns="http://maven.apache.org/POM/4.0.0" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    
      <modelVersion>4.0.0</modelVersion>
    
      <groupId>org.acme</groupId>
      <artifactId>money-tasks</artifactId>
      <version>1.0.0</version>
      <packaging>jar</packaging>
      <name>Acme Corporation Money Tasks</name>
    ...
    </project>

    As you can see, this is just a basic pom.xml file that defines a groupId, artifactId and version for the project. We will create a customization that includes a single custom node for our money business.

    Add the integration library to your project's dependencies by including this dependency in your pom.xml file:

    <dependencies>
      <dependency>
        <groupId>org.activiti.designer</groupId>
        <artifactId>org.activiti.designer.integration</artifactId>
        <version>5.12.0</version> <!-- Use the current Activiti Designer version -->
        <scope>compile</scope>
      </dependency>
    </dependencies>
    ...
    <repositories>
      <repository>
          <id>Activiti</id>
          <url>https://maven.alfresco.com/nexus/content/groups/public/</url>
       </repository>
    </repositories>

    Finally, in the pom.xml file, add the configuration for the maven-compiler-plugin so the Java source level is at least 1.5 (see snippet below). You will need this in order to use annotations. You can also include instructions for Maven to generate the JAR's MANIFEST.MF file. This is not required, but you can use a specific property in the manifest to provide a name for your extension (this name may be shown at certain places in the designer and is primarily intended for future use if you have several extensions in the designer). If you wish to do so, include the following snippet in pom.xml:

    <build>
      <plugins>
            <plugin>
          <artifactId>maven-compiler-plugin</artifactId>
          <configuration>
            <source>1.5</source>
            <target>1.5</target>
            <showDeprecation>true</showDeprecation>
            <showWarnings>true</showWarnings>
            <optimize>true</optimize>
          </configuration>
        </plugin>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-jar-plugin</artifactId>
          <version>2.3.1</version>
          <configuration>
            <archive>
              <index>true</index>
              <manifest>
                <addClasspath>false</addClasspath>
                <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
              </manifest>
              <manifestEntries>
                <ActivitiDesigner-Extension-Name>Acme Money</ActivitiDesigner-Extension-Name>
              </manifestEntries>
            </archive>
          </configuration>
        </plugin>
      </plugins>
    </build>

    The name for the extension is described by the ActivitiDesigner-Extension-Name property. The only thing left to do now is tell Eclipse to setup the project according to the instructions in pom.xml. So open up a command shell and go to the root folder of your project in the Eclipse workspace. Then execute the following Maven command:

    mvn eclipse:eclipse

    Wait until the build is successful. Refresh the project (use the project's context menu (right-click) and select Refresh). You should now have the src/main/java and src/main/resources folders as source folders in the Eclipse project.

    Note

    You can of course also use the m2eclipse plugin and simply enable Maven dependency management from the context menu (right-click) of the project. Then choose Maven > Update project configuration from the project's context menu. That should setup the source folders as well.

    That's it for the setup. Now you're ready to start creating customizations to Activiti Designer!

    Applying your extension to Activiti Designer

    You might be wondering how you can add your extension to Activiti Designer so your customizations are applied. These are the steps to do just that:

    • Once you've created your extension JAR (for instance, by performing a mvn install in your project to build it with Maven), you need to transfer the extension to the computer where Activiti Designer is installed;

    • Store the extension somewhere on the hard drive where it will be able to remain and remember the location. Note: the location must be outside the Eclipse workspace of Activiti Designer - storing the extension inside the workspace will lead to the user getting a popup error message and the extensions being unavailable;

    • Start Activiti Designer and from the menu, select Window > Preferences

    • In the preferences screen, type user as keyword. You should see an option to access the User Libraries in Eclipse in the Java section.

    • Select the User Libraries item and a tree view shows up to the right where you can add libraries. You should see the default group where you can add extensions to Activiti Designer (depending on your Eclipse installation, you might see several others as well).

    • Select the Activiti Designer Extensions group and click the Add JARs... button. Navigate to to folder where your extension is stored and select the extension file you want to add. After completing this, your preferences screen should show the extension as part of the Activiti Designer Extensions group, as shown below.

    • Click the OK button to save and close the preferences dialog. The Activiti Designer Extensions group is automatically added to new Activiti projects you create. You can see the user library as entry in the project's tree in the Navigator or Package Explorer. If you already had Activiti projects in the workspace, you should also see the new extensions show up in the group. An example is shown below.

    Diagrams you open will now have the shapes from the new extension in their palette (or shapes disabled, depending on the customizations in your extension). If you already had a diagram opened, close and reopen it to see the changes in the palette.

    Adding shapes to the palette

    With your project set up, you can now easily add shapes to the palette. Each shape you wish to add is represented by a class in your JAR. Take note that these classes are not the classes that will be used by the Activiti engine during runtime. In your extension you describe the properties that can be set in Activiti Designer for each shape. From these shapes, you can also define the runtime characteristics that should be used by the engine when a process instance reaches the node in the process. The runtime characteristics can use any of the options that Activiti supports for regular ServiceTasks. See this section for more details.

    A shape's class is a simple Java class, to which a number of annotations are added. The class should implement the CustomServiceTask interface, but you shouldn't implement this interface yourself. Extend the AbstractCustomServiceTask base class instead (at the moment you MUST extend this class directly, so no abstract classes in between). In the Javadoc for that class you can find instructions on the defaults it provides and when you should override any of the methods it already implements. Overrides allow you to do things such as providing icons for the palette and in the shape on the canvas (these can be different) and specifying the base shape you want the node to have (activity, event, gateway).

    /**
     * @author John Doe
     * @version 1
     * @since 1.0.0
     */
    public class AcmeMoneyTask extends AbstractCustomServiceTask {
    ...
    }

    You will need to implement the getName() method to determine the name the node will have in the palette. You can also put the nodes in their own drawer and provide an icon. Override the appropriate methods from AbstractCustomServiceTask. If you want to provide an icon, make sure it's in the src/main/resources package in your JAR and is about 16x16 pixels and a JPEG or PNG format. The path you supply is relative to that folder.

    You can add properties to the shape by adding members to the class and annotating them with the @Property annotation like this:

    @Property(type = PropertyType.TEXT, displayName = "Account Number")
    @Help(displayHelpShort = "Provide an account number", displayHelpLong = HELP_ACCOUNT_NUMBER_LONG)
    private String accountNumber;

    There are several PropertyType values you can use, which are described in more detail in this section. You can make a field required by setting the required attribute to true. A message and red background will appear if the user doesn't fill out the field.

    If you want to ensure the order of the various properties in your class as they appear in the property screen, you should specify the order attribute of the @Property annotation.

    As you can see, there's also an @Help annotation that's used to provide the user some guidance when filling out the field. You can also use the @Help annotation on the class itself - this information is shown at the top of the property sheet presented to the user.

    Below is the listing for a further elaboration of the MoneyTask. A comment field has been added and you can see an icon is included for the node.

    /**
     * @author John Doe
     * @version 1
     * @since 1.0.0
     */
    @Runtime(javaDelegateClass = "org.acme.runtime.AcmeMoneyJavaDelegation")
    @Help(displayHelpShort = "Creates a new account", displayHelpLong = "Creates a new account using the account number specified")
    public class AcmeMoneyTask extends AbstractCustomServiceTask {
    
      private static final String HELP_ACCOUNT_NUMBER_LONG = "Provide a number that is suitable as an account number.";
    
      @Property(type = PropertyType.TEXT, displayName = "Account Number", required = true)
      @Help(displayHelpShort = "Provide an account number", displayHelpLong = HELP_ACCOUNT_NUMBER_LONG)
      private String accountNumber;
    
      @Property(type = PropertyType.MULTILINE_TEXT, displayName = "Comments")
      @Help(displayHelpShort = "Provide comments", displayHelpLong = "You can add comments to the node to provide a brief description.")
      private String comments;
    
      /*
       * (non-Javadoc)
       * 
       * @see org.activiti.designer.integration.servicetask.AbstractCustomServiceTask #contributeToPaletteDrawer()
       */
      @Override
      public String contributeToPaletteDrawer() {
        return "Acme Corporation";
      }
    
      @Override
      public String getName() {
        return "Money node";
      }
    
      /*
       * (non-Javadoc)
       * 
       * @see org.activiti.designer.integration.servicetask.AbstractCustomServiceTask #getSmallIconPath()
       */
      @Override
      public String getSmallIconPath() {
        return "icons/coins.png";
      }
    }

    If you extend Activiti Designer with this shape, The palette and corresponding node will look like this:

    The properties screen for the money task is shown below. Note the required message for the accountNumber field.

    Users can enter static text or use expressions that use process variables in the property fields when creating diagrams (e.g. "This little piggy went to ${piggyLocation}"). Generally, this applies to text fields where users are free to enter any text. If you expect users to want to use expressions and you apply runtime behavior to your CustomServiceTask (using @Runtime), make sure to use Expression fields in the delegate class so the expressions are correctly resolved at runtime. More information on runtime behavior can be found in this section.

    The help for fields is offered by the buttons to the right of each property. Clicking on the button shows a popup as displayed below.

    Configuring runtime execution of Custom Service Tasks

    With your fields setup and your extension applied to Designer, users can configure the properties of the service task when modelling a process. In most cases, you will want to use these user-configured properties when the process is executed by Activiti. To do this, you must instruct Activiti which class to instantiate when the process reaches your CustomServiceTask.

    There is a special annotation for specifying the runtime characteristics of your CustomServiceTask, the @Runtime annotation. Here's an example of how to use it:

    @Runtime(javaDelegateClass = "org.acme.runtime.AcmeMoneyJavaDelegation")

    Your CustomServiceTask will result in a normal ServiceTask in the BPMN output of processes modelled with it. Activiti enables several ways to define the runtime characteristics of ServiceTasks. Therefore, the @Runtime annotation can take one of three attributes, which match directly to the options Activiti provides, like this:

    • javaDelegateClass maps to activiti:class in the BPMN output. Specify the fully qualified classname of a class that implements JavaDelegate.

    • expression maps to activiti:expression in the BPMN output. Specify an expression to a method to be executed, such as a method in a Spring Bean. You should not specify any @Property annotations on fields when using this option. For more information, see below.

    • javaDelegateExpression maps to activiti:delegateExpression in the BPMN output. Specify an expression to a class that implements JavaDelegate.

    The user's property values will be injected into the runtime class if you provide members in the class for Activiti to inject into. The names should match the names of the members in your CustomServiceTask. For more information, consult this part of the userguide. Note that since version 5.11.0 of the Designer you can use the Expression interface for dynamic field values. This means that the value of the property in the Activiti Designer must contain an expression and this expression will then be injected into an Expression property in the JavaDelegate implementation class.

    Note

    You can use @Property annotations on members of your CustomServiceTask, but this will not work if you use @Runtime's expression attribute. The reason for this is that the expression you specify will be attempted to be resolved to a method by Activiti, not to a class. Therefore, no injection into a class will be performed. Any members marked with @Property will be ignored by Designer if you use expression in your @Runtime annotation. Designer will not render them as editable fields in the node's property pane and will produce no output for the properties in the process' BPMN.

    Note

    Note that the runtime class shouldn't be in your extension JAR, as it's dependent on the Activiti libraries. Activiti needs to be able to find it at runtime, so it needs to be on the Activiti engine's classpath.

    The examples project in Designer's source tree contains examples of the different options for configuring @Runtime. Take a look in the money-tasks project for some starting points. The examples refer to delegate class examples that are in the money-delegates project.

    Property types

    This section describes the property types you can use for a CustomServiceTask by setting its type to a PropertyType value.

    PropertyType.TEXT

    Creates a single line text field as shown below. Can be a required field and shows validation messages as a tooltip. Validation failures are displayed by changing the background of the field to a light red color.

    PropertyType.MULTILINE_TEXT

    Creates a multiline text field as shown below (height is fixed at 80 pixels). Can be a required field and shows validation messages as a tooltip. Validation failures are displayed by changing the background of the field to a light red color.

    PropertyType.PERIOD

    Creates a structured editor for specifying a period of time by editing amounts of each unit with a spinner control. The result is shown below. Can be a required field (which is interpreted such that not all values may be 0, so at least 1 part of the period must have a non-zero value) and shows validation messages as a tooltip. Validation failures are displayed by changing the background of the entire field to a light red color. The value of the field is stored as a string of the form 1y 2mo 3w 4d 5h 6m 7s, which represents 1 year, 2 months, 3 weeks, 4 days, 6 minutes and 7 seconds. The entire string is always stored, even if parts are 0.

    PropertyType.BOOLEAN_CHOICE

    Creates a single checkbox control for boolean or toggle choices. Note that you can specify the required attribute on the Property annotation, but it will not be evaluated because that would leave the user without a choice whether to check the box or not. The value stored in the diagram is java.lang.Boolean.toString(boolean), which results in "true" or "false".

    PropertyType.RADIO_CHOICE

    Creates a group of radio buttons as shown below. Selection of any of the radio buttons is mutually exclusive with selection of any of the others (i.e., only one selection allowed). Can be a required field and shows validation messages as a tooltip. Validation failures are displayed by changing the background of the group to a light red color.

    This property type expects the class member you have annotated to also have an accompanying @PropertyItems annotation (for an example, see below). Using this additional annotation, you can specify the list of items that should be offered in an array of Strings. Specify the items by adding two array entries for each item: first, the label to be shown; second, the value to be stored.

    @Property(type = PropertyType.RADIO_CHOICE, displayName = "Withdrawl limit", required = true)
    @Help(displayHelpShort = "The maximum daily withdrawl amount ", displayHelpLong = "Choose the maximum daily amount that can be withdrawn from the account.")
    @PropertyItems({ LIMIT_LOW_LABEL, LIMIT_LOW_VALUE, LIMIT_MEDIUM_LABEL, LIMIT_MEDIUM_VALUE, LIMIT_HIGH_LABEL, LIMIT_HIGH_VALUE })
    private String withdrawlLimit;

    PropertyType.COMBOBOX_CHOICE

    Creates a combobox with fixed options as shown below. Can be a required field and shows validation messages as a tooltip. Validation failures are displayed by changing the background of the combobox to a light red color.

    This property type expects the class member you have annotated to also have an accompanying @PropertyItems annotation (for an example, see below). Using this additional annotation, you can specify the list of items that should be offered in an array of Strings. Specify the items by adding two array entries for each item: first, the label to be shown; second, the value to be stored.

    @Property(type = PropertyType.COMBOBOX_CHOICE, displayName = "Account type", required = true)
    @Help(displayHelpShort = "The type of account", displayHelpLong = "Choose a type of account from the list of options")
    @PropertyItems({ ACCOUNT_TYPE_SAVINGS_LABEL, ACCOUNT_TYPE_SAVINGS_VALUE, ACCOUNT_TYPE_JUNIOR_LABEL, ACCOUNT_TYPE_JUNIOR_VALUE, ACCOUNT_TYPE_JOINT_LABEL,
      ACCOUNT_TYPE_JOINT_VALUE, ACCOUNT_TYPE_TRANSACTIONAL_LABEL, ACCOUNT_TYPE_TRANSACTIONAL_VALUE, ACCOUNT_TYPE_STUDENT_LABEL, ACCOUNT_TYPE_STUDENT_VALUE,
      ACCOUNT_TYPE_SENIOR_LABEL, ACCOUNT_TYPE_SENIOR_VALUE })
    private String accountType;

    PropertyType.DATE_PICKER

    Creates a date selection control as shown below. Can be a required field and shows validation messages as a tooltip (note, that the control used will auto-set the selection to the date on the system, so the value is seldom empty). Validation failures are displayed by changing the background of the control to a light red color.

    This property type expects the class member you have annotated to also have an accompanying @DatePickerProperty annotation (for an example, see below). Using this additional annotation, you can specify the date time pattern to be used to store dates in the diagram and the type of datepicker you would like to be shown. Both attributes are optional and have default values that will be used if you don't specify them (these are static variables in the DatePickerProperty annotation). The dateTimePattern attribute should be used to supply a pattern to the SimpleDateFormat class. When using the swtStyle attribute, you should specify an integer value that is supported by SWT's DateTime control, because this is the control that is used to render this type of property.

    @Property(type = PropertyType.DATE_PICKER, displayName = "Expiry date", required = true)
    @Help(displayHelpShort = "The date the account expires ", displayHelpLong = "Choose the date when the account will expire if no extended before the date.")
    @DatePickerProperty(dateTimePattern = "MM-dd-yyyy", swtStyle = 32)
    private String expiryDate;

    PropertyType.DATA_GRID

    Creates a data grid control as shown below. A data grid can be used to allow the user to enter an arbitrary amount of rows of data and enter values for a fixed set of columns in each of those rows (each individual combination of row and column is referred to as a cell). Rows can be added and removed as the user sees fit.

    This property type expects the class member you have annotated to also have an accompanying @DataGridProperty annotation (for an example, see below). Using this additional annotation, you can specify some specific attributes of the data grid. You are required to reference a different class to determine which columns go into the grid with the itemClass attribute. Activiti Designer expects the member type to be a List. By convention, you can use the class of the itemClass attribute as its generic type. If, for example, you have a grocery list that you edit in the grid, you would define the columns of the grid in the GroceryListItem class. From your CustomServiceTask, you would refer to it like this:

    @Property(type = PropertyType.DATA_GRID, displayName = "Grocery List")
    @DataGridProperty(itemClass = GroceryListItem.class)
    private List<GroceryListItem> groceryList;

    The "itemClass" class uses the same annotations you would otherwise use to specify fields of a CustomServiceTask, with the exception of using a data grid. Specifically, TEXT, MULTILINE_TEXT and PERIOD are currently supported. You'll notice the grid will create single line text controls for each field, regardless of the PropertyType. This is done on purpose to keep the grid graphically appealing and readable. If you consider the regular display mode for a PERIOD PropertyType for instance, you can imagine it would never properly fit in a grid cell without cluttering the screen. For MULTILINE_TEXT and PERIOD, a double-click mechanism is added to each field which pops up a larger editor for the PropertyType. The value is stored to the field after the user clicks OK and is therefore readable within the grid.

    Required attributes are handled in a similar manner to regular fields of type TEXT and the entire grid is validated as soon as any field loses focus. The background color of the text control in a specific cell of the data grid is changed to light red if there are validation failures.

    By default, the component allows the user to add rows, but not to determine the order of those rows. If you wish to allow this, you should set the orderable attribute to true, which enables buttons at the end of each row to move it up or down in the grid.

    Note

    At the moment, this property type is not correctly injected into your runtime class.

    Disabling default shapes in the palette

    This customization requires you to include a class in your extension that implements the DefaultPaletteCustomizer interface. You should not implement this interface directly, but subclass the AbstractDefaultPaletteCustomizer base class. Currently, this class provides no functionality, but future versions of the DefaultPaletteCustomizer interface will offer more capabilities for which this base class will provide some sensible defaults so it's best to subclass so your extension will be compatible with future releases.

    Extending the AbstractDefaultPaletteCustomizer class requires you to implement one method, disablePaletteEntries(), from which you must return a list of PaletteEntry values. For each of the default shapes, you can disable it by adding its corresponding PaletteEntry value to your list. Note that if you remove shapes from the default set and there are no remaining shapes in a particular drawer, that drawer will be removed from the palette in its entirety. If you wish to disable all of the default shapes, you only need to add PaletteEntry.ALL to your result. As an example, the code below disables the Manual task and Script task shapes in the palette.

    public class MyPaletteCustomizer extends AbstractDefaultPaletteCustomizer {
    
      /*
       * (non-Javadoc)
       *
       * @see org.activiti.designer.integration.palette.DefaultPaletteCustomizer#disablePaletteEntries()
       */
      @Override
      public List<PaletteEntry> disablePaletteEntries() {
        List<PaletteEntry> result = new ArrayList<PaletteEntry>();
        result.add(PaletteEntry.MANUAL_TASK);
        result.add(PaletteEntry.SCRIPT_TASK);
        return result;
      }
    
    }

    The result of applying this extension is shown in the picture below. As you can see, the manual task and script task shapes are no longer available in the Tasks drawer.

    To disable all of the default shapes, you could use something similar to the code below.

    public class MyPaletteCustomizer extends AbstractDefaultPaletteCustomizer {
    
      /*
       * (non-Javadoc)
       *
       * @see org.activiti.designer.integration.palette.DefaultPaletteCustomizer#disablePaletteEntries()
       */
      @Override
      public List<PaletteEntry> disablePaletteEntries() {
        List<PaletteEntry> result = new ArrayList<PaletteEntry>();
        result.add(PaletteEntry.ALL);
        return result;
      }
    
    }

    The result will look like this (notice that the drawers the default shapes were in are no longer in the palette):

    Validating diagrams and exporting to custom output formats

    Besides customizing the palette, you can also create extensions to Activiti Designer that can perform validations and save information from the diagram to custom resources in the Eclipse workspace. There are built-in extension points for doing this and this section explains how to use them.

    Note

    The ExportMarshaller functions were reintroduced recently. We are still working on the validation functionality. The documentation below details the old situation and will be updated when the new functionality is available.

    Activiti Designer allows you to write extensions that validate diagrams. There are already validations of BPMN constructs in the tool by default, but you can add your own if you want to validate additional items such as modeling conventions or the values in properties of CustomServiceTasks. These extensions are known as Process Validators.

    You can also Activiti Designer to publish to additional formats when saving diagrams. These extensions are called Export Marshallers and are invoked automatically by Activiti Designer on each save action by the user. This behavior can be enabled or disabled by setting a preference in Eclipse's preferences dialog for each format for which there is an extension detected. Designer will make sure your ExportMarshaller is invoked when saving the diagram, depending on the user's preference.

    Often, you will want to combine a ProcessValidator and an ExportMarshaller. Let's say you have a number of CustomServiceTasks in use that have properties you would like to use in the process that gets generated. However, before the process is generated, you want to validate some of those values first. Combining a ProcessValidator and ExportMarshaller is the best way to accomplish this and Activiti Designer enables you to plug your extensions into the tool seamlessly.

    To create a ProcessValidator or an ExportMarshaller, you need to create a different kind of extension than for extending the palette. The reason for this is simple: from your code you will need access to more APIs than those that are offered by the integration library. In particular, you will need classes that are available in Eclipse itself. So to get started, you should create an Eclipse plugin (which you can do by using Eclipse's PDE support) and package it in a custom Eclipse product or feature. It's beyond the scope of this user guide to explain all the details involved in developing Eclipse plugins, so the instructions below are limited to the functionality for extending Activiti Designer.

    Your bundle should be dependent on the following libraries:

    • org.eclipse.core.runtime
    • org.eclipse.core.resources
    • org.activiti.designer.eclipse
    • org.activiti.designer.libs
    • org.activiti.designer.util

    Optionally, the org.apache.commons.lang bundle is available through Designer if you'd like to use that in your extension.

    Both ProcessValidators and ExportMarshallers are created by extending a base class. These base classes inherit some useful methods from their superclass, the AbstractDiagramWorker class. Using these methods you can create information, warning and error markers that show up in Eclipse's problems view for the user to figure out what's wrong or important. You can get to information about the diagram in the form of Resources and InputStreams. This information is provided from the DiagramWorkerContext, which is available from the AbstractDiagramWorker class.

    It's probably a good idea to invoke clearMarkers() as one of the first things you do in either a ProcessValidator or an ExportMarshaller; this will clear any previous markers for your worker (markers are automatically linked to the worker and clearing markers for one worker leaves other markers untouched). For example:

    // Clear markers for this diagram first
    clearMarkersForDiagram();

    You should also use the progress monitor provided (in the DiagramWorkerContext) to report your progress back to the user because validations and/or marshalling actions can take up some time during which the user is forced to wait. Reporting progress requires some knowledge of how you should use Eclipse's features. Take a look at this article for a thorough explanation of the concepts and usage.

    Creating a ProcessValidator extension

    Note

    Under review!

    Create an extension to the org.activiti.designer.eclipse.extension.validation.ProcessValidator extension point in your plugin.xml file. For this extension point, you are required to subclass the AbstractProcessValidator class.

    <?eclipse version="3.6"?>
    <plugin>
      <extension
        point="org.activiti.designer.eclipse.extension.validation.ProcessValidator">
        <ProcessValidator
          class="org.acme.validation.AcmeProcessValidator">
        </ProcessValidator>
      </extension>
    </plugin>

    public class AcmeProcessValidator extends AbstractProcessValidator {
    }

    You have to implement a number of methods. Most importantly, implement getValidatorId() so you return a globally unique ID for your validator. This will enable you to invoke it from and ExportMarshaller, or event let someone else invoke your validator from their ExportMarshaller. Implement getValidatorName() and return a logical name for your validator. This name is shown to the user in dialogs. In getFormatName(), you can return the type of diagram the validator typically validates.

    The validation work itself is done in the validateDiagram() method. From this point on, it's up to your specific functionality what you code here. Typically, however, you will want to start by getting hold of the nodes in the diagram's process, so you can iterate through them, collect, compare and validate data. This snippet shows you how to do this:

    final EList<EObject> contents = getResourceForDiagram(diagram).getContents();
    for (final EObject object : contents) {
      if (object instanceof StartEvent ) {
      // Perform some validations for StartEvents
      }
      // Other node types and validations
    }

    Don't forget to invoke addProblemToDiagram() and/or addWarningToDiagram(), etc as you go through your validations. Make sure you return a correct boolean result at the end to indicate whether you consider the validation as succeeded or failed. This can be used by and invoking ExportMarshaller to determine the next course of action.

    Creating an ExportMarshaller extension

    Create an extension to the org.activiti.designer.eclipse.extension.ExportMarshaller extension point in your plugin.xml file. For this extension point, you are required to subclass the AbstractExportMarshaller class. This abstract base class provides you with a number of useful methods when marshalling to your own format, but most importantly it allows you to save resources to the workspace and to invoke validators.

    An example implementation is available in Designer's examples folder. This example shows how to use the methods in the base class to get the basics done, such as accessing the diagram's InputStream, using its BpmnModel and saving resources to the workspace.

    <?eclipse version="3.6"?>
    <plugin>
      <extension
        point="org.activiti.designer.eclipse.extension.ExportMarshaller">
        <ExportMarshaller
          class="org.acme.export.AcmeExportMarshaller">
        </ExportMarshaller>
      </extension>
      </plugin>

    public class AcmeExportMarshaller extends AbstractExportMarshaller {
    }

    You are required to implement some methods, such as getMarshallerName() and getFormatName(). These methods are used to display options to the user and to show information in progress dialogs, so make sure the descriptions you return reflect the functionality you are implementing.

    The bulk of your work is performed in the doMarshallDiagram() method.

    If you want to perform a certain validation first, you can invoke the validator directly from your marshaller. You receive a boolean result from the validator, so you know whether validation succeeded. In most cases you won't want to proceed with marshalling the diagram if it's not valid, but you might choose to go ahead anyway or even create a different resource if validation fails.

    Once you have all the data you need, you should invoke the saveResource() method to create a file containing your data. You can invoke saveResource() as many times as you wish from a single ExportMarshaller; a marshaller can therefore be used to create more than one output file.

    You can construct a filename for your output resource(s) by using the saveResource() method in the AbstractDiagramWorker class. There are a couple of useful variables you can have parsed, allowing you to create filenames such as _original-filename__my-format-name.xml. These variables are described in the Javadocs and defined by the ExportMarshaller interface. You can also use resolvePlaceholders() on a string (e.g. a path) if you want to parse the placeholders yourself. getURIRelativeToDiagram() will invoke this for you.

    You should use the progress monitor provided to report your progress back to the user. How to do this is described in this article.

    Chapter 13. Activiti Explorer

    Activiti Explorer is a web application that is included when you download Activiti from the Activiti website. The purpose of Explorer is not a finished, end-user ready application, but rather to excersise and show the functionality of Activiti. As such, Explorer is meant as a demo, or maybe inspiration for people using Activiti in there own applications. Out of the box, Explorer uses an in-memory database, but it is easy to switch to your own database (see the applicationContext files in the WEB-INF folder).

    After logging into the application, you will see three large icons that show the main capabilities.

    • Tasks: Task management functionality. Here you can see user tasks from running processes that are assigned to you, or see group tasks which you can claim. Explorer allows to relate content, divide work into subtasks, involve people in different roles, etc ... Explorer can also be used to create standalone tasks that are not related to any process.

    • Process: shows the deployed process definitions, and allows to start new process instances.

    • Reporting: generate reports and view previously saved results. See the section on reporting for more details.

    • Manage: only visible when the logged in user has administrator rights. Allows to administrate the Activiti engine: manage users and groups, execute and see stuck jobs, see the database and deploy new process definitions.

    Process diagram

    The Explorer includes functionality to dynamically generate an overview of a process definition using the Raphaël Javascript framework. This process image can only be generated when the process definition XML contains BPMN DI information. When there's no BPMN DI information in the process definition XML and the deployment contains a process definition image, that image will be shown.

    When you don't want to use the Javascript process definition overview you can disable it in the ui.properties file

    activiti.ui.jsdiagram = false

    In addition to showing the process diagram in the Explorer it's also easy to include the process diagram anywhere you want. The following URL will show the process definition image, based on a process definition id:

    http://localhost:8080/activiti-explorer/diagram-viewer/index.html?processDefinitionId=reviewSaledLead:1:36

    It's also possible to show the current state of a process instance by adding a processInstanceId request parameter like this:

    http://localhost:8080/activiti-explorer/diagram-viewer/index.html?processDefinitionId=reviewSaledLead:1:36&processInstanceId=41

    Tasks

    • Inbox: shows the tasks where the logged in user is the assignee.

    • My tasks: shows the tasks where the logged in user is the owner. When you create a standalone task, you are automatically made owner of the task.

    • Queued: shows the different groups which you are part of. Tasks here must first be claimed before they can be completed.

    • Involved: shows the tasks where the logged in user is involved with (i.e. not assignee or owner).

    • Archived contains the past (historical) tasks.

    Start process instances

    The Process definitions tab, allows to see all process definitions that are deployed to the Activiti engine. You can start new process instances using the button on the top right. If the process definition has a start form, the form will be displayed before starting the process instance.

    My instances

    The My instances tab, shows all the process instances where you currently have an uncompleted user task. It also visually shows the current activities of the process instance and the stored process variables.

    Administration

    The administration functionality is only available when the logged in user is part of the security group admin. When clicking the Manage icon, following tabs are available:

    • Database: Shows the content of the database. Extremely useful when developing processes or troubleshooting problems.

    • Deployments: Shows the current deployments of the engine, and see the content of a deployment (process definitions, images, business rules, etc.)

      You can also upload new deployments when clicking the deployment tab. Select a business archive or a bpmn20.xml file from your computer, or simply drag and drop to the designated area to deploy the new business processes.

    • Jobs: Shows the current jobs (timers, etc.) on the left and allows to manually execute them (e.g. firing a timer before the deadline). Also shows any exceptions, if the jobs failed to execute (e.g. mail server could not be reached)

    • Users and Groups: manage the users and groups: create, edit and delete users and groups. Relate users to groups such they have more privileges or they can see tasks assigned to specific groups.

    Reporting

    Activiti Explorer ships with some report examples and has the capability to easily add new reports to the system. The report functionality is grouped under the main tab 'Reports'.

    Important: for reporting to work, Explorer needs to be configured with a history level different from none. The default configuration fulfills this requirement.

    The reporting tab currently shows two sub-tabs:

    • Generate reports: shows a list of all reports known to the system. Allows to run the report generation.

    • Saved reports: shows a list of all reports that were previously saved. Note that these are personal saved reports only, and it is not possible to see the saved reports of someone else.

    The data that is used to create lists and charts in the report is generated by a process. While this may seem odd at first, using a process to generate the report data has several advantages

    • The process has straight access to the internals of the Activiti engine. It has direct access to the database used by the engine.

    • The job executor can be used as for any other process. This means that you can asynchronously generate the process or only execute certain steps asynchronously. It also means you can use timers, eg. to generate the report data on certain points in time.

    • Creating a new report can be done with known tools and known concepts. Also, no new concepts, services or applications are needed. Deploying or uploading a new report is the same as deploying a new process.

    • It allows to use the BPMN 2.0 constructs. This means that all things like parallel steps, do branching based on data or even request user input during the generation are possible out-of-the-box.

    Process definitions that generate report data need to have 'activiti-report' as category to be seen in the list of known reports in Explorer. A 'report process' can be as simple or as complex as wanted. The only requirement to actually be able to see the report, is that the process produces a variable called reportData is created. This variable must be a byte array representation of a json object. This variable is stored in the history tables of Activiti (hence the requirement that history must be enabled for the engine) so it can be retrieved later when the report is saved.

    Report data JSON

    A report process must generate a variable reportData that is a JSON representation of the data that must be displayed to the user. The json should look as follows:

    {
      "title": "My Report",
      "datasets": [
        {
          "type" : "lineChart",
          "description" : "My first chart",
          "xaxis" : "Year"
          "yaxis" : "Total sales"
          "data" : 
          {
            "2010" : 50,
            "2011" : 33,
            "2012" : 17,
            "2013" : 87,
          }
        }
      ]
    }          
              

    This json will be fetched at runtime in Explorer and will be used to generate charts or lists. The elements in the json are:

    • title: this is the general title for the whole report

    • datasets: this is an array of datasets corresponding with the different charts and lists on the report.

    • typeEach dataset has a type. This type will be used to determine how the data will be rendered. Currently supported values are: pieChart, lineChart, barChart and list.

    • description: each chart can have an optional description that will be shown in the report.

    • x- and yaxis: only usable for type lineChart. Optional parameter that determines the name of the axes of the chart

    • data: this is the actual data. The data is a json object with key-value elements.

    Example process

    The following example shows a 'process instance overview' report. The process itself is very easy and contains only a script task (besides start and end) that generates the json dataset using javascript. Although all of the examples in Explorer use scripting, this can very well be done using Java service tasks. The end result of running the process should just be the reportData variable that contains the data.

    Important note: The following example only works on JDK 7+. The reason for this is that the javascript engine (Rhino) that is shipped with older JDK versions isn't advanced enough to cope with some constructs needed to write scripts like the one below. See below for a JDK 6+ compliant example.

    <?xml version="1.0" encoding="UTF-8"?>
    <definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:activiti="http://activiti.org/bpmn"
        xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:omgdc="http://www.omg.org/spec/DD/20100524/DC"
        xmlns:omgdi="http://www.omg.org/spec/DD/20100524/DI" typeLanguage="http://www.w3.org/2001/XMLSchema"
        expressionLanguage="http://www.w3.org/1999/XPath" 
        targetNamespace="activiti-report">
    
        <process id="process-instance-overview-report" name="Process Instance Overview" isExecutable="true">
        
            <startEvent id="startevent1" name="Start" />
            <sequenceFlow id="flow1" sourceRef="startevent1" targetRef="generateDataset" />
            
            <scriptTask id="generateDataset" name="Execute script" scriptFormat="JavaScript" activiti:autoStoreVariables="false">
              <script><![CDATA[
              
                   importPackage(java.sql);
                   importPackage(java.lang);
                   importPackage(org.activiti.explorer.reporting);
                   
                   var result = ReportingUtil.executeSelectSqlQuery("SELECT PD.NAME_, PD.VERSION_ , count(*) FROM ACT_HI_PROCINST PI inner join ACT_RE_PROCDEF PD on PI.PROC_DEF_ID_ = PD.ID_ group by PROC_DEF_ID_");
                
                   var reportData = {};
                   reportData.datasets = [];
                   
                   var dataset = {};
                   dataset.type = "pieChart";
                   dataset.description = "Process instance overview (" + new java.util.Date() + ")";
                   dataset.data = {};
                
                   while (result.next()) { // process results one row at a time
                     var name = result.getString(1);
                     var version = result.getLong(2)
                     var count = result.getLong(3);
                     dataset.data[name + " (v" + version + ")"] = count;
                   }
                   reportData.datasets.push(dataset);
                   
                   execution.setVariable("reportData", new java.lang.String(JSON.stringify(reportData)).getBytes("UTF-8"));
              ]]></script>
            </scriptTask>
            <sequenceFlow id="flow3" sourceRef="generateDataset" targetRef="theEnd" />
            
            <endEvent id="theEnd" />
            
        </process>
    
    </definitions>            
                

    Besides the typical XML linea at the top of the process xml, the main difference is that the targetNamespace is set to activiti-report, adding the category with the same name to the deployed process definition.

    The first lines of the script are just some imports to avoid having to type the package names all the time. The first line of interest is where the ReportingUtil is used to query the Activiti database. The result of that call is a regular JDBC Resultset. In the lines following the query, the javascript capabilities to easily create json is used. The json that is produced matches the requirements.

    The last line of the script may seem a bit odd. The first thing we need to do is to convert the json object to a string by using the javascript function JSON.stringify(). This string then needs to be stored as a byte array variable. The reason for this is technical: a byte array is unlimited in size while the string is not. That is why the javascript string must be converted to a Java string which has the capability to get the byte representation.

    The same process which is compatible with JDK 6 (and higher) looks a bit different. The native json capabilities cannot be used, hence some helper classes (ReportData and Dataset) are provided:

    <?xml version="1.0" encoding="UTF-8"?>
    <definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:activiti="http://activiti.org/bpmn"
        xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:omgdc="http://www.omg.org/spec/DD/20100524/DC"
        xmlns:omgdi="http://www.omg.org/spec/DD/20100524/DI" typeLanguage="http://www.w3.org/2001/XMLSchema"
        expressionLanguage="http://www.w3.org/1999/XPath" 
        targetNamespace="activiti-report">
    
        <process id="process-instance-overview-report" name="Process Instance Overview" isExecutable="true">
        
            <startEvent id="startevent1" name="Start" />
            <sequenceFlow id="flow1" sourceRef="startevent1" targetRef="generateDataset" />
            
            <scriptTask id="generateDataset" name="Execute script" scriptFormat="js" activiti:autoStoreVariables="false">
              <script><![CDATA[
              
                   importPackage(java.sql);
                   importPackage(java.lang);
                   importPackage(org.activiti.explorer.reporting);
                   
                   var result = ReportingUtil.executeSelectSqlQuery("SELECT PD.NAME_, PD.VERSION_ , count(*) FROM ACT_HI_PROCINST PI inner join ACT_RE_PROCDEF PD on PI.PROC_DEF_ID_ = PD.ID_ group by PROC_DEF_ID_");
    
                
                   var reportData = new ReportData;
                   var dataset = reportData.newDataset();
                   dataset.type = "pieChart";
                   dataset.description = "Process instance overview (" + new java.util.Date() + ")"
                   
                   
                   while (result.next()) { // process results one row at a time
                     var name = result.getString(1);
                     var version = result.getLong(2);
                     var count = result.getLong(3);
                     dataset.add(name + " (v" + version + ")", count);
                   }
                   
                   execution.setVariable("reportData", reportData.toBytes());
                   
              ]]></script>
            </scriptTask>
            <sequenceFlow id="flow3" sourceRef="generateDataset" targetRef="theEnd" />
            
            <endEvent id="theEnd" />
            
        </process>
    
    </definitions>            
                

    Report start forms

    As reports are generated by regular processes, the regular form capabilities can be used. Simply add a start form to the start event and Explorer will display the form to the user before generating the process.

    <startEvent id="startevent1" name="Start">
      <extensionElements>
        <activiti:formProperty id="processDefinition" name="Select process definition" type="processDefinition" required="true" />
          <activiti:formProperty id="chartType" name="Chart type" type="enum" required="true">
            <activiti:value id="pieChart" name="Pie chart" />
            <activiti:value id="barChart" name="Bar chart" />
          </activiti:formProperty>
      </extensionElements>
    </startEvent>            
                

    which is rendered to the user as a typical form:

    The form properties are submitted when starting the process and they are available as normal execution variables that can be used within the script that generates the data:

     var processDefinition = execution.getVariable("processDefinition");

    Example processes

    By default, Explorer contains four example reports:

    • Employee productivity: this report demonstrates the use of a line chart and using a a start form. The script in this report is also complexer as in the other examples, as the data that is fetched is interpreted by the script before stored in the report data.

    • Helpdesk - firstline vs escalated: shows the use of a pie chart and combines the result of two separate database queries.

    • Process instance overview: this is an example of a report where multiple datasets are used. The report contains a pie chart and a list view of the same data, thus showing how multiple datasets can be used to generate a page with several charts.

    • Task duration: another example of using a start form and using the corresponding variables to build the SQL query dynamically.

    Changing the database

    To change the database that Explorer uses in the demo setup, change the properties file apps/apache-tomcat-6.x/webapps/activiti-explorer/WEB-INF/classes/db.properties. Also, place a suitable database driver on the classpath (Tomcat shared libs or in apps/apache-tomcat-6.x/webapps/activiti-explorer/WEB-INF/lib/).

    Chapter 14. Activiti Modeler

    Activiti Modeler is a BPMN web modeler component that's available as part of the Activiti Explorer web application. The Modeler is a fork of the Signavio Core Components project. The initial development of the new Activiti Modeler is donated to the Activiti project by KIS BPM. A main difference with the previous Activiti Modeler (Signavio Core Components) is that that the new modeler is maintained and developed as part of the Activiti project. The goal of the Activiti Modeler is to support all the BPMN elements and extension supported by the Activiti Engine.

    When you run the Activiti Explorer with the default configuration one demo process will be available in the model workspace.

    Model editing

    When you click on the edit button in the model workspace the model will be opened in the modeler. On the left side of the screen the available palette of BPMN elements and Activiti extensions is available. You can drag and drop new elements on the canvas when needed. On the right side of the screen the attributes of a selected element can be filled-in. In the example screenshot a user task is selected and you can fill-in user task attributes like assignment, form properties and due date. To return to the Activiti Explorer you can click the close button at the top right of the screen.

    Importing existing models

    You can also import existing models into the model workspace to edit them in the Activiti Modeler. Click on the import button and select a .bpmn or .bpmn20.xml file. Note that the BPMN XML file should contain BPMN DI information.

    Convert deployed definitions to a editeable model

    Deployed process definition can be converted into models that can be edited by the Activiti Modeler. Note that the process definition should contain BPMN DI information.

    Export model to BPMN XML

    A model in the model workspace can be exported to a BPMN XML file. Select the export option in the model action select box.

    Deploy model to the Activiti Engine

    When a model contains all the attributes necessary to be executed, it can be deployed to the Activiti Engine. Select the deploy option in the model action select box.

    Chapter 15. REST API

    Table of Contents

    General Activiti REST principles
    Installation and Authentication
    Usage in Tomcat
    Methods and return-codes
    Error response body
    Request parameters
    Deployment
    List of Deployments
    Get a deployment
    Create a new deployment
    Delete a deployment
    List resources in a deployment
    Get a deployment resource
    Get a deployment resource content
    Process Definitions
    List of process definitions
    Get a process definition
    Update category for a process definition
    Get a process definition resource content
    Get a process definition BPMN model
    Suspend a process definition
    Activate a process definition
    Get all candidate starters for a process-definition
    Add a candidate starter to a process definition
    Delete a candidate starter from a process definition
    Get a candidate starter from a process definition
    Models
    Get a list of models
    Get a model
    Update a model
    Create a model
    Delete a model
    Get the editor source for a model
    Set the editor source for a model
    Get the extra editor source for a model
    Set the extra editor source for a model
    Process Instances
    Get a process instance
    Delete a process instance
    Activate or suspend a process instance
    Start a process instance
    List of process instances
    Query process instances
    Get diagram for a process instance
    Get involved people for process instance
    Add an involved user to a process instance
    Remove an involved user to from process instance
    List of variables for a process instance
    Get a variable for a process instance
    Create (or update) variables on a process instance
    Update a single variable on a process instance
    Create a new binary variable on a process-instance
    Update an existing binary variable on a process-instance
    Executions
    Get an execution
    Execute an action on an execution
    Get active activities in an execution
    List of executions
    Query executions
    List of variables for an execution
    Get a variable for an execution
    Create (or update) variables on an execution
    Update a variable on an execution
    Create a new binary variable on an execution
    Update an existing binary variable on a process-instance
    Tasks
    Get a task
    List of tasks
    Query for tasks
    Update a task
    Task actions
    Delete a task
    Get all variables for a task
    Get a variable from a task
    Get the binary data for a variable
    Create new variables on a task
    Create a new binary variable on a task
    Update an existing variable on a task
    Updating a binary variable on a task
    Delete a variable on a task
    Delete all local variables on a task
    Get all identity links for a task
    Get all identitylinks for a task for either groups or users
    Get a single identity link on a task
    Create an identity link on a task
    Delete an identity link on a task
    Create a new comment on a task
    Get all comments on a task
    Get a comment on a task
    Delete a comment on a task
    Get all events for a task
    Get an event on a task
    Create a new attachment on a task, containing a link to an external resource
    Create a new attachment on a task, with an attached file
    Get all attachments on a task
    Get an attachment on a task
    Get the content for an attachment
    Delete an attachment on a task
    History
    Get a historic process instance
    List of historic process instances
    Query for historic process instances
    Delete a historic process instance
    Get the identity links of a historic process instance
    Get the binary data for a historic process instance variable
    Create a new comment on a historic process instance
    Get all comments on a historic process instance
    Get a comment on a historic process instance
    Delete a comment on a historic process instance
    Get a single historic task instance
    Get historic task instances
    Query for historic task instances
    Delete a historic task instance
    Get the identity links of a historic task instance
    Get the binary data for a historic task instance variable
    Get historic activity instances
    Query for historic activity instances
    List of historic variable instances
    Query for historic variable instances
    Get the binary data for a historic task instance variable
    Get historic detail
    Query for historic details
    Get the binary data for a historic detail variable
    Forms
    Get form data
    Submit task form data
    Database tables
    List of tables
    Get a single table
    Get column info for a single table
    Get row data for a single table
    Engine
    Get engine properties
    Get engine info
    Runtime
    Signal event received
    Jobs
    Get a single job
    Delete a job
    Execute a single job
    Get the exception stacktrace for a job
    Get a list of jobs
    Users
    Get a single user
    Get a list of users
    Update a user
    Create a user
    Delete a user
    Get a user's picture
    Updating a user's picture
    List a user's info
    Get a user's info
    Update a user's info
    Create a new user's info entry
    Delete a user's info
    Groups
    Get a single group
    Get a list of groups
    Update a group
    Create a group
    Delete a group
    Get members in a group
    Add a member to a group
    Delete a member from a group
    Legacy REST - General Usage
    Repository
    Upload Deployment
    Get Deployments
    Get Deployment Resources
    Get Deployment Resource
    Delete Deployment
    Delete Deployments
    Engine
    Get Process Engine
    Processes
    List Process Definitions
    Get Process Definition Form Properties
    Get Process Definition Form Resource
    Get Process Definition Diagram
    Start Process Instance
    List Process Instances
    Get Process Instance Details
    Get Process Instance Diagram
    Get open tasks for a process instance
    Signal an activity (receive task) for a specific process instance
    Trigger a signal for a specific process instance
    Tasks
    Get Task Summary
    List Tasks
    Get Task
    Get Task Form
    Perform Task Operation
    List Form Properties
    Add attachment to a task
    Get task attachment
    Add url to a task
    Identity
    Login
    Get User
    List User's Groups
    Search users
    Create user
    Add user to groups
    Remove user from group
    Get user picture
    Get Group
    List Group Users
    Search groups
    Create group
    Add users to a group
    Remove user from group
    Management
    List Jobs
    Get Job
    Execute Job
    Execute Jobs
    List Database Tables
    Get Table Meta Data
    Get Table Data

    General Activiti REST principles

    Installation and Authentication

    Activiti includes a REST API to the Activiti Engine that can be installed by deploying the activiti-rest.war file to a servlet container like Apache Tomcat. However, it can also be used in another web-application by including the servlet and it's mapping in your application and add all activiti-rest dependencies to the classpath.

    By default the Activiti Engine will connect to an in-memory H2 database. You can change the database settings in the db.properties file in the WEB-INF/classes folder. The REST API uses JSON format (http://www.json.org) and is built upon the Restlet (http://www.restlet.org).

    All REST-resources require a valid Activiti-user to be authenticated by default. Basic HTTP access authentication is used, so you should always include a Authorization: Basic ...== HTTP-header when performing requests or include the username and password in the request-url (eg. http://username:password@localhost...).

    It's recommended to use Basic Authentication in combination with HTTPS.

    It's possible to remove authentication from certain resources or adding additional authorisation on top of being an authenticated user (eg. being part of group X allows a user to execute request with URL Y). This can be achieved by using an implementation of org.activiti.rest.common.filter.RestAuthenticator which has 2 methods:

    • boolean requestRequiresAuthentication(Request request): Called before a request is checked for authentication (valid username and password is passed in header). If this method returns true, the method needs authentication. If false is returned, the request will be done regardless of the request being authenticated. If false is returned, isRequestAuthorized will not be called either for this request.

    • boolean isRequestAuthorized(Request request): Called after a user is successfully authenticated against the Activiti identity-management but before the request is actually executed. Can be used to check if a certain request is valid for the authenticated user. If true is returned, the request is considered authorised and is executed. When false is returned, the request is not executed and the client gets an appropriate error.

    The custom RestAuthenticator should be set on the org.activiti.rest.service.application.ActivitiRestServicesApplicationthat is used in the RestletServlet. The easiest way for this to create a subclass of the ActivitiRestServicesApplication and use the custom implementation classname in the servlet-mapping:

       <!-- Restlet adapter -->  
      <servlet>  
        <servlet-name>RestletServlet</servlet-name>  
        <servlet-class>org.restlet.ext.servlet.ServerServlet</servlet-class>
        <init-param>
          <!-- Application class name -->
          <param-name>org.restlet.application</param-name>
          <param-value>com.my.company.CustomActivitiRestServicesApplication</param-value>
        </init-param>
      </servlet>

    Usage in Tomcat

    Due to default security properties on Tomcat, escaped forward slashes (%2F and %5C) are not allowed by default (400-result is returned). This may have an impact on the deployment resources and their data-URL, as the URL can potentially contain escaped forward slashes. When issues are experienced with unexpected 400-results, set the following system-property: -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true.

    Methods and return-codes

    Table 15.1. HTTP-methods and corresponding operations

    MethodOperations
    GETGet a single resource or get a collection of resources.
    POSTCreate a new resource. Also used for executing resource-queries which have a too complex request-structure to fit in the query-URL of a GET-request.
    PUTUpdate properties of an existing resource. Also used for invoking actions on an existing resource.
    DELETEDelete an existing resource.

    Table 15.2. HTTP-methods response codes

    ResponseDescription
    200 - OkThe operation was successful and a response has been returned (GET and PUT requests).
    201 - CreatedThe operation was successful and the entity has been created and is returned in the response-body (POST request).
    204 - No contentThe operation was successful and entity has been deleted and therefore there is no response-body returned (DELETE request).
    401 - UnauthorizedThe operation failed. The operation requires an Authentication header to be set. If this was present in the request, the supplied credentials are not valid or the user is not authorized to perform this operation.
    403 - ForbiddenThe operation is forbidden and should not be re-attempted. This does not imply an issue with authentication not authorization, it's an operation that is not allowed. Example: deleting a task that is part of a running process is not allowed and will never be allowed, regardless of the user or process/task state.
    404 - Not foundThe operation failed.The requested resource was not found.
    405 - Method not allowedThe operation failed. The used method is not allowed for this resource. Eg. trying to update (PUT) a deployment-resource will result in a 405 status.
    409 - ConflictThe operation failed. The operation causes an update of a resource that has been updated by another operation, which makes the update no longer valid. Can also indicate a resource that is being created in a collection where a resource with that identifier already exists.
    415 - Unsupported Media TypeThe operation failed. The request body contains an unsupported media type. Also occurs when the request-body JSON contains an unknown attribute or value that doesn't have the right format/type to be accepted.
    500 - Internal server errorThe operation failed. An unexpected exception occurred while executing the operation. The response-body contains details about the error.

    The media-type of the HTTP-responses is always application/json unless binary content is requested (eg. deployment resource data), the media-type of the content is used.

    Error response body

    When an error occurs (both client and server, 4XX and 5XX status-codes) the response body contains an object describing the error that occurred. An example for a 404-status when a task is not found:

    {
      "statusCode" : 404,
      "errorMessage" : "Could not find a task with id '444'."
    }

    Request parameters

    URL fragments

    Parameters that are part of the url (eg. the deploymentId parameter in http://host/actviti-rest/service/repository/deployments/{deploymentId}) need to be properly escaped (see URL-encoding or Percent-encoding) in case the segment contains special characters. Most frameworks have this functionality built in, but it should be taken into account. Especially for segments that can contains forward-slashes (eg. deployment resource), this is required.

    Rest URL query parameters

    Parameters added as query-string in the URL (eg. the name parameter used in http://host/activiti-rest/service/deployments?name=Deployment) can have the following types and are mentioned in the corresponding REST-API documentation:

    Table 15.3. URL query parameter types

    TypeFormat
    StringPlain text parameters. Can contain any valid characters that are allowed in URL's. In case of a XXXLike parameter, the string should contain the wildcard characted % (properly url-encoded). This allows to specify the intent of the like-search. Eg. 'Tas%' matches all values, starting with 'Tas'.
    IntegerParameter representing an integer value. Can only contain numeric non-decmimal values, between -2.147.483.648 and 2.147.483.647.
    LongParameter representing a long value. Can only contain numeric non-decmimal values, between -9.223.372.036.854.775.808 and 9.223.372.036.854.775.807.
    BooleanParameter representing a boolean value. Can be eiter true or false. All other values other than these two, will cause a '405 - Bad request' response.
    DateParameter representing a date value. Use the ISO-8601 date-format (see ISO-8601 on wikipedia) using both time and date-components (eg. 2013-04-03T23:45Z).


    JSON body parameters

    Table 15.4. JSON parameter types

    TypeFormat
    StringPlain text parameters. In case of a XXXLike parameter, the string should contain the wildcard characted %. This allows to specify the intent of the like-search. Eg. 'Tas%' matches all values, starting with 'Tas'.
    IntegerParameter representing an integer value, using a JSON number. Can only contain numeric non-decmimal values, between -2.147.483.648 and 2.147.483.647.
    LongParameter representing a long value, using a JSON number. Can only contain numeric non-decmimal values, between -9.223.372.036.854.775.808 and 9.223.372.036.854.775.807.
    BooleanParameter representing a boolean value, using a JSON boolean. Can be eiter true or false. All other values other than these two, will cause a '405 - Bad request' response.
    DateParameter representing a date value, using a JSON text. Use the ISO-8601 date-format (see ISO-8601 on wikipedia) using both time and date-components (eg. 2013-04-03T23:45Z).


    Paging and sorting

    Paging and order parameters can be added as query-string in the URL (eg. the name parameter used in http://host/activiti-rest/service/deployments?sort=name).

    Table 15.5. Variable query JSON parameters

    ParameterDefault valueDescription
    sortdifferent per query implementationName of the sort key, for which the default value and the allowed values are different per query implementation.
    orderascSorting order which can be 'asc' or 'desc'.
    start0Parameter to allow for paging of the result. By default the result will start at 0.
    size10Parameter to allow for paging of the result. By default the size will be 10.


    JSON query variable format

    { 
      "name" : "variableName",
      "value" : "variableValue",
      "operation" : "equals",
      "type" : "string"
    }

    Table 15.6. Variable query JSON parameters

    ParameterRequiredDescription
    nameNoName of the variable to include in a query. Can be empty in case 'equals' is used in some queries to query for resources that have any variable name with the given value.
    valueYesValue of the variable included in the query, should include a correct format for the given type.
    operatorYesOperator to use in query, can have the following values: equals, notEquals, equalsIgnoreCase, notEqualsIgnoreCase, lessThan, greaterThan, lessThanOrEquals, greaterThanOrEquals and like.
    typeNoType of variable to use. When omitted, the type will be deducted from the value parameter. Any JSON text-values will be considered of type string, JSON booleans of type boolean, JSON numbers of type long or integer depending on the size of the number. It's recommended to include an explicit type when in doubt. Types supported out of the box are listed below.


    Table 15.7. Default query JSON types

    Type nameDescription
    stringValue is threaded as and converted to a java.lang.String.
    shortValue is threaded as and converted to a java.lang.Integer.
    integerValue is threaded as and converted to a java.lang.Integer.
    longValue is threaded as and converted to a java.lang.Long.
    doubleValue is threaded as and converted to a java.lang.Double.
    booleanValue is threaded as and converted to a java.lang.Boolean.
    dateValue is treated as and converted to a java.util.Date. The JSON string will be converted using ISO-8601 date format.


    Variable representation

    When working with variables (execution/process and task), the REST-api uses some common principles and JSON-format for both reading and writing. The JSON representation of a variable looks like this:

    { 
      "name" : "variableName",
      "value" : "variableValue",
      "valueUrl" : "http://...",
      "scope" : "local",
      "type" : "string"
    }

    Table 15.8. Variable JSON attributes

    ParameterRequiredDescription
    nameYesName of the variable.
    valueNoValue of the variable. When writing a variable and value is omitted, null will be used as value.
    valueUrlNoWhen reading a variable of type binary or serializable, this attribute will point to the URL where the raw binary data can be fetched from.
    scopeNoScope of the variable. If 'local', the variable is explicitly defined on the resource it's requested from. When 'global', the variable is defined on the parent (or any parent in the parent-tree) of the resource it's requested from. When writing a variable and the scope is omitted, global is assumed.
    typeNoType of the variable. See table below for additional information on types. When writing a variable and this value is omitted, the type will be deducted from the raw JSON-attribute request type and is limited to either string, double, integer and boolean. It's advised to always include a type to make sure no wrong assumption about the type can be done.


    Table 15.9. Variable Types

    Type nameDescription
    stringValue is threaded as a java.lang.String. Raw JSON-text value is used when writing a variable.
    integerValue is threaded as a java.lang.Integer. When writing, JSON number value is used as base for conversion, falls back to JSON text.
    shortValue is threaded as a java.lang.Short. When writing, JSON number value is used as base for conversion, falls back to JSON text.
    longValue is threaded as a java.lang.Long. When writing, JSON number value is used as base for conversion, falls back to JSON text.
    doubleValue is threaded as a java.lang.Double. When writing, JSON number value is used as base for conversion, falls back to JSON text.
    booleanValue is threaded as a java.lang.Boolean. When writing, JSON boolean value is used for conversion.
    dateValue is treated as a java.util.Date. When writing, the JSON text will be converted using ISO-8601 date format.
    binaryBinary variable, threated as an array of bytes. The value attribute is null, the valueUrl contains an URL pointing to the raw binary stream.
    serializableSerialized representation of a Serializable Java-object. As with the binary type, the value attribute is null, the valueUrl contains an URL pointing to the raw binary stream. All serializable variables (which are not of any of the above types) will be exposed as a variable of this type.


    It's possible to support additional variable-types with a custom JSON representation (either simple value or complex/nested JSON object). By extending the initializeVariableConverters() method on org.activiti.rest.service.api.RestResponseFactory, you can add additional org.activiti.rest.service.api.engine.variable.RestVariableConverter classes to support converting your POJO's to a format suitable for transferring through REST and converting the REST-value back to your POJO. The actual transformation to JSON is done by Jackson.

    Deployment

    When using tomcat, please read Usage in Tomcat.

    List of Deployments

    GET repository/deployments

    Table 15.10. URL query parameters

    ParameterRequiredValueDescription
    nameNoStringOnly return deployments with the given name.
    nameLikeNoStringOnly return deployments with a name like the given name.
    categoryNoStringOnly return deployments with the given category.
    categoryNotEqualsNoStringOnly return deployments which don't have the given category.
    tenantIdNoStringOnly return deployments with the given tenantId.
    tenantIdLikeNoStringOnly return deployments with a tenantId like the given value.
    withoutTenantIdNoBooleanIf true, only returns deployments without a tenantId set. If false, the withoutTenantId parameter is ignored.
    sortNo'id' (default), 'name', 'deploytime' or 'tenantId'Property to sort on, to be used together with the 'order'.

    The general paging and sorting query-parameters can be used for this URL.


    Table 15.11. REST Response codes

    Response codeDescription
    200Indicates the request was successful.


    Success response body:

    {
      "data": [
        {
          "id": "10",
          "name": "activiti-examples.bar",
          "deploymentTime": "2010-10-13T14:54:26.750+02:00",
          "category": "examples",
          "url": "http://localhost:8081/service/repository/deployments/10",
          "tenantId": null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "id",
      "order": "asc",
      "size": 1
    }

    Get a deployment

    GET repository/deployments/{deploymentId}

    Table 15.12. Get a deployment - URL parameters

    ParameterRequiredValueDescription
    deploymentIdYesStringThe id of the deployment to get.


    Table 15.13. Get a deployment - Response codes

    Response codeDescription
    200Indicates the deployment was found and returned.
    404Indicates the requested deployment was not found.


    Success response body:

    {
      "id": "10",
      "name": "activiti-examples.bar",
      "deploymentTime": "2010-10-13T14:54:26.750+02:00",
      "category": "examples",
      "url": "http://localhost:8081/service/repository/deployments/10",
      "tenantId" : null
    }

    Create a new deployment

    POST repository/deployments

    Request body:

    The request should body should contain data of type multipart/form-data. There should be only exactly file in the request, any additional files will be ignored. The deployment name is the name of the file-field passed in. If multiple resources need to be deployed in a single deployment, compress the resources in a zip and make sure the file-name ends with .bar or .zip.

    An additional parameter (form-field) can be passed in the request body with name tenantId. The value of this field will be used as the id of the tenant this deployment is done in.

    Table 15.14. Create a new deployment - Response codes

    Response codeDescription
    201Indicates the deployment was created.
    400Indicates there was no content present in the request body or the content mime-type is not supported for deployment. The status-description contains additional information.


    Success response body:

    {
      "id": "10",
      "name": "activiti-examples.bar",
      "deploymentTime": "2010-10-13T14:54:26.750+02:00",
      "category": null,
      "url": "http://localhost:8081/service/repository/deployments/10",
      "tenantId" : "myTenant"
    }

    Delete a deployment

    DELETE repository/deployments/{deploymentId}

    Table 15.15. Delete a deployment - URL parameters

    ParameterRequiredValueDescription
    deploymentIdYesStringThe id of the deployment to delete.


    Table 15.16. Delete a deployment - Response codes

    Response codeDescription
    204Indicates the deployment was found and has been deleted. Response-body is intentionally empty.
    404Indicates the requested deployment was not found.


    List resources in a deployment

    GET repository/deployments/{deploymentId}/resources

    Table 15.17. List resources in a deployment - URL parameters

    ParameterRequiredValueDescription
    deploymentIdYesStringThe id of the deployment to get the resources for.


    Table 15.18. List resources in a deployment - Response codes

    Response codeDescription
    200Indicates the deployment was found and the resource list has been returned.
    404Indicates the requested deployment was not found.


    Success response body:

    [
      {
        "id": "diagrams/my-process.bpmn20.xml",
        "url": "http://localhost:8081/activiti-rest/service/repository/deployments/10/resources/diagrams%2Fmy-process.bpmn20.xml",
        "dataUrl": "http://localhost:8081/activiti-rest/service/repository/deployments/10/resourcedata/diagrams%2Fmy-process.bpmn20.xml",
        "mediaType": "text/xml",
        "type": "processDefinition"
      },
      {
        "id": "image.png",
        "url": "http://localhost:8081/activiti-rest/service/repository/deployments/10/resources/image.png",
        "dataUrl": "http://localhost:8081/activiti-rest/service/repository/deployments/10/resourcedata/image.png",
        "mediaType": "image/png",
        "type": "resource"
      }
    ]

    • mediaType: Contains the media-type the resource has. This is resolved using a (pluggable) MediaTypeResolver and contains, by default, a limited number of mime-type mappings.

    • type: Type of resource, possible values:

      • resource: Plain old resource.

      • processDefinition: Resource that contains one or more process-definitions. This resource is picked up by the deployer.

      • processImage: Resource that represents a deployed process definition's graphical layout.

    The dataUrl property in the resulting json for a single resource contains the actual URL to use for retrieving the binary resource.

    Get a deployment resource

    GET repository/deployments/{deploymentId}/resources/{resourceId}

    Table 15.19. Get a deployment resource - URL parameters

    ParameterRequiredValueDescription
    deploymentIdYesStringThe id of the deployment the requested resource is part of.
    resourceIdYesStringThe id of the resource to get. Make sure you URL-encode the resourceId in case it contains forward slashes. Eg: use 'diagrams%2Fmy-process.bpmn20.xml' instead of 'diagrams/Fmy-process.bpmn20.xml'.


    Table 15.20. Get a deployment resource - Response codes

    Response codeDescription
    200Indicates both deployment and resource have been found and the resource has been returned.
    404Indicates the requested deployment was not found or there is no resource with the given id present in the deployment. The status-description contains additional information.


    Success response body:

    {
      "id": "diagrams/my-process.bpmn20.xml",
      "url": "http://localhost:8081/activiti-rest/service/repository/deployments/10/resources/diagrams%2Fmy-process.bpmn20.xml",
      "dataUrl": "http://localhost:8081/activiti-rest/service/repository/deployments/10/resourcedata/diagrams%2Fmy-process.bpmn20.xml",
      "mediaType": "text/xml",
      "type": "processDefinition"
    }

    • mediaType: Contains the media-type the resource has. This is resolved using a (pluggable) MediaTypeResolver and contains, by default, a limited number of mime-type mappings.

    • type: Type of resource, possible values:

      • resource: Plain old resource.

      • processDefinition: Resource that contains one or more process-definitions. This resource is picked up by the deployer.

      • processImage: Resource that represents a deployed process definition's graphical layout.

    Get a deployment resource content

    GET repository/deployments/{deploymentId}/resourcedata/{resourceId}

    Table 15.21. Get a deployment resource content - URL parameters

    ParameterRequiredValueDescription
    deploymentIdYesStringThe id of the deployment the requested resource is part of.
    resourceIdYesStringThe id of the resource to get the data for. Make sure you URL-encode the resourceId in case it contains forward slashes. Eg: use 'diagrams%2Fmy-process.bpmn20.xml' instead of 'diagrams/Fmy-process.bpmn20.xml'.


    Table 15.22. Get a deployment resource content - Response codes

    Response codeDescription
    200Indicates both deployment and resource have been found and the resource data has been returned.
    404Indicates the requested deployment was not found or there is no resource with the given id present in the deployment. The status-description contains additional information.


    Success response body:

    The response body will contain the binary resource-content for the requested resource. The response content-type will be the same as the type returned in the resources 'mimeType' property. Also, a content-disposition header is set, allowing browsers to download the file instead of displaying it.

    Process Definitions

    List of process definitions

    GET repository/process-definitions

    Table 15.23. List of process definitions - URL parameters

    ParameterRequiredValueDescription
    versionNointegerOnly return process definitions with the given version.
    nameNoStringOnly return process definitions with the given name.
    nameLikeNoStringOnly return process definitions with a name like the given name.
    keyNoStringOnly return process definitions with the given key.
    keyLikeNoStringOnly return process definitions with a name like the given key.
    resourceNameNoStringOnly return process definitions with the given resource name.
    resourceNameLikeNoStringOnly return process definitions with a name like the given resource name.
    categoryNoStringOnly return process definitions with the given category.
    categoryLikeNoStringOnly return process definitions with a category like the given name.
    categoryNotEqualsNoStringOnly return process definitions which don't have the given category.
    deploymentIdNoStringOnly return process definitions which are part of a deployment with the given id.
    startableByUserNoStringOnly return process definitions which can be started by the given user.
    latestNoBooleanOnly return the latest process definition versions. Can only be used together with 'key' and 'keyLike' parameters, using any other parameter will result in a 400-response.
    suspendedNoBooleanIf true, only returns process definitions which are suspended. If false, only active process definitions (which are not suspended) are returned.
    sortNo'name' (default), 'id', 'key', 'category', 'deploymentId' and 'version'Property to sort on, to be used together with the 'order'.

    The general paging and sorting query-parameters can be used for this URL.

       


    Table 15.24. List of process definitions - Response codes

    Response codeDescription
    200Indicates request was successful and the process-definitions are returned
    400Indicates a parameter was passed in the wrong format or that 'latest' is used with other parameters other than 'key' and 'keyLike'. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "oneTaskProcess:1:4",
          "url" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
          "version" : 1,
          "key" : "oneTaskProcess",
          "category" : "Examples",
          "suspended" : false,
          "name" : "The One Task Process",
          "description" : "This is a process for testing purposes",
          "deploymentId" : "2",
          "deploymentUrl" : "http://localhost:8081/repository/deployments/2",
          "graphicalNotationDefined" : true,
          "resource" : "http://localhost:8182/repository/deployments/2/resources/testProcess.xml",
          "diagramResource" : "http://localhost:8182/repository/deployments/2/resources/testProcess.png",
          "startFormDefined" : false
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    • graphicalNotationDefined: Indicates the process definition contains graphical information (BPMN DI).

    • resource: Contains the actual deployed BPMN 2.0 xml.

    • diagramResource: Contains a graphical representation of the process, null when no diagram is available.

    Get a process definition

    GET repository/process-definitions/{processDefinitionId}

    Table 15.25. Get a process definition - URL parameters

    ParameterRequiredValueDescription
    processDefinitionIdYesStringThe id of the process definition to get.


    Table 15.26. Get a process definition - Response codes

    Response codeDescription
    200Indicates the process definition was found and returned.
    404Indicates the requested process definition was not found.


    Success response body:

    { 
      "id" : "oneTaskProcess:1:4",
      "url" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
      "version" : 1,
      "key" : "oneTaskProcess",
      "category" : "Examples",
      "suspended" : false,
      "name" : "The One Task Process",
      "description" : "This is a process for testing purposes",
      "deploymentId" : "2",
      "deploymentUrl" : "http://localhost:8081/repository/deployments/2",
      "graphicalNotationDefined" : true,
      "resource" : "http://localhost:8182/repository/deployments/2/resources/testProcess.xml",
      "diagramResource" : "http://localhost:8182/repository/deployments/2/resources/testProcess.png",
      "startFormDefined" : false
    }

    • graphicalNotationDefined: Indicates the process definition contains graphical information (BPMN DI).

    • resource: Contains the actual deployed BPMN 2.0 xml.

    • diagramResource: Contains a graphical representation of the process, null when no diagram is available.

    Update category for a process definition

    PUT repository/process-definitions/{processDefinitionId}

    Body JSON:

    { 
      "category" : "updatedcategory"
    }

    Table 15.27. Update category for a process definition - Response codes

    Response codeDescription
    200Indicates the process was category was altered.
    400Indicates no category was defined in the request body.
    404Indicates the requested process definition was not found.


    Success response body: see response for repository/process-definitions/{processDefinitionId}.

    Get a process definition resource content

    GET repository/process-definitions/{processDefinitionId}/resourcedata

    Table 15.28. Get a process definition resource content - URL parameters

    ParameterRequiredValueDescription
    processDefinitionIdYesStringThe id of the process definition to get the resource data for.


    Response:

    Exactly the same response codes/boy as GET repository/deployment/{deploymentId}/resourcedata/{resourceId}.

    Get a process definition BPMN model

    GET repository/process-definitions/{processDefinitionId}/model

    Table 15.29. Get a process definition BPMN model - URL parameters

    ParameterRequiredValueDescription
    processDefinitionIdYesStringThe id of the process definition to get the model for.


    Table 15.30. Get a process definition BPMN model - Response codes

    Response codeDescription
    200Indicates the process definition was found and the model is returned.
    404Indicates the requested process definition was not found.


    Response body: The response body is a JSON representation of the org.activiti.bpmn.model.BpmnModel and contains the full process definition model.

    {
       "processes":[
          {
             "id":"oneTaskProcess",
             "xmlRowNumber":7,
             "xmlColumnNumber":60,
             "extensionElements":{
    
             },
             "name":"The One Task Process",
             "executable":true,
             "documentation":"One task process description",
             
             ...
        ], 
        
        ...
    }
    

    Suspend a process definition

    PUT repository/process-definitions/{processDefinitionId}

    Body JSON:

    { 
      "action" : "suspend",
      "includeProcessInstances" : "false",
      "date" : "2013-04-15T00:42:12Z"
    }

    Table 15.31. Suspend a process definition - JSON Body parameters

    ParameterDescriptionRequired
    actionAction to perform. Either activate or suspend.Yes
    includeProcessInstancesWhether or not to suspend/activate running process-instances for this process-definition. If omitted, the process-instances are left in the state they are.No
    dateDate (ISO-8601) when the suspension/activation should be executed. If omitted, the suspend/activation is effective immediatly.No


    Table 15.32. Suspend a process definition - Response codes

    Response codeDescription
    200Indicates the process was suspended.
    404Indicates the requested process definition was not found.
    409Indicates the requested process definition is already suspended.


    Success response body: see response for repository/process-definitions/{processDefinitionId}.

    Activate a process definition

    PUT repository/process-definitions/{processDefinitionId}

    Body JSON:

    { 
      "action" : "activate",
      "includeProcessInstances" : "true",
      "date" : "2013-04-15T00:42:12Z"
    }

    See suspend process definition JSON Body parameters.

    Table 15.33. Activate a process definition - Response codes

    Response codeDescription
    200Indicates the process was activated.
    404Indicates the requested process definition was not found.
    409Indicates the requested process definition is already active.


    Success response body: see response for repository/process-definitions/{processDefinitionId}.

    Get all candidate starters for a process-definition

    GET repository/process-definitions/{processDefinitionId}/identitylinks

    Table 15.34. Get all candidate starters for a process-definition - URL parameters

    ParameterRequiredValueDescription
    processDefinitionIdYesStringThe id of the process definition to get the identity links for.


    Table 15.35. Get all candidate starters for a process-definition - Response codes

    Response codeDescription
    200Indicates the process definition was found and the requested identity links are returned.
    404Indicates the requested process definition was not found.


    Success response body:

    [
       {
          "url":"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4/identitylinks/groups/admin",
          "user":null,
          "group":"admin",
          "type":"candidate"
       },
       {
          "url":"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4/identitylinks/users/kermit",
          "user":"kermit",
          "group":null,
          "type":"candidate"
       }
    ]

    Add a candidate starter to a process definition

    POST repository/process-definitions/{processDefinitionId}/identitylinks

    Table 15.36. Add a candidate starter to a process definition - URL parameters

    ParameterRequiredValueDescription
    processDefinitionIdYesStringThe id of the process definition.


    Request body (user):

    {
      "user" : "kermit"
    }

    Request body (group):

    {
      "groupId" : "sales"
    }

    Table 15.37. Add a candidate starter to a process definition - Response codes

    Response codeDescription
    201Indicates the process definition was found and the identity link was created.
    404Indicates the requested process definition was not found.


    Success response body:

    {
      "url":"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4/identitylinks/users/kermit",
      "user":"kermit",
      "group":null,
      "type":"candidate"
    }

    Delete a candidate starter from a process definition

    DELETE repository/process-definitions/{processDefinitionId}/identitylinks/{family}/{identityId}

    Table 15.38. Delete a candidate starter from a process definition - URL parameters

    ParameterRequiredValueDescription
    processDefinitionIdYesStringThe id of the process definition.
    familyYesStringEither users or groups, depending on the type of identity link.
    identityIdYesStringEither the userId or groupId of the identity to remove as candidate starter.


    Table 15.39. Delete a candidate starter from a process definition - Response codes

    Response codeDescription
    204Indicates the process definition was found and the identity link was removed. The response body is intentionally empty.
    404Indicates the requested process definition was not found or the process definition doesn't have an identity-link that matches the url.


    Success response body:

    {
      "url":"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4/identitylinks/users/kermit",
      "user":"kermit",
      "group":null,
      "type":"candidate"
    }

    Get a candidate starter from a process definition

    GET repository/process-definitions/{processDefinitionId}/identitylinks/{family}/{identityId}

    Table 15.40. Get a candidate starter from a process definition - URL parameters

    ParameterRequiredValueDescription
    processDefinitionIdYesStringThe id of the process definition.
    familyYesStringEither users or groups, depending on the type of identity link.
    identityIdYesStringEither the userId or groupId of the identity to get as candidate starter.


    Table 15.41. Get a candidate starter from a process definition - Response codes

    Response codeDescription
    200Indicates the process definition was found and the identity link was returned.
    404Indicates the requested process definition was not found or the process definition doesn't have an identity-link that matches the url.


    Success response body:

    {
      "url":"http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4/identitylinks/users/kermit",
      "user":"kermit",
      "group":null,
      "type":"candidate"
    }

    Models

    Get a list of models

    GET repository/models

    Table 15.42. Get a list of models - URL query parameters

    ParameterRequiredValueDescription
    idNoStringOnly return models with the given id.
    categoryNoStringOnly return models with the given category.
    categoryLikeNoStringOnly return models with a category like the given value. Use the % character as wildcard.
    categoryNotEqualsNoStringOnly return models without the given category.
    nameNoStringOnly return models with the given name.
    nameLikeNoStringOnly return models with a name like the given value. Use the % character as wildcard.
    keyNoStringOnly return models with the given key.
    deploymentIdNoStringOnly return models which are deployed in the given deployment.
    versionNoIntegerOnly return models with the given version.
    latestVersionNoBooleanIf true, only return models which are the latest version. Best used in combination with key. If false is passed in as value, this is ignored and all versions are returned.
    deployedNoBooleanIf true, only deployed models are returned. If false, only undeployed models are returned (deploymentId is null).
    tenantIdNoStringOnly return models with the given tenantId.
    tenantIdLikeNoStringOnly return models with a tenantId like the given value.
    withoutTenantIdNoBooleanIf true, only returns models without a tenantId set. If false, the withoutTenantId parameter is ignored.
    sortNo'id' (default), 'category', 'createTime', 'key', 'lastUpdateTime', 'name', 'version' or 'tenantId'Property to sort on, to be used together with the 'order'.

    The general paging and sorting query-parameters can be used for this URL.

       


    Table 15.43. Get a list of models - Response codes

    Response codeDescription
    200Indicates request was successful and the models are returned
    400Indicates a parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
       "data":[
          {
             "name":"Model name",
             "key":"Model key",
             "category":"Model category",
             "version":2,
             "metaInfo":"Model metainfo",
             "deploymentId":"7",
             "id":"10",
             "url":"http://localhost:8182/repository/models/10",
             "createTime":"2013-06-12T14:31:08.612+0000",
             "lastUpdateTime":"2013-06-12T14:31:08.612+0000",
             "deploymentUrl":"http://localhost:8182/repository/deployments/7",
             "tenantId":null
          },
          
          ...
          
       ],
       "total":2,
       "start":0,
       "sort":"id",
       "order":"asc",
       "size":2
    }

    Get a model

    GET repository/models/{modelId}

    Table 15.44. Get a model - URL parameters

    ParameterRequiredValueDescription
    modelIdYesStringThe id of the model to get.


    Table 15.45. Get a model - Response codes

    Response codeDescription
    200Indicates the model was found and returned.
    404Indicates the requested model was not found.


    Success response body:

    {
       "id":"5",
       "url":"http://localhost:8182/repository/models/5",
       "name":"Model name",
       "key":"Model key",
       "category":"Model category",
       "version":2,
       "metaInfo":"Model metainfo",
       "deploymentId":"2",
       "deploymentUrl":"http://localhost:8182/repository/deployments/2",
       "createTime":"2013-06-12T12:31:19.861+0000",
       "lastUpdateTime":"2013-06-12T12:31:19.861+0000",
       "tenantId":null
    }

    Update a model

    PUT repository/models/{modelId}

    Request body:

    {
       "name":"Model name",
       "key":"Model key",
       "category":"Model category",
       "version":2,
       "metaInfo":"Model metainfo",
       "deploymentId":"2",
       "tenantId":"updatedTenant"
    }

    All request values are optional. For example, you can only include the 'name' attribute in the request body JSON-object, only updating the name of the model, leaving all other fields unaffected. When an attribute is explicitly included and is set to null, the model-value will be updated to null. Example: {"metaInfo" : null} will clear the metaInfo of the model).

    Table 15.46. Update a model - Response codes

    Response codeDescription
    200Indicates the model was found and updated.
    404Indicates the requested model was not found.


    Success response body:

    {
       "id":"5",
       "url":"http://localhost:8182/repository/models/5",
       "name":"Model name",
       "key":"Model key",
       "category":"Model category",
       "version":2,
       "metaInfo":"Model metainfo",
       "deploymentId":"2",
       "deploymentUrl":"http://localhost:8182/repository/deployments/2",
       "createTime":"2013-06-12T12:31:19.861+0000",
       "lastUpdateTime":"2013-06-12T12:31:19.861+0000",
       "tenantId":""updatedTenant"
    }

    Create a model

    POST repository/models

    Request body:

    {
       "name":"Model name",
       "key":"Model key",
       "category":"Model category",
       "version":1,
       "metaInfo":"Model metainfo",
       "deploymentId":"2",
       "tenantId":"tenant""
    }

    All request values are optional. For example, you can only include the 'name' attribute in the request body JSON-object, only setting the name of the model, leaving all other fields null.

    Table 15.47. Create a model - Response codes

    Response codeDescription
    201Indicates the model was created.


    Success response body:

    {
       "id":"5",
       "url":"http://localhost:8182/repository/models/5",
       "name":"Model name",
       "key":"Model key",
       "category":"Model category",
       "version":1,
       "metaInfo":"Model metainfo",
       "deploymentId":"2",
       "deploymentUrl":"http://localhost:8182/repository/deployments/2",
       "createTime":"2013-06-12T12:31:19.861+0000",
       "lastUpdateTime":"2013-06-12T12:31:19.861+0000",
       "tenantId":"tenant"
    }

    Delete a model

    DELETE repository/models/{modelId}

    Table 15.48. Delete a model - URL parameters

    ParameterRequiredValueDescription
    modelIdYesStringThe id of the model to delete.


    Table 15.49. Delete a model - Response codes

    Response codeDescription
    204Indicates the model was found and has been deleted. Response-body is intentionally empty.
    404Indicates the requested model was not found.


    Get the editor source for a model

    GET repository/models/{modelId}/source

    Table 15.50. Get the editor source for a model - URL parameters

    ParameterRequiredValueDescription
    modelIdYesStringThe id of the model.


    Table 15.51. Get the editor source for a model - Response codes

    Response codeDescription
    200Indicates the model was found and source is returned.
    404Indicates the requested model was not found.


    Success response body: Response body contains the model's raw editor source. The response's content-type is set to application/octet-stream, regardless of the content of the source.

    Set the editor source for a model

    PUT repository/models/{modelId}/source

    Table 15.52. Set the editor source for a model - URL parameters

    ParameterRequiredValueDescription
    modelIdYesStringThe id of the model.


    Request body: The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the source.

    Table 15.53. Set the editor source for a model - Response codes

    Response codeDescription
    200Indicates the model was found and the source has been updated.
    404Indicates the requested model was not found.


    Success response body: Response body contains the model's raw editor source. The response's content-type is set to application/octet-stream, regardless of the content of the source.

    Get the extra editor source for a model

    GET repository/models/{modelId}/source-extra

    Table 15.54. Get the extra editor source for a model - URL parameters

    ParameterRequiredValueDescription
    modelIdYesStringThe id of the model.


    Table 15.55. Get the extra editor source for a model - Response codes

    Response codeDescription
    200Indicates the model was found and source is returned.
    404Indicates the requested model was not found.


    Success response body: Response body contains the model's raw extra editor source. The response's content-type is set to application/octet-stream, regardless of the content of the extra source.

    Set the extra editor source for a model

    PUT repository/models/{modelId}/source-extra

    Table 15.56. Set the extra editor source for a model - URL parameters

    ParameterRequiredValueDescription
    modelIdYesStringThe id of the model.


    Request body: The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the extra source.

    Table 15.57. Set the extra editor source for a model - Response codes

    Response codeDescription
    200Indicates the model was found and the extra source has been updated.
    404Indicates the requested model was not found.


    Success response body: Response body contains the model's raw editor source. The response's content-type is set to application/octet-stream, regardless of the content of the source.

    Process Instances

    Get a process instance

    GET runtime/process-instances/{processInstanceId}

    Table 15.58. Get a process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to get.


    Table 15.59. Get a process instance - Response codes

    Response codeDescription
    200Indicates the process instance was found and returned.
    404Indicates the requested process instance was not found.


    Success response body:

    {
       "id":"7",
       "url":"http://localhost:8182/runtime/process-instances/7",
       "businessKey":"myBusinessKey",
       "suspended":false,
       "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
       "activityId":"processTask",
       "tenantId": null
    }

    Delete a process instance

    DELETE runtime/process-instances/{processInstanceId}

    Table 15.60. Delete a process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to delete.


    Table 15.61. Delete a process instance - Response codes

    Response codeDescription
    204Indicates the process instance was found and deleted. Response body is left empty intentionally.
    404Indicates the requested process instance was not found.


    Activate or suspend a process instance

    PUT runtime/process-instances/{processInstanceId}

    Table 15.62. Activate or suspend a process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to activate/suspend.


    Request response body (suspend):

    {
       "action":"suspend"
    }

    Request response body (activate):

    {
       "action":"activate"
    }

    Table 15.63. Activate or suspend a process instance - Response codes

    Response codeDescription
    200Indicates the process instance was found and action was executed.
    400Indicates an invalid action was supplied.
    404Indicates the requested process instance was not found.
    409Indicates the requested process instance action cannot be executed since the process-instance is already activated/suspended.


    Start a process instance

    POST runtime/process-instances

    Request body (start by process definition id):

    {
       "processDefinitionId":"oneTaskProcess:1:158",
       "businessKey":"myBusinessKey",
       "variables": [
          {
            "name":"myVar",
            "value":"This is a variable",
          },
          
          ... 
       ]
    }

    Request body (start by process definition key):

    {
       "processDefinitionKey":"oneTaskProcess",
       "businessKey":"myBusinessKey",
       "tenantId": "tenant1",
       "variables": [
          {
            "name":"myVar",
            "value":"This is a variable",
          },
          
          ... 
       ]
    }

    Request body (start by message):

    {
       "message":"newOrderMessage",
       "businessKey":"myBusinessKey",
       "tenantId": "tenant1",
       "variables": [
          {
            "name":"myVar",
            "value":"This is a variable",
          },
          
          ... 
       ]
    }

    Only one of processDefinitionId, processDefinitionKey or message can be used in the request body. Parameters businessKey, variables and tenantId are optional. If tenantId is omitted, the default tenant will be used. More information about the variable format can be found in the REST variables section. Note that the variable-scope that is supplied is ignored, process-variables are always local.

    Table 15.64. Start a process instance - Response codes

    Response codeDescription
    201Indicates the process instance was created.
    400Indicates either the process-definition was not found (based on id or key), no process is started by sending the given message or an invalid variable has been passed. Status description contains additional information about the error.


    Success response body:

    {
       "id":"7",
       "url":"http://localhost:8182/runtime/process-instances/7",
       "businessKey":"myBusinessKey",
       "suspended":false,
       "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
       "activityId":"processTask",
       "tenantId" : null
    }

    List of process instances

    GET runtime/process-instances

    Table 15.65. List of process instances - URL query parameters

    ParameterRequiredValueDescription
    idNoStringOnly return process instance with the given id.
    processDefinitionKeyNoStringOnly return process instances with the given process definition key.
    processDefinitionIdNoStringOnly return process instances with the given process definition id.
    businessKeyNoStringOnly return process instances with the given businessKey.
    involvedUserNoStringOnly return process instances in which the given user is involved.
    suspendedNoBooleanIf true, only return process instance which are suspended. If false, only return process instances which are not suspended (active).
    superProcessInstanceIdNoStringOnly return process instances which have the given super process-instance id (for processes that have a call-activities).
    subProcessInstanceIdNoStringOnly return process instances which have the given sub process-instance id (for processes started as a call-activity).
    excludeSubprocessesNoBooleanReturn only process instances which aren't sub processes.
    includeProcessVariablesNoBooleanIndication to include process variables in the result.
    tenantIdNoStringOnly return process instances with the given tenantId.
    tenantIdLikeNoStringOnly return process instances with a tenantId like the given value.
    withoutTenantIdNoBooleanIf true, only returns process instances without a tenantId set. If false, the withoutTenantId parameter is ignored.
    sortNoStringSort field, should be either one of id (default), processDefinitionId, tenantId or processDefinitionKey.

    The general paging and sorting query-parameters can be used for this URL.

       


    Table 15.66. List of process instances - Response codes

    Response codeDescription
    200Indicates request was successful and the process-instances are returned
    400Indicates a parameter was passed in the wrong format . The status-message contains additional information.


    Success response body:

    {
       "data":[
          {
             "id":"7",
             "url":"http://localhost:8182/runtime/process-instances/7",
             "businessKey":"myBusinessKey",
             "suspended":false,
             "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
             "activityId":"processTask",
             "tenantId" : null
          },
          
          ...
       ],
       "total":2,
       "start":0,
       "sort":"id",
       "order":"asc",
       "size":2
    }

    Query process instances

    POST query/process-instances

    Request body:

    {
      "processDefinitionKey":"oneTaskProcess",
      "variables": 
      [
        {
            "name" : "myVariable",
            "value" : 1234,
            "operation" : "equals",
            "type" : "long"
        },
        ...
      ],
      ...
    }

    The request body can contain all possible filters that can be used in the List process instances URL query. On top of these, it's possible to provide an array of variables to include in the query, with their format described here.

    The general paging and sorting query-parameters can be used for this URL.

    Table 15.67. Query process instances - Response codes

    Response codeDescription
    200Indicates request was successful and the process-instances are returned
    400Indicates a parameter was passed in the wrong format . The status-message contains additional information.


    Success response body:

    {
       "data":[
          {
             "id":"7",
             "url":"http://localhost:8182/runtime/process-instances/7",
             "businessKey":"myBusinessKey",
             "suspended":false,
             "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
             "activityId":"processTask",
             "tenantId" : null
          },
          
          ...
       ],
       "total":2,
       "start":0,
       "sort":"id",
       "order":"asc",
       "size":2
    }

    Get diagram for a process instance

    GET runtime/process-instances/{processInstanceId}

    Table 15.68. Get diagram for a process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to get the diagram for.


    Table 15.69. Get diagram for a process instance - Response codes

    Response codeDescription
    200Indicates the process instance was found and the diagram was returned.
    400Indicates the requested process instance was not found but the process doesn't contain any graphical information (BPMN:DI) and no diagram can be created.
    404Indicates the requested process instance was not found.


    Success response body:

    {
       "id":"7",
       "url":"http://localhost:8182/runtime/process-instances/7",
       "businessKey":"myBusinessKey",
       "suspended":false,
       "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
       "activityId":"processTask"
    }

    Get involved people for process instance

    GET runtime/process-instances/{processInstanceId}/identitylinks

    Table 15.70. Get involved people for process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to the links for.


    Table 15.71. Get involved people for process instance - Response codes

    Response codeDescription
    200Indicates the process instance was found and links are returned.
    404Indicates the requested process instance was not found.


    Success response body:

    [
       {
          "url":"http://localhost:8182/runtime/process-instances/5/identitylinks/users/john/customType",
          "user":"john",
          "group":null,
          "type":"customType"
       },
       {
          "url":"http://localhost:8182/runtime/process-instances/5/identitylinks/users/paul/candidate",
          "user":"paul",
          "group":null,
          "type":"candidate"
       }
    ]

    Note that the groupId will always be null, as it's only possible to involve users with a process-instance.

    Add an involved user to a process instance

    POST runtime/process-instances/{processInstanceId}/identitylinks

    Table 15.72. Add an involved user to a process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to the links for.


    Request body:

    {
      "userId":"kermit",
      "type":"participant"
    }

    Both userId and type are required.

    Table 15.73. Add an involved user to a process instance - Response codes

    Response codeDescription
    201Indicates the process instance was found and the link is created.
    400Indicates the requested body did not contain a userId or a type.
    404Indicates the requested process instance was not found.


    Success response body:

    {
       "url":"http://localhost:8182/runtime/process-instances/5/identitylinks/users/john/customType",
       "user":"john",
       "group":null,
       "type":"customType"
    }

    Note that the groupId will always be null, as it's only possible to involve users with a process-instance.

    Remove an involved user to from process instance

    DELETE runtime/process-instances/{processInstanceId}/identitylinks/users/{userId}/{type}

    Table 15.74. Remove an involved user to from process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance.
    userIdYesStringThe id of the user to delete link for.
    typeYesStringType of link to delete.


    Table 15.75. Remove an involved user to from process instance - Response codes

    Response codeDescription
    204Indicates the process instance was found and the link has been deleted. Response body is left empty intentionally.
    404Indicates the requested process instance was not found or the link to delete doesn't exist. The response status contains additional information about the error.


    Success response body:

    {
       "url":"http://localhost:8182/runtime/process-instances/5/identitylinks/users/john/customType",
       "user":"john",
       "group":null,
       "type":"customType"
    }

    Note that the groupId will always be null, as it's only possible to involve users with a process-instance.

    List of variables for a process instance

    GET runtime/process-instances/{processInstanceId}/variables

    Table 15.76. List of variables for a process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to the variables for.


    Table 15.77. List of variables for a process instance - Response codes

    Response codeDescription
    200Indicates the process instance was found and variables are returned.
    404Indicates the requested process instance was not found.


    Success response body:

    [
       {
          "name":"intProcVar",
          "type":"integer",
          "value":123,
          "scope":"local"
       },
       {
          "name":"byteArrayProcVar",
          "type":"binary",
          "value":null,
          "valueUrl":"http://localhost:8182/runtime/process-instances/5/variables/byteArrayProcVar/data",
          "scope":"local"
       },
       
       ...
    ]

    In case the variable is a binary variable or serializable, the valueUrl points to an URL to fetch the raw value. If it's a plain variable, the value is present in the response. Note that only local scoped variables are returned, as there is no global scope for process-instance variables.

    Get a variable for a process instance

    GET runtime/process-instances/{processInstanceId}/variables/{variableName}

    Table 15.78. Get a variable for a process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to the variables for.
    variableNameYesStringName of the variable to get.


    Table 15.79. Get a variable for a process instance - Response codes

    Response codeDescription
    200Indicates both the process instance and variable were found and variable is returned.
    400Indicates the request body is incomplete or contains illegal values. The status description contains additional information about the error.
    404Indicates the requested process instance was not found or the process instance does not have a variable with the given name. Status description contains additional information about the error.


    Success response body:

       {
          "name":"intProcVar",
          "type":"integer",
          "value":123,
          "scope":"local"
       }

    In case the variable is a binary variable or serializable, the valueUrl points to an URL to fetch the raw value. If it's a plain variable, the value is present in the response. Note that only local scoped variables are returned, as there is no global scope for process-instance variables.

    Create (or update) variables on a process instance

    POST runtime/process-instances/{processInstanceId}/variables

    PUT runtime/process-instances/{processInstanceId}/variables

    When using POST, all variables that are passed are created. In case one of the variables already exists on the process instance, the request results in an error (409 - CONFLICT). When PUT is used, unexisting variables are created on the process-instance and existing ones are overridden without any error.

    Table 15.80. Create (or update) variables on a process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to the variables for.


    Request body:

    [
       {
          "name":"intProcVar"
          "type":"integer"
          "value":123
       },
       
       ...
    ]

    Any number of variables can be passed into the request body array. More information about the variable format can be found in the REST variables section. Note that scope is ignored, only local variables can be set in a process instance.

    Table 15.81. Create (or update) variables on a process instance - Response codes

    Response codeDescription
    201Indicates the process instance was found and variable is created.
    400Indicates the request body is incomplete or contains illegal values. The status description contains additional information about the error.
    404Indicates the requested process instance was not found.
    409Indicates the process instance was found but already contains a variable with the given name (only thrown when POST method is used). Use the update-method instead.


    Success response body:

    [
       {
          "name":"intProcVar",
          "type":"integer",
          "value":123,
          "scope":"local"
       },
       
       ...
       
    ]

    Update a single variable on a process instance

    PUT runtime/process-instances/{processInstanceId}/variables/{variableName}

    Table 15.82. Update a single variable on a process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to the variables for.
    variableNameYesStringName of the variable to get.


    Request body:

     {
        "name":"intProcVar"
        "type":"integer"
        "value":123
     }

    More information about the variable format can be found in the REST variables section. Note that scope is ignored, only local variables can be set in a process instance.

    Table 15.83. Update a single variable on a process instance - Response codes

    Response codeDescription
    200Indicates both the process instance and variable were found and variable is updated.
    404Indicates the requested process instance was not found or the process instance does not have a variable with the given name. Status description contains additional information about the error.


    Success response body:

       {
          "name":"intProcVar",
          "type":"integer",
          "value":123,
          "scope":"local"
       }

    In case the variable is a binary variable or serializable, the valueUrl points to an URL to fetch the raw value. If it's a plain variable, the value is present in the response. Note that only local scoped variables are returned, as there is no global scope for process-instance variables.

    Create a new binary variable on a process-instance

    POST runtime/process-instances/{processInstanceId}/variables

    Table 15.84. Create a new binary variable on a process-instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to create the new variable for.


    Request body: The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:

    • name: Required name of the variable.

    • type: Type of variable that is created. If omitted, binary is assumed and the binary data in the request will be stored as an array of bytes.

    Success response body:

    { 
      "name" : "binaryVariable",
      "scope" : "local",
      "type" : "binary",
      "value" : null,
      "valueUrl" : "http://.../runtime/process-instances/123/variables/binaryVariable/data"
    }

    Table 15.85. Create a new binary variable on a process-instance - Response codes

    Response codeDescription
    201Indicates the variable was created and the result is returned.
    400Indicates the name of the variable to create was missing. Status message provides additional information.
    404Indicates the requested process instance was not found.
    409Indicates the process instance already has a variable with the given name. Use the PUT method to update the task variable instead.
    415Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.


    Update an existing binary variable on a process-instance

    PUT runtime/process-instances/{processInstanceId}/variables

    Table 15.86. Update an existing binary variable on a process-instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to create the new variable for.


    Request body: The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:

    • name: Required name of the variable.

    • type: Type of variable that is created. If omitted, binary is assumed and the binary data in the request will be stored as an array of bytes.

    Success response body:

    { 
      "name" : "binaryVariable",
      "scope" : "local",
      "type" : "binary",
      "value" : null,
      "valueUrl" : "http://.../runtime/process-instances/123/variables/binaryVariable/data"
    }

    Table 15.87. Update an existing binary variable on a process-instance - Response codes

    Response codeDescription
    200Indicates the variable was updated and the result is returned.
    400Indicates the name of the variable to update was missing. Status message provides additional information.
    404Indicates the requested process instance was not found or the process instance does not have a variable with the given name.
    415Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.


    Executions

    Get an execution

    GET runtime/executions/{executionId}

    Table 15.88. Get an execution - URL parameters

    ParameterRequiredValueDescription
    executionIdYesStringThe id of the execution to get.


    Table 15.89. Get an execution - Response codes

    Response codeDescription
    200Indicates the execution was found and returned.
    404Indicates the execution was not found.


    Success response body:

    {
       "id":"5",
       "url":"http://localhost:8182/runtime/executions/5",
       "parentId":null,
       "parentUrl":null,
       "processInstanceId":"5",
       "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
       "suspended":false,
       "activityId":null,
       "tenantId": null
    }

    Execute an action on an execution

    PUT runtime/executions/{executionId}

    Table 15.90. Execute an action on an execution - URL parameters

    ParameterRequiredValueDescription
    executionIdYesStringThe id of the execution to execute action on.


    Request body (signal an execution):

    {
      "action":"signal"
    }

    Request body (signal event received for execution):

    {
      "action":"signalEventReceived",
      "signalName":"mySignal"
      "variables": [ ... ]
    }

    Notifies the execution that a signal event has been received, requires a signalName parameter. Optional variables can be passed that are set on the execution before the action is executed.

    Request body (signal event received for execution):

    {
      "action":"messageEventReceived",
      "messageName":"myMessage"
      "variables": [ ... ]
    }

    Notifies the execution that a message event has been received, requires a messageName parameter. Optional variables can be passed that are set on the execution before the action is executed.

    Table 15.91. Execute an action on an execution - Response codes

    Response codeDescription
    200Indicates the execution was found and the action is performed.
    204Indicates the execution was found, the action was performed and the action caused the execution to end.
    400Indicates an illegal action was requested, required parameters are missing in the request body or illegal variables are passed in. Status description contains additional information about the error.
    404Indicates the execution was not found.


    Success response body (in case execution is not ended due to action):

    {
       "id":"5",
       "url":"http://localhost:8182/runtime/executions/5",
       "parentId":null,
       "parentUrl":null,
       "processInstanceId":"5",
       "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
       "suspended":false,
       "activityId":null,
       "tenantId" : null
    }

    Get active activities in an execution

    GET runtime/executions/{executionId}/activities

    Returns all activities which are active in the execution and in all child-executions (and their children, recursively), if any.

    Table 15.92. Get active activities in an execution - URL parameters

    ParameterRequiredValueDescription
    executionIdYesStringThe id of the execution to get activities for.


    Table 15.93. Get active activities in an execution - Response codes

    Response codeDescription
    200Indicates the execution was found and activities are returned.
    404Indicates the execution was not found.


    Success response body:

    [
      "userTaskForManager",
      "receiveTask"
    ]

    List of executions

    GET repository/executions

    Table 15.94. List of executions - URL query parameters

    ParameterRequiredValueDescription
    idNoStringOnly return executions with the given id.
    processDefinitionKeyNoStringOnly return executions with the given process definition key.
    processDefinitionIdNoStringOnly return executions with the given process definition id.
    processInstanceIdNoStringOnly return executions which are part of the process instance with the given id.
    messageEventSubscriptionNameNoStringOnly return executions which are subscribed to a message with the given name.
    signalEventSubscriptionNameNoStringOnly return executions which are subscribed to a signal with the given name.
    parentIdNoStringOnly return executions which are a direct child of the given execution.
    tenantIdNoStringOnly return executions with the given tenantId.
    tenantIdLikeNoStringOnly return executions with a tenantId like the given value.
    withoutTenantIdNoBooleanIf true, only returns executions without a tenantId set. If false, the withoutTenantId parameter is ignored.
    sortNoStringSort field, should be either one of processInstanceId (default), processDefinitionId, processDefinitionKey or tenantId.

    The general paging and sorting query-parameters can be used for this URL.

       


    Table 15.95. List of executions - Response codes

    Response codeDescription
    200Indicates request was successful and the executions are returned
    400Indicates a parameter was passed in the wrong format . The status-message contains additional information.


    Success response body:

    {
       "data":[
          {
             "id":"5",
             "url":"http://localhost:8182/runtime/executions/5",
             "parentId":null,
             "parentUrl":null,
             "processInstanceId":"5",
             "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
             "suspended":false,
             "activityId":null,
             "tenantId":null
          },
          {
             "id":"7",
             "url":"http://localhost:8182/runtime/executions/7",
             "parentId":"5",
             "parentUrl":"http://localhost:8182/runtime/executions/5",
             "processInstanceId":"5",
             "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
             "suspended":false,
             "activityId":"processTask",
             "tenantId":null
          }
       ],
       "total":2,
       "start":0,
       "sort":"processInstanceId",
       "order":"asc",
       "size":2
    }

    Query executions

    POST query/executions

    Request body:

    {
      "processDefinitionKey":"oneTaskProcess",
      "variables": 
      [
        {
            "name" : "myVariable",
            "value" : 1234,
            "operation" : "equals",
            "type" : "long"
        },
        ...
      ],
      "processInstanceVariables": 
      [
        {
            "name" : "processVariable",
            "value" : "some string",
            "operation" : "equals",
            "type" : "string"
        },
        ...
      ],
      ...
    }

    The request body can contain all possible filters that can be used in the List executions URL query. On top of these, it's possible to provide an array of variables and processInstanceVariables to include in the query, with their format described here.

    The general paging and sorting query-parameters can be used for this URL.

    Table 15.96. Query executions - Response codes

    Response codeDescription
    200Indicates request was successful and the executions are returned
    400Indicates a parameter was passed in the wrong format . The status-message contains additional information.


    Success response body:

    {
       "data":[
          {
             "id":"5",
             "url":"http://localhost:8182/runtime/executions/5",
             "parentId":null,
             "parentUrl":null,
             "processInstanceId":"5",
             "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
             "suspended":false,
             "activityId":null,
             "tenantId":null
          },
          {
             "id":"7",
             "url":"http://localhost:8182/runtime/executions/7",
             "parentId":"5",
             "parentUrl":"http://localhost:8182/runtime/executions/5",
             "processInstanceId":"5",
             "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
             "suspended":false,
             "activityId":"processTask",
             "tenantId":null
          }
       ],
       "total":2,
       "start":0,
       "sort":"processInstanceId",
       "order":"asc",
       "size":2
    }

    List of variables for an execution

    GET runtime/executions/{executionId}/variables?scope={scope}

    Table 15.97. List of variables for an execution - URL parameters

    ParameterRequiredValueDescription
    executionIdYesStringThe id of the execution to the variables for.
    scopeNoStringEither local or global. If omitted, both local and global scoped variables are returned.


    Table 15.98. List of variables for an execution - Response codes

    Response codeDescription
    200Indicates the execution was found and variables are returned.
    404Indicates the requested execution was not found.


    Success response body:

    [
       {
          "name":"intProcVar",
          "type":"integer",
          "value":123,
          "scope":"global"
       },
       {
          "name":"byteArrayProcVar",
          "type":"binary",
          "value":null,
          "valueUrl":"http://localhost:8182/runtime/process-instances/5/variables/byteArrayProcVar/data",
          "scope":"local"
       },
       
       ...
    ]

    In case the variable is a binary variable or serializable, the valueUrl points to an URL to fetch the raw value. If it's a plain variable, the value is present in the response.

    Get a variable for an execution

    GET runtime/executions/{executionId}/variables/{variableName}?scope={scope}

    Table 15.99. Get a variable for an execution - URL parameters

    ParameterRequiredValueDescription
    executionIdYesStringThe id of the execution to the variables for.
    variableNameYesStringName of the variable to get.
    scopeNoStringEither local or global. If omitted, local variable is returned (if exists). If not, a global variable is returned (if exists).


    Table 15.100. Get a variable for an execution - Response codes

    Response codeDescription
    200Indicates both the execution and variable were found and variable is returned.
    400Indicates the request body is incomplete or contains illegal values. The status description contains additional information about the error.
    404Indicates the requested execution was not found or the execution does not have a variable with the given name in the requested scope (in case scope-query parameter was omitted, variable doesn't exist in local and global scope). Status description contains additional information about the error.


    Success response body:

       {
          "name":"intProcVar",
          "type":"integer",
          "value":123,
          "scope":"local"
       }

    In case the variable is a binary variable or serializable, the valueUrl points to an URL to fetch the raw value. If it's a plain variable, the value is present in the response.

    Create (or update) variables on an execution

    POST runtime/executions/{executionId}/variables

    PUT runtime/executions/{executionId}/variables

    When using POST, all variables that are passed are created. In case one of the variables already exists on the execution in the requested scope, the request results in an error (409 - CONFLICT). When PUT is used, unexisting variables are created on the execution and existing ones are overridden without any error.

    Table 15.101. Create (or update) variables on an execution - URL parameters

    ParameterRequiredValueDescription
    executionIdYesStringThe id of the execution to the variables for.


    Request body:

    [
       {
          "name":"intProcVar"
          "type":"integer"
          "value":123,
          "scope":"local"
       },
       
       ...
    ]

    Note that you can only provide variables that have the same scope. If the request-body array contains variables from mixed scopes, the request results in an error (400 - BAD REQUEST).Any number of variables can be passed into the request body array. More information about the variable format can be found in the REST variables section. Note that scope is ignored, only local variables can be set in a process instance.

    Table 15.102. Create (or update) variables on an execution - Response codes

    Response codeDescription
    201Indicates the execution was found and variable is created.
    400Indicates the request body is incomplete or contains illegal values. The status description contains additional information about the error.
    404Indicates the requested execution was not found.
    409Indicates the execution was found but already contains a variable with the given name (only thrown when POST method is used). Use the update-method instead.


    Success response body:

    [
       {
          "name":"intProcVar",
          "type":"integer",
          "value":123,
          "scope":"local"
       },
       
       ...
       
    ]

    Update a variable on an execution

    PUT runtime/executions/{executionId}/variables/{variableName}

    Table 15.103. Update a variable on an execution - URL parameters

    ParameterRequiredValueDescription
    executionIdYesStringThe id of the execution to update the variables for.
    variableNameYesStringName of the variable to update.


    Request body:

     {
        "name":"intProcVar"
        "type":"integer"
        "value":123,
        "scope":"global"
     }

    More information about the variable format can be found in the REST variables section.

    Table 15.104. Update a variable on an execution - Response codes

    Response codeDescription
    200Indicates both the process instance and variable were found and variable is updated.
    404Indicates the requested process instance was not found or the process instance does not have a variable with the given name. Status description contains additional information about the error.


    Success response body:

       {
          "name":"intProcVar",
          "type":"integer",
          "value":123,
          "scope":"global"
       }

    In case the variable is a binary variable or serializable, the valueUrl points to an URL to fetch the raw value. If it's a plain variable, the value is present in the response.

    Create a new binary variable on an execution

    POST runtime/executions/{executionId}/variables

    Table 15.105. Create a new binary variable on an execution - URL parameters

    ParameterRequiredValueDescription
    executionIdYesStringThe id of the execution to create the new variable for.


    Request body: The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:

    • name: Required name of the variable.

    • type: Type of variable that is created. If omitted, binary is assumed and the binary data in the request will be stored as an array of bytes.

    • scope: Scope of variable that is created. If omitted, local is assumed.

    Success response body:

    { 
      "name" : "binaryVariable",
      "scope" : "local",
      "type" : "binary",
      "value" : null,
      "valueUrl" : "http://.../runtime/executions/123/variables/binaryVariable/data"
    }

    Table 15.106. Create a new binary variable on an execution - Response codes

    Response codeDescription
    201Indicates the variable was created and the result is returned.
    400Indicates the name of the variable to create was missing. Status message provides additional information.
    404Indicates the requested execution was not found.
    409Indicates the execution already has a variable with the given name. Use the PUT method to update the task variable instead.
    415Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.


    Update an existing binary variable on a process-instance

    PUT runtime/executions/{executionId}/variables/{variableName}

    Table 15.107. Update an existing binary variable on a process-instance - URL parameters

    ParameterRequiredValueDescription
    executionIdYesStringThe id of the execution to create the new variable for.
    variableNameYesStringThe name of the variable to update.


    Request body: The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:

    • name: Required name of the variable.

    • type: Type of variable that is created. If omitted, binary is assumed and the binary data in the request will be stored as an array of bytes.

    • scope: Scope of variable that is created. If omitted, local is assumed.

    Success response body:

    { 
      "name" : "binaryVariable",
      "scope" : "local",
      "type" : "binary",
      "value" : null,
      "valueUrl" : "http://.../runtime/executions/123/variables/binaryVariable/data"
    }

    Table 15.108. Update an existing binary variable on a process-instance - Response codes

    Response codeDescription
    200Indicates the variable was updated and the result is returned.
    400Indicates the name of the variable to update was missing. Status message provides additional information.
    404Indicates the requested execution was not found or the execution does not have a variable with the given name.
    415Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.


    Tasks

    Get a task

    GET runtime/tasks/{taskId}

    Table 15.109. Get a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get.


    Table 15.110. Get a task - Response codes

    Response codeDescription
    200Indicates the task was found and returned.
    404Indicates the requested task was not found.


    Success response body:

    { 
      "assignee" : "kermit",
      "createTime" : "2013-04-17T10:17:43.902+0000",
      "delegationState" : "pending",
      "description" : "Task description",
      "dueDate" : "2013-04-17T10:17:43.902+0000",
      "execution" : "http://localhost:8182/runtime/executions/5",
      "id" : "8",
      "name" : "My task",
      "owner" : "owner",
      "parentTask" : "http://localhost:8182/runtime/tasks/9",
      "priority" : 50,
      "processDefinition" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
      "processInstance" : "http://localhost:8182/runtime/process-instances/5",
      "suspended" : false,
      "taskDefinitionKey" : "theTask",
      "url" : "http://localhost:8182/runtime/tasks/8",
      "tenantId" : null
    }

    • delegationState: Delegation-state of the task, can be null, "pending" or "resolved".

    List of tasks

    GET runtime/tasks

    Table 15.111. List of tasks - URL query parameters

    ParameterRequiredValueDescription
    nameNoStringOnly return tasks with the given name.
    nameLikeNoStringOnly return tasks with a name like the given name.
    descriptionNoStringOnly return tasks with the given description.
    priorityNoIntegerOnly return tasks with the given priotiry.
    minimumPriorityNoIntegerOnly return tasks with a priority greater than the given value.
    maximumPriorityNoIntegerOnly return tasks with a priority lower than the given value.
    assigneeNoStringOnly return tasks assigned to the given user.
    assigneeLikeNoStringOnly return tasks assigned with an assignee like the given value.
    ownerNoStringOnly return tasks owned by the given user.
    ownerLikeNoStringOnly return tasks assigned with an owner like the given value.
    unassignedNoBooleanOnly return tasks that are not assigned to anyone. If false is passed, the value is ignored.
    delegationStateNoStringOnly return tasks that have the given delegation state. Possible values are pending and resolved.
    candidateUserNoStringOnly return tasks that can be claimed by the given user. This includes both tasks where the user is an explicit candidate for and task that are claimable by a group that the user is a member of.
    candidateGroupNoStringOnly return tasks that can be claimed by a user in the given group.
    involvedUserNoStringOnly return tasks in which the given user is involved.
    taskDefinitionKeyNoStringOnly return tasks with the given task definition id.
    taskDefinitionKeyLikeNoStringOnly return tasks with a given task definition id like the given value.
    processInstanceIdNoStringOnly return tasks which are part of the process instance with the given id.
    processInstanceBusinessKeyNoStringOnly return tasks which are part of the process instance with the given business key.
    processInstanceBusinessKeyLikeNoStringOnly return tasks which are part of the process instance which has a business key like the given value.
    processDefinitionKeyNoStringOnly return tasks which are part of a process instance which has a process definition with the given key.
    processDefinitionKeyLikeNoStringOnly return tasks which are part of a process instance which has a process definition with a key like the given value.
    processDefinitionNameNoStringOnly return tasks which are part of a process instance which has a process definition with the given name.
    processDefinitionNameLikeNoStringOnly return tasks which are part of a process instance which has a process definition with a name like the given value.
    executionIdNoStringOnly return tasks which are part of the execution with the given id.
    createdOnNoISO DateOnly return tasks which are created on the given date.
    createdBeforeNoISO DateOnly return tasks which are created before the given date.
    createdAfterNoISO DateOnly return tasks which are created after the given date.
    dueOnNoISO DateOnly return tasks which are due on the given date.
    dueBeforeNoISO DateOnly return tasks which are due before the given date.
    dueAfterNoISO DateOnly return tasks which are due after the given date.
    withoutDueDateNobooleanOnly return tasks which don't have a due date. The property is ignored if the value is false.
    withoutDueDateNobooleanOnly return tasks which don't have a due date. The property is ignored if the value is false.
    withoutDueDateNobooleanOnly return tasks which don't have a due date. The property is ignored if the value is false.
    excludeSubTasksNoBooleanOnly return tasks that are not a subtask of another task.
    activeNoBooleanIf true, only return tasks that are not suspended (either part of a process that is not suspended or not part of a process at all). If false, only tasks that are part of suspended process instances are returned.
    includeTaskLocalVariablesNoBooleanIndication to include task local variables in the result.
    includeProcessVariablesNoBooleanIndication to include process variables in the result.
    tenantIdNoStringOnly return tasks with the given tenantId.
    tenantIdLikeNoStringOnly return tasks with a tenantId like the given value.
    withoutTenantIdNoBooleanIf true, only returns tasks without a tenantId set. If false, the withoutTenantId parameter is ignored.

    The general paging and sorting query-parameters can be used for this URL.

       


    Table 15.112. List of tasks - Response codes

    Response codeDescription
    200Indicates request was successful and the tasks are returned
    400Indicates a parameter was passed in the wrong format or that 'delegationState' has an invalid value (other than 'pending' and 'resolved'). The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "assignee" : "kermit",
          "createTime" : "2013-04-17T10:17:43.902+0000",
          "delegationState" : "pending",
          "description" : "Task description",
          "dueDate" : "2013-04-17T10:17:43.902+0000",
          "execution" : "http://localhost:8182/runtime/executions/5",
          "id" : "8",
          "name" : "My task",
          "owner" : "owner",
          "parentTask" : "http://localhost:8182/runtime/tasks/9",
          "priority" : 50,
          "processDefinition" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
          "processInstance" : "http://localhost:8182/runtime/process-instances/5",
          "suspended" : false,
          "taskDefinitionKey" : "theTask",
          "url" : "http://localhost:8182/runtime/tasks/8",
          "tenantId" : null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Query for tasks

    POST query/tasks

    Request body:

    {
      "name" : "My task",
      "description" : "The task description",
      
      ...
      
      "taskVariables" : [
        {
          "name" : "myVariable",
          "value" : 1234,
          "operation" : "equals",
          "type" : "long"
        }
      ],
        
        "processInstanceVariables" : [
          {
             ... 
          }
        ]
      ]
    }

    All supported JSON parameter fields allowed are exactly the same as the parameters found for getting a collection of tasks, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri's that are too long. On top of that, the query allows for filtering based on task and process variables. The taskVariables and processInstanceVariables are both json-arrays containing objects with the format as described here.

    Table 15.113. Query for tasks - Response codes

    Response codeDescription
    200Indicates request was successful and the tasks are returned
    400Indicates a parameter was passed in the wrong format or that 'delegationState' has an invalid value (other than 'pending' and 'resolved'). The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "assignee" : "kermit",
          "createTime" : "2013-04-17T10:17:43.902+0000",
          "delegationState" : "pending",
          "description" : "Task description",
          "dueDate" : "2013-04-17T10:17:43.902+0000",
          "execution" : "http://localhost:8182/runtime/executions/5",
          "id" : "8",
          "name" : "My task",
          "owner" : "owner",
          "parentTask" : "http://localhost:8182/runtime/tasks/9",
          "priority" : 50,
          "processDefinition" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
          "processInstance" : "http://localhost:8182/runtime/process-instances/5",
          "suspended" : false,
          "taskDefinitionKey" : "theTask",
          "url" : "http://localhost:8182/runtime/tasks/8",
          "tenantId" : null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Update a task

    PUT runtime/tasks/{taskId}

    Body JSON:

    { 
      "assignee" : "assignee",
      "delegationState" : "resolved",
      "description" : "New task description",
      "dueDate" : "2013-04-17T13:06:02.438+02:00",
      "name" : "New task name",
      "owner" : "owner",
      "parentTaskId" : "3",
      "priority" : 20
    }

    All request values are optional. For example, you can only include the 'assignee' attribute in the request body JSON-object, only updating the assignee of the task, leaving all other fields unaffected. When an attribute is explicitly included and is set to null, the task-value will be updated to null. Example: {"dueDate" : null} will clear the duedate of the task).

    Table 15.114. Update a task - Response codes

    Response codeDescription
    200Indicates the task was updated.
    404Indicates the requested task was not found.
    409Indicates the requested task was updated simultaneously.


    Success response body: see response for runtime/tasks/{taskId}.

    Task actions

    POST runtime/tasks/{taskId}

    Complete a task - Body JSON:

    { 
      "action" : "complete",
      "variables" : ...
    }

    Completes the task. Optional variable array can be passed in using the variables property. More information about the variable format can be found in the REST variables section. Note that the variable-scope that is supplied is ignored and the variables are set on the parent-scope unless a variable exists in a local scope, which is overridden in this case. This is the same behavior as the TaskService.completeTask(taskId, variables) invocation.

    Claim a task - Body JSON:

    { 
      "action" : "claim",
      "assignee" : "userWhoClaims"
    }

    Claims the task by the given assignee. If the assignee is null, the task is assigned to no-one, claimable agian.

    Delegate a task - Body JSON:

    { 
      "action" : "delegate",
      "assignee" : "userToDelegateTo"
    }

    Delegates the task to the given assignee. The assignee is required.

    Resolve a task - Body JSON:

    { 
      "action" : "resolve"
    }

    Resolves the task delegation. The task is assigned back to the task owner (if any).

    Table 15.115. Task actions - Response codes

    Response codeDescription
    200Indicates the action was executed.
    400When the body contains an invalid value or when the assignee is missing when the action requires it.
    404Indicates the requested task was not found.
    409Indicates the action cannot be performed due to a conflict. Either the task was updates simultaneously or the task was claimed by another user, in case of the 'claim' action.


    Success response body: see response for runtime/tasks/{taskId}.

    Delete a task

    DELETE runtime/tasks/{taskId}?cascadeHistory={cascadeHistory}&deleteReason={deleteReason}

    Table 15.116. >Delete a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to delete.
    cascadeHistoryFalseBooleanWhether or not to delete the HistoricTask instance when deleting the task (if applicable). If not provided, this value defaults to false.
    deleteReasonFalseStringReason why the task is deleted. This value is ignored when cascadeHistory is true.


    Table 15.117. >Delete a task - Response codes

    Response codeDescription
    204Indicates the task was found and has been deleted. Response-body is intentionally empty.
    403Indicates the requested task cannot be deleted because it's part of a workflow.
    404Indicates the requested task was not found.


    Get all variables for a task

    GET runtime/tasks/{taskId}/variables?scope={scope}

    Table 15.118. Get all variables for a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get variables for.
    scopeFalseStringScope of variables to be returned. When 'local', only task-local variables are returned. When 'global', only variables from the task's parent execution-hierarchy are returned. When the parameter is omitted, both local and global variables are returned.


    Table 15.119. Get all variables for a task - Response codes

    Response codeDescription
    200Indicates the task was found and the requested variables are returned.
    404Indicates the requested task was not found.


    Success response body:

    [
      { 
        "name" : "doubleTaskVar",
        "scope" : "local",
        "type" : "double",
        "value" : 99.99
      },
      {
        "name" : "stringProcVar",
        "scope" : "global",
        "type" : "string",
        "value" : "This is a ProcVariable"
      },
      
      ...
      
    ]

    The variables are returned as a JSON array. Full response description can be found in the general REST-variables section.

    Get a variable from a task

    GET runtime/tasks/{taskId}/variables/{variableName}?scope={scope}

    Table 15.120. Get a variable from a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get a variable for.
    variableNameYesStringThe name of the variable to get.
    scopeFalseStringScope of variable to be returned. When 'local', only task-local variable value is returned. When 'global', only variable value from the task's parent execution-hierarchy are returned. When the parameter is omitted, a local variable will be returned if it exists, otherwise a global variable.


    Table 15.121. Get a variable from a task - Response codes

    Response codeDescription
    200Indicates the task was found and the requested variables are returned.
    404Indicates the requested task was not found or the task doesn't have a variable with the given name (in the given scope). Status message provides additional information.


    Success response body:

    { 
      "name" : "myTaskVariable",
      "scope" : "local",
      "type" : "string",
      "value" : "Hello my friend"
    }

    Full response body description can be found in the general REST-variables section.

    Get the binary data for a variable

    GET runtime/tasks/{taskId}/variables/{variableName}/data?scope={scope}

    Table 15.122. Get the binary data for a variable - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get a variable data for.
    variableNameYesStringThe name of the variable to get data for. Only variables of type binary and serializable can be used. If any other type of variable is used, a 404 is returned.
    scopeFalseStringScope of variable to be returned. When 'local', only task-local variable value is returned. When 'global', only variable value from the task's parent execution-hierarchy are returned. When the parameter is omitted, a local variable will be returned if it exists, otherwise a global variable.


    Table 15.123. Get the binary data for a variable - Response codes

    Response codeDescription
    200Indicates the task was found and the requested variables are returned.
    404Indicates the requested task was not found or the task doesn't have a variable with the given name (in the given scope) or the variable doesn't have a binary stream available. Status message provides additional information.


    Success response body: The response body contains the binary value of the variable. When the variable is of type binary, the content-type of the response is set to application/octet-stream, regardless of the content of the variable or the request accept-type header. In case of serializable, application/x-java-serialized-object is used as content-type.

    Create new variables on a task

    POST runtime/tasks/{taskId}/variables

    Table 15.124. Create new variables on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to create the new variable for.


    Request body for creating simple (non-binary) variables:

    [
      { 
        "name" : "myTaskVariable",
        "scope" : "local",
        "type" : "string",
        "value" : "Hello my friend"
      },
      {
        ...
      }
    ]

    The request body should be an array containing one or more JSON-objects representing the variables that should be created.

    • name: Required name of the variable

    • scope: Scope of variable that is created. If omitted, local is assumed.

    • type: Type of variable that is created. If omitted, reverts to raw JSON-value type (string, boolean, integer or double).

    • value: Variable value.

    More information about the variable format can be found in the REST variables section.

    Success response body:

    [
      { 
        "name" : "myTaskVariable",
        "scope" : "local",
        "type" : "string",
        "value" : "Hello my friend"
      },
      {
        ...
      }
    ]

    Table 15.125. Create new variables on a task - Response codes

    Response codeDescription
    201Indicates the variables were created and the result is returned.
    400Indicates the name of a variable to create was missing or that an attempt is done to create a variable on a standalone task (without a process associated) with scope global or an empty array of variables was included in the request or request did not contain an array of variables. Status message provides additional information.
    404Indicates the requested task was not found.
    409Indicates the task already has a variable with the given name. Use the PUT method to update the task variable instead.


    Create a new binary variable on a task

    POST runtime/tasks/{taskId}/variables

    Table 15.126. Create a new binary variable on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to create the new variable for.


    Request body: The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:

    • name: Required name of the variable.

    • scope: Scope of variable that is created. If omitted, local is assumed.

    • type: Type of variable that is created. If omitted, binary is assumed and the binary data in the request will be stored as an array of bytes.

    Success response body:

    { 
      "name" : "binaryVariable",
      "scope" : "local",
      "type" : "binary",
      "value" : null,
      "valueUrl" : "http://.../runtime/tasks/123/variables/binaryVariable/data"
    }

    Table 15.127. Create a new binary variable on a task - Response codes

    Response codeDescription
    201Indicates the variable was created and the result is returned.
    400Indicates the name of the variable to create was missing or that an attempt is done to create a variable on a standalone task (without a process associated) with scope global. Status message provides additional information.
    404Indicates the requested task was not found.
    409Indicates the task already has a variable with the given name. Use the PUT method to update the task variable instead.
    415Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.


    Update an existing variable on a task

    PUT runtime/tasks/{taskId}/variables/{variableName}

    Table 15.128. Update an existing variable on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to update the variable for.
    variableNameYesStringThe name of the variable to update.


    Request body for updating simple (non-binary) variables:

    { 
      "name" : "myTaskVariable",
      "scope" : "local",
      "type" : "string",
      "value" : "Hello my friend"
    }

    • name: Required name of the variable

    • scope: Scope of variable that is updated. If omitted, local is assumed.

    • type: Type of variable that is updated. If omitted, reverts to raw JSON-value type (string, boolean, integer or double).

    • value: Variable value.

    More information about the variable format can be found in the REST variables section.

    Success response body:

    { 
      "name" : "myTaskVariable",
      "scope" : "local",
      "type" : "string",
      "value" : "Hello my friend"
    }

    Table 15.129. Update an existing variable on a task - Response codes

    Response codeDescription
    200Indicates the variables was updated and the result is returned.
    400Indicates the name of a variable to update was missing or that an attempt is done to update a variable on a standalone task (without a process associated) with scope global. Status message provides additional information.
    404Indicates the requested task was not found or the task doesn't have a variable with the given name in the given scope. Status message contains additional information about the error.


    Updating a binary variable on a task

    PUT runtime/tasks/{taskId}/variables/{variableName}

    Table 15.130. Updating a binary variable on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to update the variable for.
    variableNameYesStringThe name of the variable to update.


    Request body: The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:

    • name: Required name of the variable.

    • scope: Scope of variable that is updated. If omitted, local is assumed.

    • type: Type of variable that is updated. If omitted, binary is assumed and the binary data in the request will be stored as an array of bytes.

    Success response body:

    { 
      "name" : "binaryVariable",
      "scope" : "local",
      "type" : "binary",
      "value" : null,
      "valueUrl" : "http://.../runtime/tasks/123/variables/binaryVariable/data"
    }

    Table 15.131. Updating a binary variable on a task - Response codes

    Response codeDescription
    200Indicates the variable was updated and the result is returned.
    400Indicates the name of the variable to update was missing or that an attempt is done to update a variable on a standalone task (without a process associated) with scope global. Status message provides additional information.
    404Indicates the requested task was not found or the variable to update doesn't exist for the given task in the given scope.
    415Indicates the serializable data contains an object for which no class is present in the JVM running the Activiti engine and therefore cannot be deserialized.


    Delete a variable on a task

    DELETE runtime/tasks/{taskId}/variables/{variableName}?scope={scope}

    Table 15.132. Delete a variable on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task the variable to delete belongs to.
    variableNameYesStringThe name of the variable to delete.
    scopeNoStringScope of variable to delete in. Can be either local or global. If omitted, local is assumed.


    Table 15.133. Delete a variable on a task - Response codes

    Response codeDescription
    204Indicates the task variable was found and has been deleted. Response-body is intentionally empty.
    404Indicates the requested task was not found or the task doesn't have a variable with the given name. Status message contains additional information about the error.


    Delete all local variables on a task

    DELETE runtime/tasks/{taskId}/variables

    Table 15.134. Delete all local variables on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task the variable to delete belongs to.


    Table 15.135. Delete all local variables on a task - Response codes

    Response codeDescription
    204Indicates all local task variables have been deleted. Response-body is intentionally empty.
    404Indicates the requested task was not found.


    Get all identity links for a task

    GET runtime/tasks/{taskId}/identitylinks

    Table 15.136. Get all identity links for a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get the identity links for.


    Table 15.137. Get all identity links for a task - Response codes

    Response codeDescription
    200Indicates the task was found and the requested identity links are returned.
    404Indicates the requested task was not found.


    Success response body:

    [
      { 
        "userId" : "kermit",
        "groupId" : null,
        "type" : "candidate",
        "url" : "http://localhost:8081/activiti-rest/service/runtime/tasks/100/identitylinks/users/kermit/candidate"
      },
      {
        "userId" : null,
        "groupId" : "sales",
        "type" : "candidate",
        "url" : "http://localhost:8081/activiti-rest/service/runtime/tasks/100/identitylinks/groups/sales/candidate"
      },
      
      ...
    ]

    Get all identitylinks for a task for either groups or users

    GET runtime/tasks/{taskId}/identitylinks/users
    GET runtime/tasks/{taskId}/identitylinks/groups

    Returns only identity links targetting either users or groups. Response body and status-codes are exactly the same as when getting the full list of identity links for a task.

    Get a single identity link on a task

    GET runtime/tasks/{taskId}/identitylinks/{family}/{identityId}/{type}

    Table 15.138. Get all identitylinks for a task for either groups or users - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task .
    familyYesStringEither groups or users, depending on what kind of identity is targetted.
    identityIdYesStringThe id of the identity.
    typeYesStringThe type of identity link.


    Table 15.139. Get all identitylinks for a task for either groups or users - Response codes

    Response codeDescription
    200Indicates the task and identity link was found and returned.
    404Indicates the requested task was not found or the task doesn't have the requested identityLink. The status contains additional information about this error.


    Success response body:

    {
      "userId" : null,
      "groupId" : "sales",
      "type" : "candidate",
      "url" : "http://localhost:8081/activiti-rest/service/runtime/tasks/100/identitylinks/groups/sales/candidate"
    }

    Create an identity link on a task

    POST runtime/tasks/{taskId}/identitylinks

    Table 15.140. Create an identity link on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task .


    Request body (user):

    {
      "userId" : "kermit",
      "type" : "candidate",
    }

    Request body (group):

    {
      "groupId" : "sales",
      "type" : "candidate",
    }

    Table 15.141. Create an identity link on a task - Response codes

    Response codeDescription
    201Indicates the task was found and the identity link was created.
    404Indicates the requested task was not found or the task doesn't have the requested identityLink. The status contains additional information about this error.


    Success response body:

    {
      "userId" : null,
      "groupId" : "sales",
      "type" : "candidate",
      "url" : "http://localhost:8081/activiti-rest/service/runtime/tasks/100/identitylinks/groups/sales/candidate"
    }

    Delete an identity link on a task

    DELETE runtime/tasks/{taskId}/identitylinks/{family}/{identityId}/{type}

    Table 15.142. Delete an identity link on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task.
    familyYesStringEither groups or users, depending on what kind of identity is targetted.
    identityIdYesStringThe id of the identity.
    typeYesStringThe type of identity link.


    Table 15.143. Delete an identity link on a task - Response codes

    Response codeDescription
    204Indicates the task and identity link were found and the link has been deleted. Response-body is intentionally empty.
    404Indicates the requested task was not found or the task doesn't have the requested identityLink. The status contains additional information about this error.


    Create a new comment on a task

    POST runtime/tasks/{taskId}/comments

    Table 15.144. Create a new comment on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to create the comment for.


    Request body:

    { 
      "message" : "This is a comment on the task."
    }

    Success response body:

    { 
      "id" : "123",
      "url" : "http://localhost:8081/activiti-rest/service/runtime/tasks/100/comments/123",
      "message" : "This is a comment on the task.",
      "author" : "kermit"
    }

    Table 15.145. Create a new comment on a task - Response codes

    Response codeDescription
    201Indicates the comment was created and the result is returned.
    400Indicates the comment is missing from the request.
    404Indicates the requested task was not found.


    Get all comments on a task

    GET runtime/tasks/{taskId}/comments

    Table 15.146. Get all comments on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get the comments for.


    Success response body:

    [
      { 
        "id" : "123",
        "url" : "http://localhost:8081/activiti-rest/service/runtime/tasks/100/comments/123",
        "message" : "This is a comment on the task.",
        "author" : "kermit"
      },
      { 
        "id" : "456",
        "url" : "http://localhost:8081/activiti-rest/service/runtime/tasks/100/comments/456",
        "message" : "This is another comment on the task.",
        "author" : "gonzo"
      }
    ]

    Table 15.147. Get all comments on a task - Response codes

    Response codeDescription
    200Indicates the task was found and the comments are returned.
    404Indicates the requested task was not found.


    Get a comment on a task

    GET runtime/tasks/{taskId}/comments/{commentId}

    Table 15.148. Get a comment on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get the comment for.
    commentIdYesStringThe id of the comment.


    Success response body:

    { 
      "id" : "123",
      "url" : "http://localhost:8081/activiti-rest/service/runtime/tasks/100/comments/123",
      "message" : "This is a comment on the task.",
      "author" : "kermit"
    }

    Table 15.149. Get a comment on a task - Response codes

    Response codeDescription
    200Indicates the task and comment were found and the comment is returned.
    404Indicates the requested task was not found or the tasks doesn't have a comment with the given ID.


    Delete a comment on a task

    DELETE runtime/tasks/{taskId}/comments/{commentId}

    Table 15.150. Delete a comment on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to delete the comment for.
    commentIdYesStringThe id of the comment.


    Table 15.151. Delete a comment on a task - Response codes

    Response codeDescription
    204Indicates the task and comment were found and the comment is deleted. Response body is left empty intentionally.
    404Indicates the requested task was not found or the tasks doesn't have a comment with the given ID.

    Get all events for a task

    GET runtime/tasks/{taskId}/events

    Table 15.152. Get all events for a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get the events for.


    Success response body:

    [
      { 
        "action" : "AddUserLink",
        "id" : "4",
        "message" : [ "gonzo", "contributor" ],
        "taskUrl" : "http://localhost:8182/runtime/tasks/2",
        "time" : "2013-05-17T11:50:50.000+0000",
        "url" : "http://localhost:8182/runtime/tasks/2/events/4",
        "userId" : null
      },
      
      ...
    
    ]

    Table 15.153. Get all events for a task - Response codes

    Response codeDescription
    200Indicates the task was found and the events are returned.
    404Indicates the requested task was not found.


    Get an event on a task

    GET runtime/tasks/{taskId}/events/{eventId}

    Table 15.154. Get an event on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get the event for.
    eventIdYesStringThe id of the event.


    Success response body:

    { 
      "action" : "AddUserLink",
      "id" : "4",
      "message" : [ "gonzo", "contributor" ],
      "taskUrl" : "http://localhost:8182/runtime/tasks/2",
      "time" : "2013-05-17T11:50:50.000+0000",
      "url" : "http://localhost:8182/runtime/tasks/2/events/4",
      "userId" : null
    }

    Table 15.155. Get an event on a task - Response codes

    Response codeDescription
    200Indicates the task and event were found and the event is returned.
    404Indicates the requested task was not found or the tasks doesn't have an event with the given ID.


    Create a new attachment on a task, containing a link to an external resource

    POST runtime/tasks/{taskId}/attachments

    Table 15.156. Create a new attachment on a task, containing a link to an external resource - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to create the attachment for.


    Request body:

    { 
      "name":"Simple attachment",
      "description":"Simple attachment description",
      "type":"simpleType",
      "externalUrl":"http://activiti.org"
    }

    Only the attachment name is required to create a new attachment.

    Success response body:

    {
      "id":"3",
      "url":"http://localhost:8182/runtime/tasks/2/attachments/3",
      "name":"Simple attachment",
      "description":"Simple attachment description",
      "type":"simpleType",
      "taskUrl":"http://localhost:8182/runtime/tasks/2",
      "processInstanceUrl":null,
      "externalUrl":"http://activiti.org",
      "contentUrl":null
    }

    Table 15.157. Create a new attachment on a task, containing a link to an external resource - Response codes

    Response codeDescription
    201Indicates the attachment was created and the result is returned.
    400Indicates the attachment name is missing from the request.
    404Indicates the requested task was not found.


    Create a new attachment on a task, with an attached file

    POST runtime/tasks/{taskId}/attachments

    Table 15.158. Create a new attachment on a task, with an attached file - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to create the attachment for.


    Request body: The request should be of type multipart/form-data. There should be a single file-part included with the binary value of the variable. On top of that, the following additional form-fields can be present:

    • name: Required name of the variable.

    • description: Description of the attachment, optional.

    • type: Type of attachment, optional. Supports any arbitrary string or a valid HTTP content-type.

    Success response body:

    {
          "id":"5",
          "url":"http://localhost:8182/runtime/tasks/2/attachments/5",
          "name":"Binary attachment",
          "description":"Binary attachment description",
          "type":"binaryType",
          "taskUrl":"http://localhost:8182/runtime/tasks/2",
          "processInstanceUrl":null,
          "externalUrl":null,
          "contentUrl":"http://localhost:8182/runtime/tasks/2/attachments/5/content"
       }

    Table 15.159. Create a new attachment on a task, with an attached file - Response codes

    Response codeDescription
    201Indicates the attachment was created and the result is returned.
    400Indicates the attachment name is missing from the request or no file was present in the request. The error-message contains additional information.
    404Indicates the requested task was not found.


    Get all attachments on a task

    GET runtime/tasks/{taskId}/attachments

    Table 15.160. Get all attachments on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get the attachments for.


    Success response body:

    [
      {
        "id":"3",
        "url":"http://localhost:8182/runtime/tasks/2/attachments/3",
        "name":"Simple attachment",
        "description":"Simple attachment description",
        "type":"simpleType",
        "taskUrl":"http://localhost:8182/runtime/tasks/2",
        "processInstanceUrl":null,
        "externalUrl":"http://activiti.org",
        "contentUrl":null
      },
      {
        "id":"5",
        "url":"http://localhost:8182/runtime/tasks/2/attachments/5",
        "name":"Binary attachment",
        "description":"Binary attachment description",
        "type":"binaryType",
        "taskUrl":"http://localhost:8182/runtime/tasks/2",
        "processInstanceUrl":null,
        "externalUrl":null,
        "contentUrl":"http://localhost:8182/runtime/tasks/2/attachments/5/content"
      }
    ]

    Table 15.161. Get all attachments on a task - Response codes

    Response codeDescription
    200Indicates the task was found and the attachments are returned.
    404Indicates the requested task was not found.


    Get an attachment on a task

    GET runtime/tasks/{taskId}/attachments/{attachmentId}

    Table 15.162. Get an attachment on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get the attachment for.
    attachmentIdYesStringThe id of the attachment.


    Success response body:

      {
        "id":"5",
        "url":"http://localhost:8182/runtime/tasks/2/attachments/5",
        "name":"Binary attachment",
        "description":"Binary attachment description",
        "type":"binaryType",
        "taskUrl":"http://localhost:8182/runtime/tasks/2",
        "processInstanceUrl":null,
        "externalUrl":null,
        "contentUrl":"http://localhost:8182/runtime/tasks/2/attachments/5/content"
      }

    • externalUrl - contentUrl:In case the attachment is a link to an external resource, the externalUrl contains the URL to the external content. If the attachment content is present in the Activiti engine, the contentUrl will contain an URL where the binary content can be streamed from.

    • type:Can be any arbitrary value. When a valid formatted media-type (eg. application/xml, text/plain) is included, the binary content HTTP response content-type will be set the the given value.

    Table 15.163. Get an attachment on a task - Response codes

    Response codeDescription
    200Indicates the task and attachment were found and the attachment is returned.
    404Indicates the requested task was not found or the tasks doesn't have a attachment with the given ID.


    Get the content for an attachment

    GET runtime/tasks/{taskId}/attachment/{attachmentId}/content

    Table 15.164. Get the content for an attachment - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to get a variable data for.
    attachmentIdYesStringThe id of the attachment, a 404 is returned when the attachment points to an external URL rather than content attached in Activiti.


    Table 15.165. Get the content for an attachment - Response codes

    Response codeDescription
    200Indicates the task and attachment was found and the requested content is returned.
    404Indicates the requested task was not found or the task doesn't have an attachment with the given id or the attachment doesn't have a binary stream available. Status message provides additional information.


    Success response body: The response body contains the binary content. By default, the content-type of the response is set to application/octet-stream unless the attachment type contains a valid Content-type.

    Delete an attachment on a task

    DELETE runtime/tasks/{taskId}/attachments/{attachmentId}

    Table 15.166. Delete an attachment on a task - URL parameters

    ParameterRequiredValueDescription
    taskIdYesStringThe id of the task to delete the attachment for.
    attachmentIdYesStringThe id of the attachment.


    Table 15.167. Delete an attachment on a task - Response codes

    Response codeDescription
    204Indicates the task and attachment were found and the attachment is deleted. Response body is left empty intentionally.
    404Indicates the requested task was not found or the tasks doesn't have a attachment with the given ID.

    History

    Get a historic process instance

    GET history/historic-process-instances/{processInstanceId}

    Table 15.168. Get a historic process instance - Response codes

    Response codeDescription
    200Indicates that the historic process instances could be found.
    404Indicates that the historic process instances could not be found.


    Success response body:

    {
      "data": [
        { 
          "id" : "5",
          "businessKey" : "myKey",
          "processDefinitionId" : "oneTaskProcess%3A1%3A4",
          "processDefinitionUrl" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
          "startTime" : "2013-04-17T10:17:43.902+0000",
          "endTime" : "2013-04-18T14:06:32.715+0000",
          "durationInMillis" : 86400056,
          "startUserId" : "kermit",
          "startActivityId" : "startEvent",
          "endActivityId" : "endEvent",
          "deleteReason" : null,
          "superProcessInstanceId" : "3",
          "url" : "http://localhost:8182/history/historic-process-instances/5",
          "variables": null,
          "tenantId":null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    List of historic process instances

    GET history/historic-process-instances

    Table 15.169. List of historic process instances - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdNoStringAn id of the historic process instance.
    processDefinitionKeyNoStringThe process definition key of the historic process instance.
    processDefinitionIdNoStringThe process definition id of the historic process instance.
    businessKeyNoStringThe business key of the historic process instance.
    involvedUserNoStringAn involved user of the historic process instance.
    finishedNoBooleanIndication if the historic process instance is finished.
    superProcessInstanceIdNoStringAn optional parent process id of the historic process instance.
    excludeSubprocessesNoBooleanReturn only historic process instances which aren't sub processes.
    finishedAfterNoDateReturn only historic process instances that were finished after this date.
    finishedBeforeNoDateReturn only historic process instances that were finished before this date.
    startedAfterNoDateReturn only historic process instances that were started after this date.
    startedBeforeNoDateReturn only historic process instances that were started before this date.
    startedByNoStringReturn only historic process instances that were started by this user.
    includeProcessVariablesNoBooleanAn indication if the historic process instance variables should be returned as well.
    tenantIdNoStringOnly return instances with the given tenantId.
    tenantIdLikeNoStringOnly return instances with a tenantId like the given value.
    withoutTenantIdNoBooleanIf true, only returns instances without a tenantId set. If false, the withoutTenantId parameter is ignored.

    The general paging and sorting query-parameters can be used for this URL.

       


    Table 15.170. List of historic process instances - Response codes

    Response codeDescription
    200Indicates that historic process instances could be queried.
    400Indicates an parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "5",
          "businessKey" : "myKey",
          "processDefinitionId" : "oneTaskProcess%3A1%3A4",
          "processDefinitionUrl" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
          "startTime" : "2013-04-17T10:17:43.902+0000",
          "endTime" : "2013-04-18T14:06:32.715+0000",
          "durationInMillis" : 86400056,
          "startUserId" : "kermit",
          "startActivityId" : "startEvent",
          "endActivityId" : "endEvent",
          "deleteReason" : null,
          "superProcessInstanceId" : "3",
          "url" : "http://localhost:8182/history/historic-process-instances/5",
          "variables": [
            {
              "name": "test",
              "variableScope": "local",
              "value": "myTest"
            }
          ],
          "tenantId":null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Query for historic process instances

    POST query/historic-process-instances

    Request body:

    {
      "processDefinitionId" : "oneTaskProcess%3A1%3A4",
      ...
      
      "variables" : [
        {
          "name" : "myVariable",
          "value" : 1234,
          "operation" : "equals",
          "type" : "long"
        }
      ]
    }

    All supported JSON parameter fields allowed are exactly the same as the parameters found for getting a collection of historic process instances, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri's that are too long. On top of that, the query allows for filtering based on process variables. The variables property is a json-array containing objects with the format as described here.

    Table 15.171. Query for historic process instances - Response codes

    Response codeDescription
    200Indicates request was successful and the tasks are returned
    400Indicates an parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "5",
          "businessKey" : "myKey",
          "processDefinitionId" : "oneTaskProcess%3A1%3A4",
          "processDefinitionUrl" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
          "startTime" : "2013-04-17T10:17:43.902+0000",
          "endTime" : "2013-04-18T14:06:32.715+0000",
          "durationInMillis" : 86400056,
          "startUserId" : "kermit",
          "startActivityId" : "startEvent",
          "endActivityId" : "endEvent",
          "deleteReason" : null,
          "superProcessInstanceId" : "3",
          "url" : "http://localhost:8182/history/historic-process-instances/5",
          "variables": [
            {
              "name": "test",
              "variableScope": "local",
              "value": "myTest"
            }
          ],
          "tenantId":null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Delete a historic process instance

    DELETE history/historic-process-instances/{processInstanceId}

    Table 15.172. Response codes

    Response codeDescription
    200Indicates that the historic process instance was deleted.
    404Indicates that the historic process instance could not be found.


    Get the identity links of a historic process instance

    GET history/historic-process-instance/{processInstanceId}/identitylinks

    Table 15.173. Response codes

    Response codeDescription
    200Indicates request was successful and the identity links are returned
    404Indicates the process instance could not be found.


    Success response body:

    [
     {
      "type" : "participant",
      "userId" : "kermit",
      "groupId" : null,
      "taskId" : null,
      "taskUrl" : null,
      "processInstanceId" : "5",
      "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/5"
     }
    ]

    Get the binary data for a historic process instance variable

    GET history/historic-process-instances/{processInstanceId}/variables/{variableName}/data

    Table 15.174. Get the binary data for a historic process instance variable - Response codes

    Response codeDescription
    200Indicates the process instance was found and the requested variable data is returned.
    404Indicates the requested process instance was not found or the process instance doesn't have a variable with the given name or the variable doesn't have a binary stream available. Status message provides additional information.


    Success response body: The response body contains the binary value of the variable. When the variable is of type binary, the content-type of the response is set to application/octet-stream, regardless of the content of the variable or the request accept-type header. In case of serializable, application/x-java-serialized-object is used as content-type.

    Create a new comment on a historic process instance

    POST history/historic-process-instances/{processInstanceId}/comments

    Table 15.175. Create a new comment on a historic process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to create the comment for.


    Request body:

    { 
      "message" : "This is a comment."
    }

    Success response body:

    { 
      "id" : "123",
      "url" : "http://localhost:8081/activiti-rest/history/historic-process-instances/100/comments/123",
      "message" : "This is a comment.",
      "author" : "kermit"
    }

    Table 15.176. Create a new comment on a historic process instance - Response codes

    Response codeDescription
    201Indicates the comment was created and the result is returned.
    400Indicates the comment is missing from the request.
    404Indicates the requested historic process instance was not found.


    Get all comments on a historic process instance

    GET history/historic-process-instances/{processInstanceId}/comments

    Table 15.177. Get all comments on a process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the process instance to get the comments for.


    Success response body:

    [
      { 
        "id" : "123",
        "url" : "http://localhost:8081/activiti-rest/service/history/historic-process-instances/100/comments/123",
        "message" : "This is a comment",
        "author" : "kermit"
      },
      { 
        "id" : "456",
        "url" : "http://localhost:8081/activiti-rest/service/history/historic-process-instances/100/comments/456",
        "message" : "This is another comment.",
        "author" : "gonzo"
      }
    ]

    Table 15.178. Get all comments on a process instance - Response codes

    Response codeDescription
    200Indicates the process instance was found and the comments are returned.
    404Indicates the requested task was not found.


    Get a comment on a historic process instance

    GET history/historic-process-instances/{processInstanceId}/comments/{commentId}

    Table 15.179. Get a comment on a historic process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the historic process instance to get the comment for.
    commentIdYesStringThe id of the comment.


    Success response body:

    { 
      "id" : "123",
      "url" : "http://localhost:8081/activiti-rest/history/historic-process-instances/100/comments/123",
      "message" : "This is a comment.",
      "author" : "kermit"
    }

    Table 15.180. Get a comment on a historic process instance - Response codes

    Response codeDescription
    200Indicates the historic process instance and comment were found and the comment is returned.
    404Indicates the requested historic process instance was not found or the historic process instance doesn't have a comment with the given ID.


    Delete a comment on a historic process instance

    DELETE history/historic-process-instances/{processInstanceId}/comments/{commentId}

    Table 15.181. Delete a comment on a historic process instance - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdYesStringThe id of the historic process instance to delete the comment for.
    commentIdYesStringThe id of the comment.


    Table 15.182. Delete a comment on a historic process instance - Response codes

    Response codeDescription
    204Indicates the historic process instance and comment were found and the comment is deleted. Response body is left empty intentionally.
    404Indicates the requested task was not found or the historic process instance doesn't have a comment with the given ID.

    Get a single historic task instance

    GET history/historic-task-instances/{taskId}

    Table 15.183. Get a single historic task instance - Response codes

    Response codeDescription
    200Indicates that the historic task instances could be found.
    404Indicates that the historic task instances could not be found.


    Success response body:

    {
      "id" : "5",
      "processDefinitionId" : "oneTaskProcess%3A1%3A4",
      "processDefinitionUrl" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
      "processInstanceId" : "3",
      "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/3",
      "executionId" : "4",
      "name" : "My task name",
      "description" : "My task description",
      "deleteReason" : null,
      "owner" : "kermit",
      "assignee" : "fozzie",
      "startTime" : "2013-04-17T10:17:43.902+0000",
      "endTime" : "2013-04-18T14:06:32.715+0000",
      "durationInMillis" : 86400056,
      "workTimeInMillis" : 234890,
      "claimTime" : "2013-04-18T11:01:54.715+0000",
      "taskDefinitionKey" : "taskKey",
      "formKey" : null,
      "priority" : 50,
      "dueDate" : "2013-04-20T12:11:13.134+0000",
      "parentTaskId" : null,
      "url" : "http://localhost:8182/history/historic-task-instances/5",
      "variables": null,
      "tenantId":null
    }

    Get historic task instances

    GET history/historic-task-instances

    Table 15.184. Get historic task instances - URL parameters

    ParameterRequiredValueDescription
    taskIdNoStringAn id of the historic task instance.
    processInstanceIdNoStringThe process instance id of the historic task instance.
    processDefinitionKeyNoStringThe process definition key of the historic task instance.
    processDefinitionKeyLikeNoStringThe process definition key of the historic task instance, which matches the given value.
    processDefinitionIdNoStringThe process definition id of the historic task instance.
    processDefinitionNameNoStringThe process definition name of the historic task instance.
    processDefinitionNameLikeNoStringThe process definition name of the historic task instance, which matches the given value.
    processBusinessKeyNoStringThe process instance business key of the historic task instance.
    processBusinessKeyLikeNoStringThe process instance business key of the historic task instance that matches the given value.
    executionIdNoStringThe execution id of the historic task instance.
    taskDefinitionKeyNoStringThe task definition key for tasks part of a process
    taskNameNoStringThe task name of the historic task instance.
    taskNameLikeNoStringThe task name with 'like' operator for the historic task instance.
    taskDescriptionNoStringThe task description of the historic task instance.
    taskDescriptionLikeNoStringThe task description with 'like' operator for the historic task instance.
    taskDefinitionKeyNoStringThe task identifier from the process definition for the historic task instance.
    taskDeleteReasonNoStringThe task delete reason of the historic task instance.
    taskDeleteReasonLikeNoStringThe task delete reason with 'like' operator for the historic task instance.
    taskAssigneeNoStringThe assignee of the historic task instance.
    taskAssigneeLikeNoStringThe assignee with 'like' operator for the historic task instance.
    taskOwnerNoStringThe owner of the historic task instance.
    taskOwnerLikeNoStringThe owner with 'like' operator for the historic task instance.
    taskInvolvedUserNoStringAn involved user of the historic task instance.
    taskPriorityNoStringThe priority of the historic task instance.
    finishedNoBooleanIndication if the historic task instance is finished.
    processFinishedNoBooleanIndication if the process instance of the historic task instance is finished.
    parentTaskIdNoStringAn optional parent task id of the historic task instance.
    dueDateNoDateReturn only historic task instances that have a due date equal this date.
    dueDateAfterNoDateReturn only historic task instances that have a due date after this date.
    dueDateBeforeNoDateReturn only historic task instances that have a due date before this date.
    withoutDueDateNoBooleanReturn only historic task instances that have no due-date. When false is provided as value, this parameter is ignored.
    taskCompletedOnNoDateReturn only historic task instances that have been completed on this date.
    taskCompletedAfterNoDateReturn only historic task instances that have been completed after this date.
    taskCompletedBeforeNoDateReturn only historic task instances that have been completed before this date.
    taskCreatedOnNoDateReturn only historic task instances that were created on this date.
    taskCreatedBeforeNoDateReturn only historic task instances that were created before this date.
    taskCreatedAfterNoDateReturn only historic task instances that were created after this date.
    includeTaskLocalVariablesNoBooleanAn indication if the historic task instance local variables should be returned as well.
    includeProcessVariablesNoBooleanAn indication if the historic task instance global variables should be returned as well.
    tenantIdNoStringOnly return historic task instances with the given tenantId.
    tenantIdLikeNoStringOnly return historic task instances with a tenantId like the given value.
    withoutTenantIdNoBooleanIf true, only returns historic task instances without a tenantId set. If false, the withoutTenantId parameter is ignored.

    The general paging and sorting query-parameters can be used for this URL.

       


    Table 15.185. Get historic task instances - Response codes

    Response codeDescription
    200Indicates that historic process instances could be queried.
    400Indicates an parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "5",
          "processDefinitionId" : "oneTaskProcess%3A1%3A4",
          "processDefinitionUrl" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
          "processInstanceId" : "3",
          "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/3",
          "executionId" : "4",
          "name" : "My task name",
          "description" : "My task description",
          "deleteReason" : null,
          "owner" : "kermit",
          "assignee" : "fozzie",
          "startTime" : "2013-04-17T10:17:43.902+0000",
          "endTime" : "2013-04-18T14:06:32.715+0000",
          "durationInMillis" : 86400056,
          "workTimeInMillis" : 234890,
          "claimTime" : "2013-04-18T11:01:54.715+0000",
          "taskDefinitionKey" : "taskKey",
          "formKey" : null,
          "priority" : 50,
          "dueDate" : "2013-04-20T12:11:13.134+0000",
          "parentTaskId" : null,
          "url" : "http://localhost:8182/history/historic-task-instances/5",
          "taskVariables": [
            {
              "name": "test",
              "variableScope": "local",
              "value": "myTest"
            }
          ],
          "processVariables": [
            {
              "name": "processTest",
              "variableScope": "global",
              "value": "myProcessTest"
            }
          ],
          "tenantId":null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Query for historic task instances

    POST query/historic-task-instances

    Query for historic task instances - Request body:

    {
      "processDefinitionId" : "oneTaskProcess%3A1%3A4",
      ...
      
      "variables" : [
        {
          "name" : "myVariable",
          "value" : 1234,
          "operation" : "equals",
          "type" : "long"
        }
      ]
    }

    All supported JSON parameter fields allowed are exactly the same as the parameters found for getting a collection of historic task instances, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri's that are too long. On top of that, the query allows for filtering based on process variables. The taskVariables and processVariables properties are json-arrays containing objects with the format as described here.

    Table 15.186. Query for historic task instances - Response codes

    Response codeDescription
    200Indicates request was successful and the tasks are returned
    400Indicates an parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "5",
          "processDefinitionId" : "oneTaskProcess%3A1%3A4",
          "processDefinitionUrl" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
          "processInstanceId" : "3",
          "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/3",
          "executionId" : "4",
          "name" : "My task name",
          "description" : "My task description",
          "deleteReason" : null,
          "owner" : "kermit",
          "assignee" : "fozzie",
          "startTime" : "2013-04-17T10:17:43.902+0000",
          "endTime" : "2013-04-18T14:06:32.715+0000",
          "durationInMillis" : 86400056,
          "workTimeInMillis" : 234890,
          "claimTime" : "2013-04-18T11:01:54.715+0000",
          "taskDefinitionKey" : "taskKey",
          "formKey" : null,
          "priority" : 50,
          "dueDate" : "2013-04-20T12:11:13.134+0000",
          "parentTaskId" : null,
          "url" : "http://localhost:8182/history/historic-task-instances/5",
          "taskVariables": [
            {
              "name": "test",
              "variableScope": "local",
              "value": "myTest"
            }
          ],
          "processVariables": [
            {
              "name": "processTest",
              "variableScope": "global",
              "value": "myProcessTest"
            }
          ],
          "tenantId":null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Delete a historic task instance

    DELETE history/historic-task-instances/{taskId}

    Table 15.187. Response codes

    Response codeDescription
    200Indicates that the historic task instance was deleted.
    404Indicates that the historic task instance could not be found.


    Get the identity links of a historic task instance

    GET history/historic-task-instance/{taskId}/identitylinks

    Table 15.188. Response codes

    Response codeDescription
    200Indicates request was successful and the identity links are returned
    404Indicates the task instance could not be found.


    Success response body:

    [
     {
      "type" : "assignee",
      "userId" : "kermit",
      "groupId" : null,
      "taskId" : "6",
      "taskUrl" : "http://localhost:8182/history/historic-task-instances/5",
      "processInstanceId" : null,
      "processInstanceUrl" : null
     }
    ]

    Get the binary data for a historic task instance variable

    GET history/historic-task-instances/{taskId}/variables/{variableName}/data

    Table 15.189. Get the binary data for a historic task instance variable - Response codes

    Response codeDescription
    200Indicates the task instance was found and the requested variable data is returned.
    404Indicates the requested task instance was not found or the process instance doesn't have a variable with the given name or the variable doesn't have a binary stream available. Status message provides additional information.


    Success response body: The response body contains the binary value of the variable. When the variable is of type binary, the content-type of the response is set to application/octet-stream, regardless of the content of the variable or the request accept-type header. In case of serializable, application/x-java-serialized-object is used as content-type.

    Get historic activity instances

    GET history/historic-activity-instances

    Table 15.190. Get historic activity instances - URL parameters

    ParameterRequiredValueDescription
    activityIdNoStringAn id of the activity instance.
    activityInstanceIdNoStringAn id of the historic activity instance.
    activityNameNoStringThe name of the historic activity instance.
    activityTypeNoStringThe element type of the historic activity instance.
    executionIdNoStringThe execution id of the historic activity instance.
    finishedNoBooleanIndication if the historic activity instance is finished.
    taskAssigneeNoStringThe assignee of the historic activity instance.
    processInstanceIdNoStringThe process instance id of the historic activity instance.
    processDefinitionIdNoStringThe process definition id of the historic activity instance.
    tenantIdNoStringOnly return instances with the given tenantId.
    tenantIdLikeNoStringOnly return instances with a tenantId like the given value.
    withoutTenantIdNoBooleanIf true, only returns instances without a tenantId set. If false, the withoutTenantId parameter is ignored.

    The general paging and sorting query-parameters can be used for this URL.

       


    Table 15.191. Get historic activity instances - Response codes

    Response codeDescription
    200Indicates that historic activity instances could be queried.
    400Indicates an parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "5",
          "activityId" : "4",
          "activityName" : "My user task",
          "activityType" : "userTask",
          "processDefinitionId" : "oneTaskProcess%3A1%3A4",
          "processDefinitionUrl" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
          "processInstanceId" : "3",
          "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/3",
          "executionId" : "4",
          "taskId" : "4",
          "calledProcessInstanceId" : null,
          "assignee" : "fozzie",
          "startTime" : "2013-04-17T10:17:43.902+0000",
          "endTime" : "2013-04-18T14:06:32.715+0000",
          "durationInMillis" : 86400056,
          "tenantId":null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Query for historic activity instances

    POST query/historic-activity-instances

    Request body:

    {
      "processDefinitionId" : "oneTaskProcess%3A1%3A4"
    }

    All supported JSON parameter fields allowed are exactly the same as the parameters found for getting a collection of historic task instances, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri's that are too long.

    Table 15.192. Query for historic activity instances - Response codes

    Response codeDescription
    200Indicates request was successful and the activities are returned
    400Indicates an parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "5",
          "activityId" : "4",
          "activityName" : "My user task",
          "activityType" : "userTask",
          "processDefinitionId" : "oneTaskProcess%3A1%3A4",
          "processDefinitionUrl" : "http://localhost:8182/repository/process-definitions/oneTaskProcess%3A1%3A4",
          "processInstanceId" : "3",
          "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/3",
          "executionId" : "4",
          "taskId" : "4",
          "calledProcessInstanceId" : null,
          "assignee" : "fozzie",
          "startTime" : "2013-04-17T10:17:43.902+0000",
          "endTime" : "2013-04-18T14:06:32.715+0000",
          "durationInMillis" : 86400056,
          "tenantId":null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    List of historic variable instances

    GET history/historic-variable-instances

    Table 15.193. List of historic variable instances - URL parameters

    ParameterRequiredValueDescription
    processInstanceIdNoStringThe process instance id of the historic variable instance.
    taskIdNoStringThe task id of the historic variable instance.
    excludeTaskVariablesNoBooleanIndication to exclude the task variables from the result.
    variableNameNoStringThe variable name of the historic variable instance.
    variableNameLikeNoStringThe variable name using the 'like' operator for the historic variable instance.

    The general paging and sorting query-parameters can be used for this URL.

       


    Table 15.194. List of historic variable instances - Response codes

    Response codeDescription
    200Indicates that historic variable instances could be queried.
    400Indicates an parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "14",
          "processInstanceId" : "5",
          "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/5",
          "taskId" : "6",
          "variable" : {
            "name" : "myVariable",
            "variableScope", "global",
            "value" : "test"
          }
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Query for historic variable instances

    POST query/historic-variable-instances

    Request body:

    {
      "processDefinitionId" : "oneTaskProcess%3A1%3A4",
      ...
      
      "variables" : [
        {
          "name" : "myVariable",
          "value" : 1234,
          "operation" : "equals",
          "type" : "long"
        }
      ]
    }

    All supported JSON parameter fields allowed are exactly the same as the parameters found for getting a collection of historic process instances, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri's that are too long. On top of that, the query allows for filtering based on process variables. The variables property is a json-array containing objects with the format as described here.

    Table 15.195. Query for historic variable instances - Response codes

    Response codeDescription
    200Indicates request was successful and the tasks are returned
    400Indicates an parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "14",
          "processInstanceId" : "5",
          "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/5",
          "taskId" : "6",
          "variable" : {
            "name" : "myVariable",
            "variableScope", "global",
            "value" : "test"
          }
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Get the binary data for a historic task instance variable

    GET history/historic-variable-instances/{varInstanceId}/data

    Table 15.196. Get the binary data for a historic task instance variable - Response codes

    Response codeDescription
    200Indicates the variable instance was found and the requested variable data is returned.
    404Indicates the requested variable instance was not found or the variable instance doesn't have a variable with the given name or the variable doesn't have a binary stream available. Status message provides additional information.


    Success response body: The response body contains the binary value of the variable. When the variable is of type binary, the content-type of the response is set to application/octet-stream, regardless of the content of the variable or the request accept-type header. In case of serializable, application/x-java-serialized-object is used as content-type.

    Get historic detail

    GET history/historic-detail

    Table 15.197. Get historic detail - URL parameters

    ParameterRequiredValueDescription
    idNoStringThe id of the historic detail.
    processInstanceIdNoStringThe process instance id of the historic detail.
    executionIdNoStringThe execution id of the historic detail.
    activityInstanceIdNoStringThe activity instance id of the historic detail.
    taskIdNoStringThe task id of the historic detail.
    selectOnlyFormPropertiesNoBooleanIndication to only return form properties in the result.
    selectOnlyVariableUpdatesNoBooleanIndication to only return variable updates in the result.

    The general paging and sorting query-parameters can be used for this URL.

       


    Table 15.198. Get historic detail - Response codes

    Response codeDescription
    200Indicates that historic detail could be queried.
    400Indicates an parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "26",
          "processInstanceId" : "5",
          "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/5",
          "executionId" : "6",
          "activityInstanceId", "10",
          "taskId" : "6",
          "taskUrl" : "http://localhost:8182/history/historic-task-instances/6",
          "time" : "2013-04-17T10:17:43.902+0000",
          "detailType" : "variableUpdate",
          "revision" : 2,
          "variable" : {
            "name" : "myVariable",
            "variableScope", "global",
            "value" : "test"
          },
          "propertyId", null,
          "propertyValue", null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Query for historic details

    POST query/historic-detail

    Request body:

    {
      "processInstanceId" : "5",
    }

    All supported JSON parameter fields allowed are exactly the same as the parameters found for getting a collection of historic process instances, but passed in as JSON-body arguments rather than URL-parameters to allow for more advanced querying and preventing errors with request-uri's that are too long.

    Table 15.199. Query for historic details - Response codes

    Response codeDescription
    200Indicates request was successful and the historic details are returned
    400Indicates an parameter was passed in the wrong format. The status-message contains additional information.


    Success response body:

    {
      "data": [
        { 
          "id" : "26",
          "processInstanceId" : "5",
          "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/5",
          "executionId" : "6",
          "activityInstanceId", "10",
          "taskId" : "6",
          "taskUrl" : "http://localhost:8182/history/historic-task-instances/6",
          "time" : "2013-04-17T10:17:43.902+0000",
          "detailType" : "variableUpdate",
          "revision" : 2,
          "variable" : {
            "name" : "myVariable",
            "variableScope", "global",
            "value" : "test"
          },
          "propertyId", null,
          "propertyValue", null
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }

    Get the binary data for a historic detail variable

    GET history/historic-detail/{detailId}/data

    Table 15.200. Get the binary data for a historic detail variable - Response codes

    Response codeDescription
    200Indicates the historic detail instance was found and the requested variable data is returned.
    404Indicates the requested historic detail instance was not found or the historic detail instance doesn't have a variable with the given name or the variable doesn't have a binary stream available. Status message provides additional information.


    Success response body: The response body contains the binary value of the variable. When the variable is of type binary, the content-type of the response is set to application/octet-stream, regardless of the content of the variable or the request accept-type header. In case of serializable, application/x-java-serialized-object is used as content-type.

    Forms

    Get form data

    GET form/form-data

    Table 15.201. Get form data - URL parameters

    ParameterRequiredValueDescription
    taskIdYes (if no processDefinitionId)StringThe task id corresponding to the form data that needs to be retrieved.
    processDefinitionIdYes (if no taskId)StringThe process definition id corresponding to the start event form data that needs to be retrieved.


    Table 15.202. Get form data - Response codes

    Response codeDescription
    200Indicates that form data could be queried.
    404Indicates that form data could not be found.


    Success response body:

    {
      "data": [
        { 
          "formKey" : null,
          "deploymentId" : "2",
          "processDefinitionId" : "3",
          "processDefinitionUrl" : "http://localhost:8182/repository/process-definition/3",
          "taskId" : "6",
          "taskUrl" : "http://localhost:8182/runtime/task/6",
          "formProperties" : [
            {
              "id" : "room",
              "name" : "Room",
              "type" : "string",
              "value" : null,
              "readable" : true,
              "writable" : true,
              "required" : true,
              "datePattern" : null,
              "enumValues" : [
                {
                  "id" : "normal",
                  "name" : "Normal bed"
                },
                {
                  "id" : "kingsize",
                  "name" : "Kingsize bed"
                },
              ]
            }
          ]
        }
      ],
      "total": 1,
      "start": 0,
      "sort": "name",
      "order": "asc",
      "size": 1
    }