Keep informed?
Subscribe for our newsletter now!

Going Java Enterprise with Activiti and Jboss AS


Please note that this blog post is outdated, since we forked Activiti in March 2013 and started a new Open Source BPM project called camunda BPM ( You will find this topic and loads of more best practices, blueprints etc. there, so you should just have a look 🙂

Have you ever wondered whether processe-xml files could be picked up directly by activiti and deployed if they have changed? Or have you ever tried to use the same activiti instance with multiple applications and then invoke custom java code from the processes? We currently use activiti in a number of projects and often we get to a point where the default servlet-container-based configuration and infrastructure is not enough to satisfy all the requirements. Today, I want to briefly outline our technology stack for using activiti with Java EE. As with many of our projects, the stack is available open source for you to try out 🙂

Meeting Enterprise Requirements

In many instances, if services like clustering, reliable messaging, distributed transaction management or security are needed, it makes sense to move to an enterprise application server. Even if “lightweight” third party frameworks like Spring combined with additional infrastructure can offer comparable functionality for servlet containers, I still feel that moving to a full-fledged application server like JBoss AS makes sense, for two main reasons: first an application server offers such functionality in a robust, reliable and standards conform way and does so out of the box, and second, application servers and Java EE as such have become pretty lightweight themselves. In addition to these general requirements, I see a number of process-execution-specific problems, which need to be addressed:

  1. – Scoped deployment and classloading
  2. – Process versioning
  3. – Manageability
  4. – Integration with Jta, Ejb, Jms etc.

In many instances, I do not want to deploy the activiti process engine for each application, but instead, install a managed, centralized engine which can be used by each deployed application, without having the individual applications interfere with each other. The main reason for this is ensuring manageability. If I have a central process engine shared by different applications, I can access it with a uniform set of management and monitoring tools. Scoped deployment and classloading gives me the possibility to contain the classloader scope for each such application and ensure isolation. In addition, this also enables me to deploy multiple versions of the same application in parallel, by using a different name for each version. However, if I do this in combination with a central process engine, I need to make sure that the process engine can access the application-provided classes and resources when executing the process.

Deployment also needs to function incremental, i.e. if a new version of an application is deployed, potentially a new version of a process is deployed as well. This is discussed in greater detail here.


To solve this, we opted for the same approach we pursued for jBPM, back some time. We developed a custom jboss-deployer, which scans deployment archives for *.bpmn20.xml files, deploys the processes to a central process engine and takes care of classloading. Figure 1 shows the overall architecture. The deployer is shown in the bottom left corner of Figure 1. In addition, Figure 1 shows a schematic client application named client-app.ear. Such applications can be composed (but need not be) of different modules, like multiple jar modules containing EJBs, a WAR module and libraries. Figure 2 also shows a module named “process archive”. Process Archives are deployments such that the name ends in “.bar” (business archive) or a regular deployment (.jar / .war) containing a processes.xml –marker file. As already indicated, we deploy a central acitiviti process engine instance, labeled “activiti service” in Figure 1. The activiti service exposes the activiti CommandExecutor as an EJB with both local and remote interfaces. Client applications access the activiti service either by running commands on the CommandExecutor-EJB or by looking up the process engine in Jndi. This is handled by the “activiti client”, which makes the activiti services (such as the RuntimeService or the TaskService) available for injection (using the @EJB-annotation). Figure 2 shows the deployment infrastructure in more detail. Note that this is just an example. As already explained above, different “types” of deployments are supported, like .war/.jar/.ear etc.

Alternatively, the camunda fox PSI framework or the activiti-cdi module could be used to invoke EJBs (and different services) from the process.

In a clustered scenario, we deploy the same infrastructure (activiti-service, activiti-deployer) and applications on each cluster-node. Each node then accesses the same datasource, to share process definitions and process state.

Where can I get it?

If you are interested in trying out the activiti Java EE infrastructure, you can download a binary distribution or checkout the sources of activiti-java-ee. The project is licensed under LGPL.

Please note that in many instances you will probably want to customize the infrastructure to fit you individual needs. For example you could add a service registry, JMS queues etc. In any case, we are of course happy to assist you 😉

How can I use it?

In the following I briefly outline how to use the infrastructure presented above. I am assuming that you have a jboss appilcation server (5.1 / 6) installation available. We will start by installing the activiti infrastructure to the jboss distribution. To achieve this, you first need to download the activiti-java-ee distribution. It is a compressed archive containing two folders one for jboss-AS 5.1 and one for 6.0. Choose the right version for you server. You will then find different sub-folders named client, deployer, lib, service, setup, representing the individual components. We enter the setup folder. This folder contains an ant buildfile which can be used for installing / uninstalling the activiti-java-ee distributions to an existing jboss installation. The setup-folder also contains a properties file which we need to rename from “” to “”. The file contains a single configuration value called “jboss.home”. Make sure you put the absolute path of your jboss installation here. If we now invoke ant, the components of activiti-java-ee are installed into your jboss as. For the moment that is all.
If you want to configure activiti, you have different options. You can either use Spring in combination with the default “activiti.cfg.xml”, or, if you do not want to use Spring, you can configure activiti using a jboss-beans.xml file directly. To achieve this, enter the “service” folder and edit the “activiti-service-jboss-beans.xml” file. By default, it contains the following content:

<deployment xmlns="urn:jboss:bean-deployer:2.0">

	<bean name="ProcessEngineManager"
		<property name="processEngineConfiguration"><inject bean="ProcessEngineConfiguration" /></property>
		<property name="dataSourceJndiName">java:ActivitiDS</property>

	<bean name="ProcessEngineConfiguration"
		<property name="transactionManager"><inject bean="RealTransactionManager" /></property>		

		<install method="setTransactionsExternallyManaged"><parameter><value>true</value></parameter></install>
		<install method="setDatabaseSchemaUpdate"><parameter><value>true</value></parameter></install>
		<install method="setMailServerHost"><parameter><value>localhost</value></parameter></install>
		<install method="setMailServerPort"><parameter><value>2525</value></parameter></install>
		<install method="setJobExecutorActivate"><parameter><value>true</value></parameter></install>

Does look a lot like the Spring-configuration, does it not? 🙂

If you need to configure a different datasource for activiti, this is the file you need to adjust. By default, we look up a datasource using the name “java:ActivitiDS” and we configure externally managed transactions using the JtaProcessEngineConfiguration. The setup script also deploys a datasource using a h2 database to get you started. It is recommended to use a different database for production, of course.

Next, we will briefly look at how we can develop an application. Lets assume we have an application (ear) with an EJB module (jar) and a process archive (bar). Lets also assume the project is maven-based. First, we reference the activti-client project in the pom file, which generates the application.xml for the ear. We can do it like this:


In addition, we include the camunda fox repository:

    <id>Camunda Fox Repository</id>

Now we can inject the activiti-services in our ejb module:

public class StartProcessEjb implements StartProcessLocal, StartProcessRemote{    

	@EJB RuntimeService runtimeService;    

	public void startProcess() {     



The injected org.activiti.engine.RuntimeService is a proxy, executing commands on the EJB-command executor of the central process engine (see figure 2, above).

Already read?

Scientific performance benchmark of open source BPMN engines

Why BPMN is not enough

Decision Model and Notation (DMN) – the new Business Rules Standard. An introduction by example.

New Whitepaper: The Zero-Code BPM Myth

6 Responses

Leave a reply