Activiti 5.

9 User Guide
Table of Contents 1. Introduction License Download Sources Required software JDK 5+ Ant 1.8.1+ Eclipse 3.6.2 Reporting problems Experimental features Internal implementation classes 2. Getting Started One minute version Demo setup Example projects in the workspace Library dependencies Eclipse setup Inspecting the database Database table names explained 3. Configuration Creating a ProcessEngine ProcessEngineConfiguration bean Database configuration Job executor activation Mail server configuration History configuration Exposing configuration beans in expressions and scripts Supported databases Creating the database tables Database upgrade 4. Spring integration ProcessEngineFactoryBean Transactions Expressions Automatic resource deployment Unit testing 5. API Engine API Exception strategy Unit testing

Debugging unit tests The process engine in a web application Process Virtual Machine API Expressions 6. Deployment Business archives Deploying programmatically Deploying with ant 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 7. BPMN 20 Introduction What is BPMN? Examples 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 20 Constructs Custom extensions Events Event definitions Timer events definitions Error event definitions Signal event definitions Message event definitions Start events None start event Timer start event Message 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 Cancel Boundary event Compensation Boundary event Intermediate catching events Timer intermediate catching event Signal 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 WebService Task Business Rule Task Email task Mule Task Manual Task Java receive task Shell Task Execution listener Task listener Multi-instance (for each) Compensation Handlers Subprocesses and Callactivities SubProcess Event subprocess Transaction subprocess Call activity (subprocess) Transactions and Concurrency Asynchronous Continuations

Exclusive Jobs 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 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 Case overview Cases Start process instances My instances Administration Changing the database 14. Activiti add-on components cycle Activiti Modeler based on Signavio Core components 15. REST API 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 Start Process Instance List Process Instances Get Process Instance Details Get Process Instance Diagram Tasks Get Task Summary List Tasks Get Task Get Task Form Perform Task Operation List Form Properties Add attachment to a task Add url to a task Identity Login Get User List User's Groups Get Group List Group Users 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 List of Tables

2.1. The demo users 2.2. The webapp tools 3.1. Supported databases 6.1. 6.2. 8.1. Mail server configuration 8.2. Mail server configuration 8.3. Mule server configuration 8.4. Shell task parameter configuration

Chapter 1. Introduction
Table of Contents License Download Sources Required software JDK 5+ Ant 1.8.1+ Eclipse 3.6.2 Reporting problems Experimental features Internal implementation classes

License
Activiti is distributed under the Apache V2 license.

Download
http://activiti.org/download.html

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 5+
Activiti runs on a JDK higher then version 5. 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.

Ant 1.8.1+
Download the latest stable version of ant from the Ant download page. Unzip the file and make sure that the bin folder is in the path of your OS. Verify with running ant -version in the command line. That should print the installed version ant.

Eclipse 3.6.2
Download the Eclipse Classic version of eclipse 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 setting up the Activiti examples projects in your eclipseand another one 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

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

Table of Contents One minute version Demo setup Example projects in the workspace Library dependencies Eclipse setup Inspecting the database Database table names explained

One minute version

After downloading the Activiti distribution zip 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 Ant installation.

Unzip the Activiti distribution zip file. Open up a terminal window and navigate to the setup folder in the unzipped folder. Type ant demo.start and hit enter. When the script finishes, it starts up all the Activiti webapps in your browser. Login with kermit/kermit.

That's it! If you want to know more about what actually happened in the steps above, read the longer version. You can also start learning all about Activiti and BPMN 2.0 in the ten minute tutorial.

Demo setup
'Demo Setup' is an ant script located in directory setup that sets up an Activiti environment in no time. To run the script, you'll need a working Java runtime and Ant installation. Also make sure that the JAVA_HOME and ANT_HOME system variables are correctly set. The way to do this depends on your operating system, but the manual of ant gives a description on how to do this. The demo setup script is tested with Ant 1.7.1+. To get started, open a command prompt/terminal in the setup folder of the unzipped Activiti distribution and type:

ant demo.start
This ant script will execute following steps:

(*) Build the webapps. All libraries are stored in ${actviti.home}/setup/files/dependencies/libs The webapps without the libs are stored in ${actviti.home}/setup/files/webapps. Building the webapps means that webapps are combined with the necessary libraries in ${actviti.home}/setup/build/webapps

(*) Install the H2 in ${activiti.home}/apps/h2. Start the H2 database. (*) Create the Activiti tables in the H2 database (*) Insert the demo users and groups in the Activiti identity tables (see below) (*) Deploy the example processes to the Activiti Engine DB (*) Download Tomcat if not available in the ${downloads.dir} (*) Install Tomcat in ${activiti.home}/apps/apache-tomcat-${tomcat.version} (*) Create an Activiti configuration jar (*) Deploy the REST interface webapp into tomcat (*) Deploy the Activiti webapp into tomcat. Start tomcat

(*) only performed the first time when running ant demo.start After running this target H2 and Tomcat will be running in the background. To stop those processes run ant demo.stop.

The other targets in that build script can also be called individually. Run ant -p for more details. These are the demo users: Table 2.1. The demo users

UserId Password Security roles

kermit kermit gonzo fozzie gonzo fozzie admin manager user

Now you can access following web applications: Table 2.2. The webapp tools

Webapp Name
Activiti Explorer

URL
http://localhost:8080/activitiexplorer

Description
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 demo setup is a way of showing the capabilities and functionality of Activiti as easy 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!

Example projects in the workspace

The distribution contains a workspace directory containing a couple of example java projects:

activiti-engine-examples: This set of examples show the most common usage of Activiti: BPMN process definitions and process executions are stored in a DB and the examples make use of the persistent API. This project contains the eclipse project files, an ant build file and a maven pom file. The ant build file is independent of the maven pom. Both are there to show how you can use ant and maven respectively for building and deploying

processes as part of your build. activiti-spring-examples: These examples show how you can use the Activiti Engine in a Spring environment. activiti-groovy-examples: These examples show the library dependencies for groovy and an example process with groovy scripting. activiti-jpa-examples: These examples show library dependencies and how you can work with JPA in Activiti. activiti-cxf-examples: These examples show library dependencies and how you can work with web services in Activiti.

the section called Eclipse setup shows how you can set up your eclipse environment to play with these example projects.

As part of the demo.start, the examples will be inflated. This means that all the libs and configuration files will be put in place. If you don't run thedemo.start and you want to inflate the examples with libs in the appropriate place, run this command in the setup directory:

ant inflate.examples
Once you've done that the activiti-engine-examples and activiti-spring-examples will contain libsruntime and libs-test directories containing the runtime dependency jars and test time dependency jars respectively.

Library dependencies
In order to prevent that the distribution file becomes too big by libraries that are included multiple times, all the libraries are grouped into thesetup/files/dependencies/libs/ folder. The ant scripts in the setup/build.xml can inflate the examples (target inflate.examples) with the libs and they will include the appropriate libs when building the webapps. The following files in setup/files/dependencies describe the library dependencies:

libs.engine.runtime.txt: The library runtime dependencies to run the Activiti Engine. libs.engine.runtime.test.txt: The libraries that need to be added to the ones in libs.engine.runtime.txt to run the tests libs.engine.runtime.feature.groovy.txt: The libraries that need to be added to the ones in libs.engine.runtime.txt to use the groovy scripting capabilities. libs.engine.runtime.txt: The libraries that need to be added to the ones in libs.engine.runtime.txt to use the JPA variable reference capabilities. libs.spring.runtime.txt: The library runtime dependencies to run the Activiti Engine in a Spring environment. (This list includes the libs in libs.engine.runtime.txt) libs.spring.runtime.test.txt: The libraries that need to be added to the ones in libs.spring.runtime.txt to run tests in a Spring environment

Eclipse setup
To run and play with the examples in your eclipse, follow these simple instructions: File --> Import...

Select General --> Existing Projects into Workspace and click Next

Click 'Browse...', select the directory ${activiti.home}/workspace and you'll see the example projects being automatically selected. Then you can click Finish in the Import dialog and you're all set. For more convenience, open the ant view (Window --> Show View --> Ant) and drag the file activiti-

engine-examples/build.xml into the ant window. Now you'll be able to activate the build targets by just double
clicking on them.

If you want BPMN 2.0 XML auto-completion and validation while typing, you can add the BPMN 2.0 XML Schema to the XML catalog. Go to Window --> Preferences --> XML --> XML Catalog --> Add..., and select the XML Schema from the file system in the folder${activiti.home}/docs/xsd/BPMN20.xsd. Repeat this step with ${activiti.home}/docs/xsd/activiti-bpmn-extensions-5.4.xsd.

Have a look at Chapter 12, Eclipse Designer for instructions on how to install the Activiti Designer plugin into Eclipse.

Inspecting the database

To check out the database while trying out the demo setup, run the following Ant target in the setup folder:

ant h2.console.start
This will boot the H2 web console. Note that the Ant target doesn't return, so a 'CTRL + C' is required to shutdown the console. Fill in the following URL in the JDBC URL field and click connect:

jdbc:h2:tcp://localhost/activiti

You are now able to browse the Activiti database schema and check the content of the tables. To change the database, see ???

Database table names explained

The database names of Activiti all start with ACT_. The second part is a two-character identification of 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 will contain 'static'' information such as process definitions and, process resources (images, rules, etc.). ACT_RU_*: 'RE' 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.

Chapter 3. Configuration
Table of Contents Creating a ProcessEngine ProcessEngineConfiguration bean Database configuration Job executor activation

Mail server configuration History configuration Exposing configuration beans in expressions and scripts Supported databases Creating the database tables Database upgrade

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 .springframework.org/schema/beans/spring-beans.xsd">

http://www

<bean id="processEngineConfiguration" class="org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration"> <property <property <property <property name="jdbcUrl" value="jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000" /> name="jdbcDriver" value="org.h2.Driver" /> name="jdbcUsername" value="sa" /> 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(InputStr eam inputStream); ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(InputStr eam 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 theprocessEngineConfiguration. 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. 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 : ([EXPERIMENTAL]) 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. 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 its taking unusually long (to avoid failing silently forever if the pool is misconfigured) Default is 20000 (20 seconds).

Example database configuration:

<property <property <property <property

name="jdbcUrl" value="jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000" /> name="jdbcDriver" value="org.h2.Driver" /> name="jdbcUsername" value="sa" /> 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 data source. So you have to make sure that the libraries (e.g. from DBCP) are on your classpath. Following properties can be set, regardless of 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.

o o o

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

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. Therefor 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 that the job executor interferes, 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 process engine boot.

Mail server configuration

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
Optional. Allows 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, then 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.

Supported databases
Following are the types (case sensitive!) that Activiti uses to refer to databases. Table 3.1. Supported databases

Activiti database type

h2 mysql oracle postgres db2 mssql

Versions tested
1.2.132 5.1.11 10.2.0 8.4 DB2 9.7 using db2jcc4 2008 using JDBC jtds-1.2.4

Example JDBC URL

jdbc:h2:tcp://localhost/activiti jdbc:mysql://localhost:3306/activiti?autoReconnect=true jdbc:oracle:thin:@localhost:1521:xe jdbc:postgresql://localhost:5432/activiti jdbc:db2://localhost:50000/activiti jdbc:jtds:sqlserver://localhost:1433/activiti

Notes
Default configured database Tested using mysql-connetor-java database driver

[EXPERIMENTAL] [EXPERIMENTAL]

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. The SQL DDL statements can be found inside the Activiti 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: optional tables, when using the default identity management as shipped with the engine. history: contain the history and audit information. Optional: not needed when history level is set to none

Database upgrade
[EXPERIMENTAL] We don't yet have enough coverage testing of upgrade to have full confidence in it. That is why we still marked it as experimental. 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 an 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.

Chapter 4. Spring integration

Table of Contents ProcessEngineFactoryBean Transactions Expressions Automatic resource deployment Unit testing While you definitely can 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 classorg.activiti.spring.ProcessEngineFactoryBean. That bean takes a process engine configuration and creates the process engine. This means that the way and all configuration properties documented in the configuration section are exactly the same as for Spring:

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

Do 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. Here is the spring configuration file that we use in this example (located in SpringTransactionIntegrationTest-context.xml). The quoted section contains the dataSource, transactionManager, processEngine and the Activiti Engine services. When passing the DataSource to the SpringProcessEngineConfiguration (using property "dataSource"), Activiti uses aorg.springframework.jdbc.datasource.TransactionAwareDataSourceProxy internally, which wraps the passed DataSource. This is done 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, however it's allowed to pass a TransactionAwareDataSourceProxy into theSpringProcessEngineConfiguration. 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" factorymethod="getRepositoryService" /> <bean id="runtimeService" factory-bean="processEngine" factorymethod="getRuntimeService" /> <bean id="taskService" factory-bean="processEngine" factorymethod="getTaskService" /> <bean id="historyService" factory-bean="processEngine" factorymethod="getHistoryService" /> <bean id="managementService" factory-bean="processEngine" factorymethod="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/SpringTransactionInteg rationTest-context.xml");

or since it is a test:

@ContextConfiguration("classpath:org/activiti/spring/test/transaction/SpringTransac tionIntegrationTest-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 we can use for example 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. 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/springTypicalUsageTestcontext.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>

Chapter 5. API
Table of Contents Engine API Exception strategy Unit testing Debugging unit tests The process engine in a web application Process Virtual Machine API Expressions

Engine API
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();

The names of the service are quite self-explanatory. For detailed information on the services and the engine API, see the javadocs.

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() andProcessEngines.destroy() ProcessEngines will scan for all activiti.cfg.xml and activiti-context.xml files. For all activiti.cfg.xml files, the process engine will be build in the typical Activiti way:ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(input

Stream).buildProcessEngine(). For allactiviti-context.xml files, the process engine will be build in the
Spring way: First the spring application context is created and then the process engine is obtained from that application context.

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 fromTaskService: /** * Called when the task is successfully executed. * @param taskId the id of the task to complete, cannot be null. * @throws ActivitiException 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 ActivitiException 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:

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 an class requested to load was not found or when error occurred while loading it (e.g. JavaDelegates, TaskListeners, ...).

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 test for business processes is as simple as writing regular unit tests. Activiti supports both JUnit versions 3 and 4 style 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 thegetConfigurationResource() method. Process engines are be 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. 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, 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 the 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("").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 isjdbc: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 when the container boots and shut down the engine when the container goes down.

The following code snippet 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 will delegate to ProcessEngines.init(). That will look for activiti.cfg.xml resource files on the classpath, and create aProcessEngines 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 of the context-listener delegates to ProcessEngines.destroy(). That will properly close all initialized process engines.

Process Virtual Machine API

The Process Virtual Machine API exposes the POJO core of the Process Virtual Machine. Reading and playing with it is interesting for education purposes to understand the internal workings of Activiti. And the POJO API can also be used to build new process languages. For example: PvmProcessDefinition processDefinition = new ProcessDefinitionBuilder() .createActivity("a") .initial() .behavior(new WaitState()) .transition("b") .endActivity() .createActivity("b") .behavior(new WaitState())

.transition("c") .endActivity() .createActivity("c") .behavior(new WaitState()) .endActivity() .buildProcessDefinition(); PvmProcessInstance processInstance = processDefinition.createProcessInstance(); processInstance.start(); PvmExecution activityInstance = processInstance.findExecution("a"); assertNotNull(activityInstance); activityInstance.signal(null, null); activityInstance = processInstance.findExecution("b"); assertNotNull(activityInstance); activityInstance.signal(null, null); activityInstance = processInstance.findExecution("c"); assertNotNull(activityInstance);

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 makes abstraction of this and they can both be used where anexpression 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. 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 object exposed that you can use 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, 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.

Chapter 6. Deployment
Table of Contents Business archives Deploying programmatically Deploying with ant 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

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. Basically 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 extension. Each of those will be parsed and potentially contains multiple process definitions. Note that 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 javadocs for more details.

Deploying with ant

To deploy a business archive with ant, first the deploy-bar task needs to be defined. Make sure that the configuration jar is on the classpath, as well as the Activiti jar and all its dependencies: <taskdef name="deploy-bar" classname="org.activiti.engine.impl.ant.DeployBarTask"> <classpath> <fileset dir="..."> <include name="activiti-cfg.jar"/> <include name="your-db-driver.jar"/> </fileset> <fileset dir="${activiti.home}/lib"> <include name="activiti-engine-${activiti.version}.jar"/> <include name="ibatis-sqlmap-*.jar"/> </fileset> </classpath> </taskdef> <deploy-bar file=".../yourprocess.bar" />

Deploying with Activiti Explorer

The Activiti Explorer webapp allows to upload 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 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. Those 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.

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. But during deployment of a business archive, those classes don't have to be present on the classpath. This means that you're 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-rest webapp lib. Don't forget to include the dependencies of your custom classes (if any) as well. This is the same location where the activiti-engine jar is located. You can find this folder inside your distro at ${activiti.home}/apps/apache-tomcat-6.0.29/webapps/activiti-rest/lib/

Using spring beans from a process

When expressions or scripts use spring beans, those spring beans have to be available to the engine. 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.home}/apps/apache-tomcat-

6.0.29/webapps/activiti-rest/lib/activiti-cfg.jar with a activiti-context.xmlcontaining 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 can consider to include the Activiti rest webapp inside your own webapp so that there is only one single ProcessEngine.

Versioning of process definitions

BPMN doesn't have a notion of versioning. And that is good because the executable BPMN process file will probably live in an Subversion repository 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 max currently deployed version. The key property is used to distinct 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 as follows Table 6.1.

id

key

name

version

myProcess:1:676 myProcess My important process 1

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 following entries: Table 6.2.

id

key

name

version

myProcess:1:676 myProcess My important process 1 myProcess:2:870 myProcess My important process 2

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.

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 as process key 'expense'. Following naming conventions for the process diagram image apply (in this specific order):

If in the deployment an image resource with as name the BPMN 2.0 XML file name concatenated with the process key and an image suffix exists, 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. 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 of course no 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 then later be retrieved through the API: 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 when the process definition contains the necessary 'diagram interchange' information. This is the case when using the Activiti Modeler (and in the near future when using the Activiti Eclipse Designer). The resource can be retrieved in exactly the same way as when an image is provided in the deployment.

Chapter 7. BPMN 20 Introduction

Table of Contents What is BPMN? Examples 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

What is BPMN?
See our FAQ entry on BPMN 2.0.

Examples
Examples for the BPMN 2.0 constructs described in the following sections can be found in the workspace/activiti-xexamples folders of the Activiti distribution. See the specific section on examples for more information.

Defining a process
To create a new BPMN 2.0 process definition, it's best to have your Eclipse properly set up. Create a new XML file (rightclick on any project and select New->Other->XML-XML File) and give it a name. Make sure that the file ends with .bpmn20.xml, 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 follows. 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 schemalocation 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 for example be used for displaying a more human-friendly name in a user interface.

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. Optionally, you should also have an Eclipse installed and imported the Activiti examples.

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. All files and code snippets used through the next sections can be found in the examples shipped with the Activiti distribution. Look for the packageorg.activiti.examples.bpmn.usertask.

Process diagram
The business process as described above, can be graphically visualized using the Activiti Modeler or the Activiti Designer. However, for this tutorial we'll type the XML ourselves, as this learns us the most 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 accountancygroup, 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 directionof 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 now have 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 the financial report every 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 go first through the start event. After the start event, it follows all the outgoing sequence flow (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 its 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 the 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 setup/files/dependencies/libs). 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, that 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 contains also 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 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 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 (run the demo setup if you haven't done it yet'), we can now log into Activiti Explorer (login with fozzie/fozzie), and we fill 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, bringing the execution in the second task ('verification of the report'). The same mechanism as described for the first task will now happen, 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 (which 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 bring process execution at the end event, which finishes the process instance. The process instance and all related runtime execution data is 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).singl eResult(); System.out.println("Process instance end time: " + historicProcessInstance.getEndTime());

Code overview
Taking 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 works always):

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).singleRes ult(); 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 20 Constructs

Table of Contents Custom extensions Events Event definitions Timer events definitions Error event definitions Signal event definitions Message event definitions Start events None start event Timer start event Message 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 Cancel Boundary event Compensation Boundary event Intermediate catching events Timer intermediate catching event Signal 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 WebService Task Business Rule Task Email task Mule Task Manual Task Java receive task Shell Task Execution listener Task listener Multi-instance (for each) Compensation Handlers Subprocesses and Callactivities SubProcess Event subprocess Transaction subprocess Call activity (subprocess) Transactions and Concurrency Asynchronous Continuations Exclusive Jobs

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 events 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 subelement oftimerEventDefinition. 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

[EXPERIMENTAL] 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 theorg.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() .signalEventSubscription("alert") .list();

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

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

[EXPERIMENTAL] 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 messaageRef references a message element declared as a child element of the definitions root element. The following is an excerpt of a process where a message event is declared and referenced by a start 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" /> <process id="invoiceProcess"> <startEvent id="messageStart" > <messageEventDefinition messageRef="tns:newInvoice" /> </startEvent> ... </process> </definitions>

Throwing a signal event

At the moment, activiti supports message events only for starting process instances. To support this, the following methods exist on theRuntimeService:

ProcessInstance startProcessInstanceByMessage(String messageName); ProcessInstance startProcessInstanceByMessage(String messageName, Map<String, Object> processVariables); ProcessInstance startProcessInstanceByMessage(String messageName, String businessKey, Map<String, Object< processVariables);
The methods allow starting a process instance using the referenced message.

Catching a signal event

At the moment activiti only supports message start events. A message start event catches a message with a given name and starts a process instance. The payload of the message is added as process variables to the process instance. Since a message must be directed at a single receiver, activiti only allows a single process definition to be deployed for a given message name.

Querying for message event subscriptions

Since activiti only supports message start events, we can only query for message subscriptions 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.

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.), defininghow 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 thestartProcessInstanceByXXX 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. .

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 definitionsfor 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

[EXPERIMENTAL]

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 instance 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 instance. 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 themessageEventDefinition. 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, rutimeService.startProcessInstanceByMessage(...) allows to select the appropriate start event. If a process definition has multiple message start events and a single none start event,rutimeService.startProcessInstanceByKey(...) and rutimeService.startProcess InstanceById(...) starts a process instance using the none start event. If a process definition has multiple message start events and no none start event, rutimeService.startProcessInstanceByKey(...)and rutimeService.startProcess

InstanceById(...) throw an exception.

If a process definition has a single message start event, rutimeService.startProcessInstanceByKey(...) andrutimeService.startProcess InstanceById(...) 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 o 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 childelement:

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

Error start event

[EXPERIMENTAL]

Description
An error start event can be used to trigger an event subprocess. 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, 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, the execution semantics default to the none end event semantics.

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 theerrorRef 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. Note: boundary timer events are only fired when the job executor is enabled (i.e. jobExecutorActivate needs to be set to true in theactiviti.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.errorpackage.

Signal Boundary event

[EXPERIMENTAL]

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.

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 is activated when the activity is attached to completes successfully. At this point, the corresponding subscription to 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" targetRef="undoBookHotel" /> sourceRef="compensateBookHotelEvt"

<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

[EXPERIMENTAL]

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

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

Example
See section on signal 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$MyExecutionLis tener" 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

[EXPERIMENTAL]

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

<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 acompensateEventDefinition 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 subelement. 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 orgenerating 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

[EXPERIMENTAL]

Description
The event based gateway allows to take a decision based on events. Each outgoing sequenceflow of the gateway needs to be connected to an intermediate catching event. When process execution reaches the 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 sequenceflow.

Graphical notation
An event based gateway gateway is visualized as a typical gateway (i.e. a diamond shape) 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 documentationelement.

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

<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 aresourceAssignmentExpression 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. Task that have an assignee are not visible in the task lists of other people, and are found in the so-called personal task list of the assignee. 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 areassigned 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 the 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 whengroup(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.

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 candidateusers/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 atask listener with an expression that listens to task create events. In the following example, the assignee will be set by calling thefindManagerOfEmployee 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). The Groovy jar is shipped by default with the Activiti distribution. 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.

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 using an assignment statement. In the example above, the 'sum' variable will be stored as a process variable after the script task has been executed. To avoid this behavior, scriptlocal variables can be used. In Groovy, the keyword 'def' must then be used: 'def sum = 0'. In that case, no process variable will be stored.

An alternative is to set variables through the current execution, which is available as a reserved variable called 'execution'.

<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 theactiviti: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.JavaDelegateinterface 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 theorg.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 theorg.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. fieldfistName 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 callingtext.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 aorg.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.ReverseStringsFieldInjecte d"> <extensionElements> <activiti:field name="text1"> <activiti:expression>${genderBean.getGenderString(gender)}</activiti:expressi on> </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.testExpressionFieldInje

ction

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

As of Activiti 5.9, 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 or scripts. 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 (BusinessExeption e) { throw new BpmnError("BusinessExeptionOccured"); } } }
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); } }

WebService Task
[EXPERIMENTAL]

Description
A WebService task is used to synchronously invoke an external web service.

Graphical Notation
A WebService task is visualized the same as a Java service task.

XML representation
To use a WebService 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 WebService:

<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 WebService 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 WebService task by using the ##WebService implementation and a reference to the WebService operation.

<serviceTask id="webService" name="Web service invocation" implementation="##WebService" operationRef="tns:prettyPrintCountOperation">

WebService task IO Specification

Unless we are using the simplistic approach for data input and output associations (See below), each WebService 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>

WebService 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>

WebService 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

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.

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

Property
mailServerHost mailServerPort no

Required?
yes, if not on the default port

Description
The hostname of your mail server (e.g. mail.mycorp.com). Default is localhost The port for SMTP traffic on the mail server. The default is 25 The default e-mail address of the sender of e-mails, when none is provided by the user. By default this is [email protected] Some mail servers require credentials for sending e-mail. By default not set. Some mail servers require credentials for sending e-mail. By default not set.

mailServerDefaultFrom no mailServerUsername mailServerPassword if applicable for your server if applicable for your server

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

Property Required?
to from subject cc bcc charset html text yes no no no no no no no

Description
The recipients if the e-mail. Multiple recipients are defined in a comma-separated list The sender e-mail address. If not provided, the default configured from address is used. The subject of the e-mail. The cc's of the e-mail. Multiple recipients are defined in a comma-separated list The bcc's of the e-mail. Multiple recipients are defined in a comma-separated list Allows to change the charset of the email, which is necessary for many non-English languages. A piece of HTML that is the content of the e-mail. The 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.

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="[email protected]" /> <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

Property
endpointUrl language resultVariable

Required?
yes yes no

Description
The Mule endpoint you want to invoke. The language you want to use to evaluate the payloadExpression field. An expression that will be the message's payload. The name of the variable which will store the result of the invocation.

payloadExpression yes

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>

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 passthrough 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("wait") .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.4. Shell task parameter configuration

Property
command arg0-5 wait redirectError cleanEnv outputVariable directory

Required?
yes no no no no no no

Type
String String

Description
Shell command to execute. Parameter 0 to Parameter 5 false false

Default

true/false wait if necessary, until the shell process has terminated. true true/false Merge standard error with the standard output. true/false Shell process does not inherit current environment. String String String Name of variable to contain the output Name of variable to contain result error code Default directory of shell process

Output is not recorded. Error level is not registered. Current directory

errorCodeVariable no

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.p vm.delegate.TaskListener andorg.activiti.engine.impl.pvm.el.Expression have been deprecated. From now on, you should useorg.activiti.engine.delegate.ExecutionListener, org.activiti.engine.delegate.TaskL

istener andorg.activiti.engine.delegate.Expression. In the new publicly available API, access toExecutionListenerExecution.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.

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 methodnotify(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 takeevents 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}" />

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.ExampleFieldInjectedExecutionLi stener" 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/ExecutionListenersFieldInjectionProc ess.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 o 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 anassignment 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. class: the delegation class that must be called. This class must implement theorg.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}" />

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:

User task Script task Java service task Web service task Business rule task Email task Manual task Receive task (embedded) subprocess Call 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.

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, foziee]. 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 themultiInstanceCharacteristics:

<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 multiinstance 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>

Subprocesses and Callactivities

SubProcess
Description
A subprocess is an activity that contains other activities, gateways, events, etc. which on itself form a process that is part of the bigger process. Asubprocess is completely defined inside a parent process (that's why it's often called an embedded subprocess). Subprocesses have two major use cases:

Subprocesses allow hierarchical modeling. Many modeling tools allow that subprocesses can be collapsed, hiding all the details of the subprocess and displaying a high-level end-to-end overview of the business process. A subprocess creates a new scope for events. Events that are thrown during execution of the subprocess, can be caught by a boundary event on the boundary of the subprocess, thus creating a scope for that event limited to the subprocess.

Using a subprocess does impose some constraints:

A subprocess can only have one none start event, no other start event types are allowed. A subprocess must at least have one end event. Note that the BPMN 2.0 specification allows to omit the start and end events in a subprocess, but the current Activiti implementation does not support this. Sequence flow can not cross subprocess boundaries.

Graphical Notation
A subprocess is visualized as a typical activity, i.e. a rounded rectangle. In case the subprocess is collapsed, only the name and a plus-sign are displayed, giving a high-level overview of the process:

In case the subprocess is expanded, the steps of the subprocess are displayed within the subprocess boundaries:

One of the main reasons to use a subprocess, 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 subprocess.

XML representation
A subprocess is defined by the subprocess element. All activities, gateways, events, etc. that are part of the subprocess, need to be enclosed within this element.

<subProcess id="subProcess"> <startEvent id="subProcessStart" /> ... other subprocess elements ... <endEvent id="subProcessEnd" /> </subProcess>

Event subprocess
[EXPERIMENTAL]

Description
The event subprocess is new in BPMN 2.0. An event subprocess is a subprocess that is triggered by an event. An event subprocess 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 subprocesses. An event subprocess might be triggered using events lit 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 subprocess is created. The subscription is removed when the scope is destroyed.

An event subprocess may be interrupting or non interrupting. An interrupting subprocess cancels any executions in the current scope. A non interrupting event subprocess spawns a new concurrent execution. While an interrupting event subprocess can only be triggered once for each activation of the scope hosting it, a non interrupting event subprocess can be triggered multiple times. The fact whether the subprocess is interrupting is configured using the start event triggering the event subprocess. An event subprocess must not have any incoming or outgoing sequence flows. Since an event subprocess is triggered by an event, an incoming sequence flow makes no sense. When an event subprocess is ended, either the current scope is ended (in case of an interrupting event subprocess), or the concurrent execution spawned for the non-interrupting subprocess is ended. Current limitations:

Activiti only supports interrupting event subprocesses. Activiti only supports event subprocess triggered using an error start event.

Graphical Notation
An event subprocess might be visualized as a an embedded subprocess with a dotted outline.

XML representation
An event subprocess 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 subprocess triggered using an error start event. The event subprocess is located "at process level", i.e. is scoped to the process instance:

This is how the event subprocess 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 subprocess 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 subprocess, 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 onconcurrency 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 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 jbpm4 we call '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 nonexclusive.

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

Chapter 9. Forms

Table of Contents Form properties External form rendering 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 asStrings. 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 FormDatareturn 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 <activiti:formProperty <activiti:formProperty <activiti:formProperty required="true" /> </extensionElements> </userTask>

id="room" /> id="duration" type="long"/> id="speaker" variable="SpeakerName" writable="false" /> id="street" expression="#{address.street}"

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

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 withformProperty.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() andInputStream

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

Table of Contents Requirements Configuration Usage Simple Example Query JPA process variables Advanced example using Spring beans and 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 (/activitispring/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 orjpaPersistenceUnitName. 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 EntityManagerinstances. 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 theEntityManagerFactory. 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 onlyvariableValueEquals(name, entity) is supported for JPA-Entities on ProcessInstanceQuery and ExecutionQuery. MethodsvariableValueNotEquals, variableValueGreaterThan, variableValueGreaterThanOrEqua

l, variableValueLessThan andvariableValueLessThanOrEqual 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: o 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.

o o o

UserTask that allows a manager to review the request and approve/disapprove, which is stored as a boolean variableapprovedByManager 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 methodexpressions. The process requires no custom java-code at all (except for the Spring-bean off course) and speeds up development drastically.

Chapter 11. History

Table of Contents Querying history HistoricProcessInstanceQuery HistoricActivityInstanceQuery HistoricDetailQuery HistoricTaskInstanceQuery History configuration History for audit purposes 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 4 history entities:

HistoricProcessInstances containing information about current and past process instances. HistoricActivityInstances containing information about a single execution of an activity. 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 4 of the History entities. The HistoryService exposes the the methodscreateHistoricProcessInstanceQuery(), createHistoricActivityInstanceQuery(), cre ateHistoricDetailQuery() andcreateHistoricTaskInstanceQuery(). 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);

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 HISTORY_*constants defined on ProcessEngineConfiguration:

ProcessEngine processEngine = ProcessEngineConfiguration .createProcessEngineConfigurationFromResourceDefault() .setHistory(ProcessEngineConfiguration.HISTORY_AUDIT) .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. No details will be archived

audit: This is the default. It archives all process instances, activity instances 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 like process variable updates.

History for audit purposes

When configuring at least audit level for configuration. Then all properties submitted through methodsFormService.submitStartFormData(String processDefinitionId, Map<String,

String> properties) andFormService.submitTaskFormData(String taskId, Map<String, String> properties) are recorded.

[KNOWN LIMITATION] Currently the forms as worked out in Activiti Explorer do not yet use the submitStartFormData and submitTaskFormData. So the form properties are not yet archived when using the forms in Activity Explorer. A workaround is to set the historyLevel to full and use the variableUpdates to see what values were set in userTasks. @see ACT-294 Form properties can be retrieved with the query API like this:

historyService .createHistoricDetailQuery() .onlyFormProperties() ... .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

Table of Contents 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 Activiti comes with an Eclipse plugin, the Activiti Eclipse Designer, that can be used to graphically model, test and deploy BPMN 2.0 processes. The Activiti tool stack offers two modeling / design tools with the Activiti Modeler and the Activiti Designer. You can of course use these tools in your own way, but a common way of working is to use the Activiti Modeler for high level modeling. There should be no technical knowledge necessary to model a process definition with the Activiti Modeler. The Activiti Designer can then be used to add the necessary technical details, like Java service tasks, execution listeners etc. With the import functionality of the Activiti Designer this workflow is well supported.

Installation
The following installation instructions are verified on Eclipse Indigo and Helios. 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.

A BPMN 2.0 XML file and an image of the process are automatically generated after each save of the Activiti diagram (the automatic generation can be switched of in the Eclipse preferences in the Activiti tab).

BPMN 2.0 XML files can be imported into the Activiti Designer and a diagram will be created. There are two ways supported to import a BPMN 2.0 XML file. One is to right-click on the Activiti project in the package explorer and choose the Import BPMN 2.0 file option at the bottom of the popup menu. Then you can choose the BPMN 2.0 XML via the file select dialog and the diagram is created. A second option is to import the BPMN 2.0 XML file to the src/main/resources/diagrams folder of your project (the filename should end with .bpmn20.xml). Then when you open the BPMN 2.0 XML file the diagram is created. Note that the Activiti Designer is able to read the BPMN DI information from the BPMN 2.0 XML file, but in this version the diagram is created by parsing and analyzing the BPMN 2.0 XML only, because this gives the best result. This means that import support is available even for BPMN 2.0 XML files without BPMN DI information.

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 BPMN 2.0 XML is opened in the Activiti XML editor, which provides content assist. Note that there are 2 main XSDs configured, the BPMN 2.0 spec XSD and the Activiti extensions XSD. These two XSDs are not yet aligned in a good manner.

A basic validation is performed every time an Activiti diagram is saved and possible errors are displayed in the Eclipse problem view.

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 event, end event, sequence flow, parallel gateway, exclusive gateway, embedded subprocess, call activity, script task, user task, service task, mail task, manual task, timer boundary event and error boundary 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 expanded embedded sub processes. For this version no hierarchical support for embedded sub processes is provided. This means you can't 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 rightclick 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

[EXPERIMENTAL] 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 theprojects/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 (Galileo or Helios should both 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> ... </pom>
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</groupId> <artifactId>activiti-designer-integration</artifactId> <version>5.7</version> <!-- Current Activiti Designer Version --> <scope>compile</scope> </dependency> </dependencies> ... <repositories> <repository> <id>Activiti</id> <url>http://maven.alfresco.com/nexus/content/repositories/activiti/</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</ActivitiDesignerExtension-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 thesrc/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; 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 theActiviti 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, your refer to the runtime class that should be used by the engine. This class should implement JavaDelegate as for any ServiceTask in Activiti. A shape's class is a simple Java class, to which a number of annotations are added. The class should implement the CustomServiceTaskinterface, 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(delegationClass = "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.

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.

The final step for your shape is to indicate the class that is instantiated by the Activiti engine when it reaches your node when executing a process instance. To do this, you use the @Runtime annotation. The delegationClass attribute you return should contain the canonical name of the runtime class. Note that the runtime class shouldn't be in your extension JAR, as it's dependent on the Activiti libraries.

@Runtime(delegationClass = "org.acme.runtime.AcmeMoneyJavaDelegation")

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 SimpleDateFormatclass. 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. ForMULTILINE_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 theorderable 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. 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 to be saved. You can compare these extensions to the BPMN 2.0 validation, BPMN 2.0 export and process image saving that's performed during save actions by default in Activiti Designer. In fact, these functions use exactly the same extension features you can use to save to your own formats. 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 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:

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 also access the diagram through Resources andInputStreams for the diagram's content using these methods in 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 clearMarkers(getResource(diagram.eResource().getURI()));

You should also use the progress monitor provided 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

Create an extension to the org.activiti.designer.eclipse.extension.validation.ProcessValidator extension point in yourplugin.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.export.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.

<?eclipse version="3.6"?> <plugin> <extension point="org.activiti.designer.eclipse.extension.export.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 marshallDiagram(Diagram diagram, IProgressMonitor

monitor) method. You are provided with the diagram object, which contains all of the information about the objects in the
diagram (BPMN constructs) and the graphical representation. 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. For example:

final boolean validDiagram = invokeValidator(AcmeConstants.ACME_VALIDATOR_ID, diagram, monitor); if (!validDiagram) { addProblemToDiagram(diagram, "Marshalling to " + getFormatName() + " format was skipped because validation of the diagram failed.", null); } else { //proceed with marshalling }
As you can see, here we have chosen to cancel the marshalling if the validator (identified by a constant here) returns false as result. We have also added an additional marker to the diagram so the user can see an explanation why the file wasn't created. This is not required, but seems helpful to the user and shows how you can use these utilities from both ProcessValidators and ExportMarshallers. Once you have all the data you need, you should invoke the saveResource() method to create a file containing your data. You can invokesaveResource() 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 some of the methods 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, but here's an example how to use one of them:

private static final String FILENAME_PATTERN = ExportMarshaller.PLACEHOLDER_ORIGINAL_FILENAME + ".acme.axml"; ... saveResource(getRelativeURIForDiagram(diagram, FILENAME_PATTERN), bais, this.monitor);
What happens here is that a static member is used to describe the filename pattern (this is just a best practice, you can specify the string any way you like of course) and the pattern uses the ExportMarshaller.PLACEHOLDER_ORIGINAL_FILENAME constant to insert a variable for the original filename. Later on in the marshallDiagram() method, getRelativeURIForDiagram() is invoked and it will parse the filename for any variables and substitute them. You provide saveResource() with an InputStream to your data and it will save the data to a resource with a relative path to the original diagram.

Again, you should also 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

Table of Contents Case overview Cases Start process instances My instances Administration Changing the database Activiti Explorer is a web application that is installed during the demo setup. After logging into the application, you will see three large icons that show the main capabilities.

Cases: case and 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. Note that in Explorer we talk about cases rather than tasks. As Explorer allows to relate content, divide work into subtasks, involve people in different roles, etc ... the term case covers better what is possible. Activiti Explorer as such can be used to create cases that are not related to

processes (i.e. standalone cases). Process: shows the deployed process definitions, and allows to start new process instances. 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.

Case overview

Cases

Inbox: shows the cases where the logged in user is the assignee. My Cases: shows the cases where the logged in user is the owner. When you create a standalone case, you are automatically made owner of the case. Queued: shows the different groups which you are part of. Cases here must first be claimed before they can be completed. Involved: shows the cases where the logged in user is involved with (i.e. not assignee or owner). Archived contains the past (historical) cases.

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 cases assigned to specific groups.

Changing the database

To change the database that Explorer uses in the demo setup, change the properties file apps/apache-timcat-

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-timcat-6.x/webapps/activitiexplorer/WEB-INF/lib/).

Chapter 14. Activiti add-on components

Table of Contents cycle Activiti Modeler based on Signavio Core components

cycle
Started off as Activiti Cycle and now moved to the camunda fox BPM Platform, Cycle is web application that provides a collaborative platform for different stakeholders of BPM projects (Business, analysts, developers, managers, IT operations, ...). It combines different data sources like the Activiti Modeler repository, Subversion or your local file system into a single view which makes it easy to browse all the artifacts (process models, development projects, requirements, ...) that are involved in such a project. Additionally you can maintain relationships between them and cycle provides built in actions like moving artifacts between repositories or downloading different formats of process models. A plug-in infrastructure is provided to hook in own repositories, actions or functionality. The concept of Cycle, especially with the philosophy of Business-IT-Alignment is new. You might best compare it to Application Lifecycle Management (ALM) tools. Cycle is developed by camunda and no longer aprt of the Activiti project.

Activiti Modeler based on Signavio Core components

Signavio has a web based BPMN process modeler. There is a tweaked version for easy development with a file based backend. That can be found in the Google project Signavio core components We've documented some instructions on how to build it and how to use it with Activiti in the wiki page How to build Activiti Modeler from Signavio

Chapter 15. REST API

Table of Contents 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 Start Process Instance List Process Instances Get Process Instance Details

Get Process Instance Diagram Tasks Get Task Summary List Tasks Get Task Get Task Form Perform Task Operation List Form Properties Add attachment to a task Add url to a task Identity Login Get User List User's Groups Get Group List Group Users Management List Jobs Get Job Execute Job Execute Jobs List Database Tables Get Table Meta Data Get Table Data Activiti includes a REST API to the engine that will be deployed to your server when you run the setup script. The REST API uses JSON format (http://www.json.org) and is built upon the Restlet (http://www.restlet.org). Each REST API call has its individual authorization level and you must be logged in as a user to invoke a REST API call (except for the /login service). Authentication is done using Basic HTTP Authentication, so if you logged in as an admin (i.e. kermit) you should be able to perform all calls as described below. The API follows normal REST API conventions using GET for read operations, POST for creating objects, PUT for updating and performing operations on already created objects and finally DELETE for deleting objects. When performing a call that affects multiple objects POST is used on all such operations for consistency and making sure that an unlimited number of objects may be used. The reason for using POST is that the HTTP DELETE method doesn't implicitly allow request bodies and therefore, a call using DELETE, in theory, could get it's request body stripped out by a proxy. So to be certain this doesn't happen we use POST, even when PUT could have been used to update multiple objects, for consistency. All rest calls use a content type of "application/json" (except for upload requests which uses "multipart/form-data"). The base URL for invoking a REST call is http://localhost:8080/activiti-rest/service/. So for example to list the process definitions in the engine point your browser to: http://localhost:8080/activiti-rest/service/process-definitions Please look below to see what REST API calls that currently are available. Please consider the "API" sections as a "one line hint" to what functionality of the core API that is used to implement the REST API call.

Repository
Upload Deployment
Uploads and installs a deployment of format .bpmn20.xml, .bar or .zip using normal "html form upload" (enctype=multipart/form-data) in other words not a json-request. To make it possible for the ui to react when the upload is complete it is possible to submit success/failure callbacks as parameters. I.e. Sending "success=alert" will result in that the string "alert" will be placed inside a JS script block with "();" appended to the end, in other words "alert();". Sending "failure=alert" will result in "alert('Some error message if any');" inside a script block. The actual deployment file shall be placed in a parameter named "deployment".

Request: POST /deployment

success={success}&failure={success}&deployment={file}
API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getRepository

Service().createDeployment().name(fileName).deploymentBuilder.deploy()
Response:

<html> <script type="text/javascript"> alert(); </script> </html>

Get Deployments
Returns a paginated list deployments that can be sorted by "id", "name" or "deploymentTime".

Request: GET

/deployments?start={start=0}&size={size=10}&sort={sort=id}&order={order=asc} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getRepository Service().createDeploymentQuery().listPage()

Response:

{ "data": [ { "id": "10", "name": "activiti-examples.bar", "deploymentTime": "2010-10-13T14:54:26.750+02:00" } ], "total": 1, "start": 0, "sort": "id", "order": "asc", "size": 1 }

Get Deployment Resources

Returns all resources from the deployment. Example: /deployment/10/resources

Request: GET /deployment/{deploymentId}/resources API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getRepository

Service().getDeploymentResourceNames(deploymentId)
Response:

{ "resources": [ { "id": "10", "name": "activiti-examples.bar", "deploymentTime": "2010-10-13T14:54:26.750+02:00" } ] }

Get Deployment Resource

Returns a resource from the deployment. Example: /deployment/10/resource/org/activiti/examples/bpmn/usertask/FinancialReportProcess.bpmn20.xml

Request: GET /deployment/{deploymentId}/resource/{resourceName} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getRepository

Service().getResourceAsStream(deploymentId, resourceName)
Response:

I.e a .bpmn20.xml file, an image or whatever type of file the deployment resource contained.

Delete Deployment
Deletes a deployment.

Request: DELETE /deployment/{deploymentId}?cascade={cascade?} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getRepository

Service().deleteDeployment(deploymentId)
Response:

{ "success": true }

Delete Deployments
Deletes multiple deployment.

Request: POST /deployments?cascade={cascade?}

{ "deploymentIds": [ "10", "11" ] }

API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getRepository

Service().deleteDeployment(deploymentId)
Response:

{ "success": true }

Engine
Get Process Engine
Returns the process engine initialization details. If something went wrong during startup, details about the error will be given in the "exception" attribute in the response.

Request: GET /process-engine API: ProcessEngines.getProcessEngine(configuredProcessEngineName) Response:

{ "name": "default", "resourceUrl": "jar:file:\//<path-to-deployment>\/activiticfg.jar!\/activiti.properties", "exception": null, "version": "5.9" }

Processes
List Process Definitions
Returns details about the deployed process definitions that can be sorted by "id", "name", "version" or "deploymentTime". The name of the BPMN2.0 XML process diagram is given in the "resourceName" attribute and can, in combination with the "deploymentId" attribute, be retrieved from the GET Deployment Resource REST API call above.

Paginated Request: GET /process-

definitions?start={start=0}&size={size=10}&sort={sort=id}&order={order=asc} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getRepository Service().createProcessDefinitionQuery().listPage()

Paginated Response:

{ "data": [ { "id": "financialReport:1", "key": "financialReport", "version": 1,

"name": "Monthly financial report", "resourceName": "org/activiti/examples/bpmn/usertask/FinancialReportProcess.bpmn20.xml", "diagramResourceName": "org/activiti/examples/bpmn/usertask/FinancialReportProcess.png", "deploymentId": "10", "startFormResourceKey": null, "isGraphicNotationDefined": true } ], "total": 1, "start": 0, "sort": "id", "order": "asc", "size": 1 }

Get Process Definition Form Properties

Returns a process definition's form properties.

Request: GET /process-definition/{processDefinitionId}/properties API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getFormServic

e().getStartFormData(processDefinitionId)
Response:

"data": [ { "id": "fullName", "name": "Full name", "value": "${name}", "type": "String", "required": false, "readable": true, "writeable": true } ]

Get Process Definition Form Resource

Returns a process definition's form.

Request: GET /process-definition/{processDefinitionId}/form API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskServic

e().getRenderedStartFormById(processDefinitionId)
Response:

<user-defined-response>

Start Process Instance

Creates a process instance based on a process definition and returns details about the newly created process instance. Additional variables (from a form) may be passed using the body object. In other words placing attributes next to the "processDefinitionId" attribute. Note that if a value is submitted as true (instead of "true") it will be treated as a Boolean even if no descriptor is used. The same is also valid for number, i.e., 123 will become an Integer but "123" will become a String (unless a descriptor is defined).

Request: POST /process-instance

{ "processDefinitionId":"financialReport:1:1700", "businessKey":"order-4711" }
API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getRuntimeSer

vice().startProcessInstanceById(processDefinitionId[, businessKey][, variables])

Response:

{ "id": "217", "processDefinitionId": "financialReport:1:1700", "businessKey": "order-4711", "processInstanceId": "217" }

List Process Instances

Returns details about the active process instances that can be sorted by "id", "startTime", "businessKey" or "processDefinitionId". You can filter instances by "processDefinitionId" and "businessKey".

Paginated Request: GET /process-

instances?start={start=0}&size={size=10}&sort={sort=id}&order={order=asc}&bus inessKey={businessKey}&processDefinitionId={processDefinitionId} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getHistorySer vice().createHistoricProcessInstanceQuery().xxx.listPages()

Paginated Response: { "data": [ { "id": 2, "processDefinitionId": "financialReport:1", "businessKey": 55, "startTime": "2010-10-13T14:54:26.750+02:00", "startUserId": "kermit" } ], "total": 1, "start": 0, "sort": "id", "order": "asc",

"size": 1 }

Get Process Instance Details

Returns all details about a specific process instance. This can be a running or completed process instance.

Request: GET /processInstance/{processInstanceId} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getHistorySer

vice().createHistoricProcessInstanceQuery().processInstanceId(..).singleResul t()
Response: { "id": 2, "processDefinitionId": "financialReport:1", "businessKey": 55, "startTime": "2010-10-13T14:54:26.750+02:00", "startActivityId": "startFinancialAnalysis", "startUserId": "kermit", "completed": false, "tasks": [ { "taskId": 3, "taskName": "Analyze report", "owner": null, "assignee": "Kermit", "startTime": "2010-10-13T14:53:26.750+02:00", "completed": false } ], "activities": [ { "activityId": 4, "activityName": "Get report", "activityType": "ServiceTask", "startTime": "2010-10-13T14:53:25.750+02:00", "completed": true, "startTime": "2010-10-13T14:53:25.950+02:00", "duration": 200 } ], "variables": [ { "variableName": "reportName", "variableValue": "classified.pdf", "variableType": "String", "revision": 1, "time": "2010-10-13T14:53:26.750+02:00" } ]

Get Process Instance Diagram

Returns a PNG diagram of process with highlighted active executions. Returns 404 if process definition does not contain DI information.

Request: GET /processInstance/{processInstanceId}/diagram API: ProcessDiagramGenerator.generateDiagram(pde, "png",

getRuntimeService().getActiveActivityIds(processInstanceId));
Response:

Png diagram of process with highlighted active executions.

Tasks
Get Task Summary
Returns a task summary for a specific user: The number of tasks assigned the user, how many unassigned tasks that the user may claim and how many unassigned tasks there are per group that the user is a member of.

Request: GET /tasks-summary?user={userId} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskServic

e().createTaskQuery().xxx().count()
Response:

{ "assigned": { "total": 0 }, "unassigned": { "total": 1, "groups": { "accountancy": 1, "sales": 0, "engineering": 0, "management": 0 } } }

List Tasks
Returns a paginated list of tasks that can be sorted by: "id", "name", "description", "priority", "assignee", "executionId" or "processInstanceId". The list must be based on a user of a specific role: assignee (lists the tasks assigned to the user) or candidate (lists the tasks that the user may claim) or a candidate group (lists tasks that the members of the group may claim). If the task has a form it is given in the "formResourceKey" attribute. The form for a task can be retrieved from the GET Task Form REST API call.

Paginated Request: GET /tasks?[assignee={userId}|candidate={userId}|candidate-

group={groupId}]&start={start=0}&size={size=10}&sort={sort=id}&order={order=a sc} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskServic e().createTaskQuery().xxx().listPage()

Paginated Response:

{ "data": [ { "id": 127, "name": "Handle vacation request", "description": "Vacation request by Kermit", "delegationState": "pending", "dueDate": "2010-10-13T14:54:26.750+02:00", "priority": 50, "assignee": null, "executionId": 118, "formResourceKey": "org/activiti/examples/taskforms/approve.form", "owner": "Kermit", "parentTaskId": 120, "processDefinitionId": "financialReport:1", "processInstanceId": "123", "taskDefinitionKey": "125" } ], "total": 1, "start": 0, "sort": "id", "order": "asc", "size": 1 }

Get Task
Returns details about the task with the task id.

Request: GET /task/{taskId} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskServic

e().createTaskQuery().taskId(taskId).singleResult()
Response:

{ "id": "127", "name": "Handle vacation request", "description": "Vacation request by Kermit", "delegationState": "pending", "dueDate": "2010-10-13T14:54:26.750+02:00", "priority": 50, "assignee": null, "executionId": 118, "formResourceKey": "org/activiti/examples/taskforms/approve.form", "owner": "Kermit",

"parentTaskId": 120, "processDefinitionId": "financialReport:1", "processInstanceId": "123", "taskDefinitionKey": "125", "subTaskList": [ { "id": "129", "name": "Analyze request", "description": "Analyze request", "delegationState": "pending", "dueDate": "2010-10-13T14:54:26.750+02:00", "priority": 50, "assignee": null, "executionId": "118", "owner": "Kermit", "parentTaskId": "127" } ], "identityLinkList" : [ { "type": "candidate", "userId": "Fozzie", "groupId": null } ], "attachmentList" : [ { "id": "130", "name": "vacation_request.xls", "description": "Vacation request", "type": "application/pdf", "url": null } ] }

Get Task Form

Returns a task's form.

Request: GET /task/{taskId}/form API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskServic

e().getRenderedTaskForm(taskId)
Response:

<user-defined-response>

Perform Task Operation

Performs an operation (claim or complete) on a task. For the "complete" operation additional variables (from a form) may be passed in the body. To read more about additional variables from forms, visit the Start Process Instance section

Request: PUT /task/{taskId}/[claim|complete]

{}
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskServic

e().xxx(taskId ...)
Response:

{ "success": true }

List Form Properties

Returns a list of properties of a form of a running task, which is defined by the process.

Request: GET /form/{taskId}/properties API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getFormServic

e().getTaskFormData(taskId).getFormProperties()
Response:

{ "data": [ { "id": "userName", "name": "User", "value": "foobar", "type": "string", "required": "true", "readable": "true", "writable": "true" } ] }

Add attachment to a task

Add an attachment to a task instance

Request: PUT /task/{taskId}/attachment

{}
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskServic

e().createAttachment(...)
Response:

{ "id": "130", "name": "vacation_request.xls", "description": "Vacation request", "type": "application/pdf", "url": null }

Add url to a task

Add an url to a task instance

Request: PUT /task/{taskId}/url

{}
API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getTaskServic

e().createAttachment(...)
Response:

{ "id": "130", "name": "google.com", "description": "Good search sitet", "type": null, "url": "http://www.google.com" }

Identity
Login
Authenticates a user. If user and password doesn't match a response with status 403 is returned. If authentication is successful, a response with status 200 is returned.

Request: POST /login

{ "userId": "kermit", "password": "kermit" }

API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getIdentitySe

rvice().checkPassword(userId, password)
Response:

{ "success": true }

Get User
Returns details about a user.

Request: GET /user/{userId} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getIdentitySe

rvice().createUserQuery().userId(userId).singleResult();
Response:

{ "id": "kermit", "firstName": "Kermit",

"lastName": "the Frog", "email": "[email protected]" }

List User's Groups

Returns a paginated list groups belonging to a user that can be sort by "id", "name" or "type". To only get groups of a certain type use the "type" parameter.

Paginated Request: GET

/user/{userId}/groups[?type=groupType]?start={start=0}&size={size=10}&sort={s ort=id}&order={order=asc} API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getIdentitySe rvice().xxx(userId[, groupType])

Paginated Response:

{ data: [ { "id": "admin", "name": "System administrator", "type": "security-role" } ], "total": 1, "start": 0, "sort": "id", "order": "asc", "size": 1 }

Get Group
Returns details about a group.

Request: GET /group/{groupId} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getIdentitySe

rvice().createGroupQuery().groupId(groupId).singleResult();
Response:

{ "id": "admin", "name": "System administrator", "type": "security-role" }

List Group Users

Returns details about a group's users that can be sorted by "id", "firstName", "lastName" or "email".

Paginated Request: GET /groups/{groupId}/users

API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getIdentitySe

rvice().createUserQuery().memberOfGroup(groupId).list()
Paginated Response:

{ data: [ { "id": "kermit", "firstName": "Kermit", "lastName": "the Frog", "email": "[email protected]" } ], "total": 1, "start": 0, "sort": "id", "order": "asc", "size": 1 }

Management
List Jobs
Returns a paginated list of jobs that can be sorted by "id", "process-instance-id", "execution-id", "due-date", "retries" or some custom arbitrary property id. The list can also be filtered by process instance id, due date or if the jobs have retries, are executable or only have messages or timers.

Paginated Request: GET /management/jobs?process-

instance={processInstanceId?}&with-retriesleft={withRetriesLeft=false}&executable={axecutable=false}&onlytimers={onlyTimers=false}&only-messages={onlyMessage=false}&duedatelt={iso8601Date}&duedate-ltoe={iso8601Date}&duedate-ht={iso8601Date}&duedatehtoe={iso8601Date}&start={start=0}&size={size=10}&sort={sort=id}&order={order =asc} API: ProcessEngines.getProcessEngine(configuredProcessEngineName).createJobQuer y().xxx().listPage()

Paginated Response:

{ "data": [ { "id": "212", "executionId": "211", "retries": -1, "processInstanceId": "210", "dueDate": null, "assignee": null, "exceptionMessage": "Can\'t find scripting engine for \'groovy\'" } ],

"total": 1, "start": 0, "sort": "id", "order": "asc", "size": 1 }

Get Job
Returns details about a job.

Request: GET /management/job({jobId} API: ProcessEngines.getProcessEngine(configuredProcessEngineName).createJobQuer

y().id(jobId).singleResult()
Response:

{ "id": "212", "executionId": "211", "retries": -1, "processInstanceId": "210", "dueDate": null, "assignee": null, "exceptionMessage": "Can\'t find scripting engine for \'groovy\'", "stacktrace": "org.activiti.engine.ActivitiException: Can't find scripting engine for 'groovy'\n\tat ..." }

Execute Job
Executes a job.

Request: PUT /management/job/{jobId}/execute API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getManagement

Service().executeJob(jobId)
Response:

{ "success": true }

Execute Jobs
Executes multiple job.

Request: POST /management/jobs/execute

{ "jobIds": [ "212" ] }

API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getManagement

Service().executeJob(jobId)
Response:

{ "success": true }

List Database Tables

Returns meta data information about all database tables in the engine.

Request: GET /management/tables API: ProcessEngines.getProcessEngine(configuredProcessEngineName).getManagement

Service().getTableCount()
Response:

{ "data": [ { "tableName": "ACT_GE_PROPERTY", "noOfResults": 2 } ] }

Get Table Meta Data

Returns meta data about a database table.

Request: GET /management/table/{tableName} API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getManagement

Service().getTableMetaData(tableName))
Response:

{ "tableName": "ACT_GE_PROPERTY", "columnNames": ["REV_","NAME_","VALUE_"], "columnNames": ["class java.lang.Integer", "class java.lang.String", "class java.lang.String"] }

Get Table Data

Returns a paginated list of database table data.

Paginated Request: GET /management/table/{tableName}/data API:ProcessEngines.getProcessEngine(configuredProcessEngineName).getManagement

Service().createTablePageQuery().tableName(tableName).start(start).size(size) .orderXXX(sort).singleResult();
Paginated Response:

{ "data": [ { "NAME_": "schema.version", "REV_": "1", "VALUE_": "5.9" }, { "NAME_": "next.dbid", "REV_": "4", "VALUE_": "310" } ], "total": 2, "start": 0, "sort": "NAME_", "order": "asc", "size": 2 }

Chapter 16. CDI integration

Table of Contents 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 The activiti-cdi modules leverages both the configurability of activiti and the extensibility of cdi. The most prominent features of activiti-cdi are:

Support for @BusinessProcessScoped beans (Cdi beans the lifecycle of which is bound to a process instance), A custom El-Resolver for resolving Cdi beans (including EJBs) from the process, Declarative control over a process instance using annotations, Activiti is hooked-up to the cdi event bus, Works with both Java EE and Java SE, works with Spring, Support for unit testing.

In order to include activiti-cdi in a maven project, we add the following maven dependency:

<dependency> <groupId>org.activiti</groupId> <artifactId>activiti-cdi</artifactId> <version>5.x</version> </dependency>

Replace 'x' with your activiti-version (>=5.6). This will pull-in activiti-engine and spring.

Setting up activiti-cdi
Activiti cdi can be setup in different environments. In this section we briefly walk through the configuration options.

Looking up a Process Engine

The cdi extension needs to get access to a ProcessEngine. To achieve this, an implementation of the interfaceorg.activiti.cdi.spi.ProcessEngineLookup is looked up at runtime. The cdi module ships with a default implementation namedorg.activiti.cdi.impl.LocalProcessEngineLookup, which uses the ProcessEngines-Utility class for looking up the ProcessEngine. In the default configuration ProcessEngines#NAME_DEFAULT is used to lookup the ProcessEngine. This class might be subclassed to set a custom name. NOTE: needs an activiti.cfg.xml configuration on the classpath. Activiti cdi uses a java.util.ServiceLoader SPI for resolving an instance of org.activiti.cdi.spi.ProcessEngineLookup. In order to provide a custom implementation of the interface, we need to add a plain text file named META-

INF/services/org.activiti.cdi.spi.ProcessEngineLookup to our deployment, in which we specify the

fully qualified classname of the implementation.

Note
If you do not provide a custom org.activiti.cdi.spi.ProcessEngineLookup implementation, activiti will use the defaultLocalProcessEngineLookup implementation. In that case, all you need to do is providing a activiti.cfg.xml file on the classpath (see next section).

Configuring the Process Engine

Configuration depends on the selected ProcessEngineLookup-Strategy (cf. previous section). Here, we focus on the configuration options available in combination with the LocalProcessEngineLookup, which requires us to provide a Spring activiti.cfg.xml file on the classpath. Activiti offers different ProcessEngineConfiguration implementations mostly dependent on the underlying transaction management strategy. The activiti-cdi module is not concerned with transactions, which means that potentially any transaction management strategy can be used (even the Spring transaction abstraction). As a convenience, the cdi-module provides two custom ProcessEngineConfiguration implementations:

org.activiti.cdi.CdiJtaProcessEngineConfiguration: a subclass of the activiti

JtaProcessEngineConfiguration, can be used if JTA-managed transactions should be used for activiti org.activiti.cdi.CdiStandaloneProcessEngineConfiguration: a subclass of the activiti StandaloneProcessEngineConfiguration, can be used if plain JDBC transactions should be used for activiti

The following is an example activiti.cfg.xml file for JBoss 7:

<?xml version="1.0" encoding="UTF-8"?> <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"> <!-- lookup the JTA-Transaction manager --> <bean id="transactionManager" class="org.springframework.jndi.JndiObjectFactoryBean"> <property name="jndiName" value="java:jboss/TransactionManager"></property> <property name="resourceRef" value="true" /> </bean> <!-- process engine configuration --> <bean id="processEngineConfiguration" class="org.activiti.cdi.CdiJtaProcessEngineConfiguration"> <!-- lookup the default Jboss datasource --> <property name="dataSourceJndiName" value="java:jboss/datasources/ExampleDS" /> <property name="databaseType" value="h2" /> <property name="transactionManager" ref="transactionManager" /> <!-- using externally managed transactions --> <property name="transactionsExternallyManaged" value="true" /> <property name="databaseSchemaUpdate" value="true" /> </bean> </beans>
And this is how it would look like for Glassfish 3.1.1 (assuming a datasource named jdbc/activiti is properly configured): <?xml version="1.0" encoding="UTF-8"?> <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"> <!-- lookup the JTA-Transaction manager --> <bean id="transactionManager" class="org.springframework.jndi.JndiObjectFactoryBean"> <property name="jndiName" value="java:appserver/TransactionManager"></property> <property name="resourceRef" value="true" /> </bean> <!-- process engine configuration --> <bean id="processEngineConfiguration" class="org.activiti.cdi.CdiJtaProcessEngineConfiguration"> <property name="dataSourceJndiName" value="jdbc/activiti" /> <property name="transactionManager" ref="transactionManager" /> <!-- using externally managed transactions --> <property name="transactionsExternallyManaged" value="true" />

<property name="databaseSchemaUpdate" value="true" /> </bean> </beans>

(Note that the above configuration requires the "spring-context" module.) The configuration in a Java SE environment looks exactly like the examples provided in section Creating a ProcessEngine, substitute "CdiStandaloneProcessEngineConfiguration" for "StandaloneProcessEngineConfiguration".

Deploying Processes
Processes can be deployed using standard activiti-api (RepositoryService). In addition, activiti-cdi offers the possibility to auto-deploy processes listed in a file named processes.xml located top-level in the classpath. This is an example processes.xml file:

<?xml version="1.0" encoding="utf-8" ?> <!-- list the processes to be deployed --> <processes> <process resource="diagrams/myProcess.bpmn20.xml" /> <process resource="diagrams/myOtherProcess.bpmn20.xml" /> </processes>

Contextual Process Execution with CDI

In this section we briefly look at the contextual process execution model used by the activiti cdi extension. A BPMN business process is typically a long-running interaction, comprised of both user and system tasks. At runtime, a process is split-up into a set of individual units of work, performed by users and/or application logic. In activiti-cdi, a process instance can be associated with a cdi scope, the association representing a unit of work. This is particularly useful, if a unit of work is complex, for instance if the implementation of a UserTask is a complex sequence of different forms and "non-process-scoped" state needs to be kept during this interaction. In the default configuration, process instances are associated with the "broadest" active scope, starting with the conversation and falling back to the request if the conversation context is not active.

Associating a Conversation with a Process Instance

When resolving @BusinessProcessScoped beans, or injecting process variables, we rely on an existing association between an active cdi scope and a process instance. Activiti-cdi provides the org.activiti.cdi.BusinessProcess bean for controlling the association, most prominently:

the startProcessBy*(...)-methods, mirroring the respective methods exposed by the activiti RuntimeService allowing to start and subsequently associating a business process, resumeProcessById(String processInstanceId), allowing to associate the process instance with the provided id,

resumeTaskById(String taskId), allowing to associate the task with the provided id (and by extension, the
corresponding process instance),

Once a unit of work (for example a UserTask) is completed, the completeTask() method can be called to disassociate the conversation/request from the process instance. This signals activiti that the current task is completed and makes the process instance proceed.

Note that the BusinessProcess-bean is a @Named bean, which means that the exposed methods can be invoked using expression language, for example from a JSF page. The following JSF2 snippet begins a new conversation and associates it with a user task instance, the id of which is passed as a request parameter (e.g. pageName.jsf?taskId=XX):

<f:metadata> <f:viewParam name="taskId" /> <f:event type="preRenderView" listener="#{businessProcess.startTask(taskId, true)}" /> </f:metadata>

Declaratively controlling the Process

Activiti-cdi allows declaratively starting process instances and completing tasks using annotations. [email protected] annotation allows to start a process instance either by "key" or by "name". Note that the process instance is started after the annotated method returns. Example:

@StartProcess("authorizeBusinessTripRequest") public String submitRequest(BusinessTripRequest request) { // do some work return "success"; }

Depending on the configuration of activiti, the code of the annotated method and the starting of the process instance will be combined in the same transaction. The @org.activiti.cdi.annotation.CompleteTask-annotation works in the same way:

@CompleteTask(endConversation=false) public String authorizeBusinessTrip() { // do some work return "success"; }

The @CompleteTask annotation offers the possibility to end the current conversation. The default behavior is to end the conversation after the call to activiti returns. Ending the conversation can be disabled, as shown in the example above.

Referencing Beans from the Process

Activiti-cdi exposes CDI beans to activiti El, using a custom resolver. This makes it possible to reference beans from the process:

<userTask id="authorizeBusinessTrip" name="Authorize Business Trip" activiti:assignee="#{authorizingManager.account.username}" />

Where "authorizingManager" could be a bean provided by a producer method:

@Inject @ProcessVariable Object businessTripRequesterUsername; @Produces @Named public Employee authorizingManager() { TypedQuery<Employee> query = entityManager.createQuery("SELECT e FROM Employee e WHERE e.account.username='" + businessTripRequesterUsername + "'", Employee.class); Employee employee = query.getSingleResult(); return employee.getManager(); }
We can use the same feature to call a business method of an EJB in a service task, using the activiti:expression="myEjb.method()"-extension. Note that this requires a @Named-annotation on the MyEjb-class.

Working with @BusinessProcessScoped beans

Using activiti-cdi, the lifecycle of a bean can be bound to a process instance. To this extend, a custom context implementation is provided, namely the BusinessProcessContext. Instances of BusinessProcessScoped beans are stored as process variables in the current process instance.BusinessProcessScoped beans need to be PassivationCapable (for example Serializable). The following is an example of a process scoped bean:

@Named @BusinessProcessScoped public class BusinessTripRequest implements Serializable { private static final long serialVersionUID = 1L; private String startDate; private String endDate; // ... }
Sometimes, we want to work with process scoped beans, in the absence of an association with a process instance, for example before starting a process. If no process instance is currently active, instances of BusinessProcessScoped beans are temporarily stored in a local scope (I.e. the Conversation or the Request, depending on the context. If this scope is later associated with a business process instance, the bean instances are flushed to the process instance.

Injecting Process Variables

Process variables are available for injection. Activiti-CDI supports

type-safe injection of @BusinessProcessScoped beans using @Inject [additional qualifiers]

Type fieldName
unsafe injection of other process variables using the @ProcessVariable(name?) qualifier:

@Inject @ProcessVariable Object accountNumber; @Inject @ProcessVariable("accountNumber") Object account

In order to reference process variables using EL, we have similar options:

@Named @BusinessProcessScoped beans can be referenced directly, other process variables can be referenced using the ProcessVariables-bean: #{processVariables['accountNumber']}

Receiving Process Events

[EXPERIMENTAL] Activiti can be hooked-up to the CDI event-bus. This allows us to be notified of process events using standard CDI event mechanisms. In order to enable CDI event support for activiti, enable the corresponding parse listener in the configuration:

<property name="customPostBPMNParseListeners"> <list> <bean class="org.activiti.cdi.impl.event.CdiEventSupportBpmnParseListener" /> </list> </property>

Now activiti is configured for publishing events using the CDI event bus. The following gives an overview of how process events can be received in CDI beans. In CDI, we can declaratively specify event observers using the @Observes-annotation. Event notification is type-safe. The type of process events is org.activiti.cdi.BusinessProcessEvent. The following is an example of a simple event observer method:

public void onProcessEvent(@Observes BusinessProcessEvent businessProcessEvent) { // handle event }

This observer would be notified of all events. If we want to restrict the set of events the observer receives, we can add qualifier annotations:

@BusinessProcess: restricts the set of events to a certain process definition. Example: @Observes @BusinessProcess("billingProcess") BusinessProcessEvent evt @StartActivity: restricts the set of events by a certain activity. For example: @Observes @StartActivity("shipGoods") BusinessProcessEvent evt is invoke whenever an activity with the
id "shipGoods" is entered. @EndActivity: restricts the set of events by a certain activity. For example: @Observes @EndActivity("shipGoods") BusinessProcessEvent evt is invoke whenever an activity with the id "shipGoods" is left.

@TakeTransition: restricts the set of events by a certain transition.

The qualifiers named above can be combined freely. For example, in order to receive all events generated when leaving the "shipGoods" activity in the "shipmentProcess", we could write the following observer method:

public void beforeShippingGoods(@Observes @BusinessProcess("shippingProcess") @EndActivity("shipGoods") BusinessProcessEvent evt) {

// handle event }
In the default configuration, event listeners are invoked synchronously and in the context of the same transaction. CDI transactional observers (only available in combination with JavaEE / EJB), allow to control when the event is handed to the observer method. Using transactional observers, we can for example assure that an observer is only notified if the transaction in which the event is fired succeeds:

public void onShipmentSuceeded(@Observes(during=TransactionPhase.AFTER_SUCCESS) @BusinessProcess("shippingProcess") @EndActivity("shipGoods") BusinessProcessEvent evt) { // send email to customer. }

Additional Features

The ProcessEngine as well as the services are available for injection: @Inject ProcessEngine,

RepositoryService, TaskService, ...

The current process instance and task can be injected: @Inject ProcessInstance, Task, The current business key can be injected: @Inject @BusinessKey String businessKey, The current process instance id be injected: @Inject @ProcessInstanceId String pid,

Known Limitations
Although activiti-cdi is implemented against the SPI and designed to be a "portable-extension" it is only tested using Weld.