« Modeler Help updated... | Main | BPM and JSF »

BPM solutions using Java EE

The Imixs Workflow project is an open source project that relieved the construction of business process management systems (BPMS). An essential part of the project are the Imixs JEE Workflow components. These components can be used to build BPM solutions based on the Java EE plattform.

The following tutorial will show how an Imixs BPM solution can be created in a few minutes with the help of Eclipse, Maven and Glassfish Application Server.


For the execution of the tutorial, an application server, a database, and the Eclipse IDE is required. The application server platform used here is Glassfish Server V 3, on which the application can be deployed and executed. The data is stored in a database. Java EE has no special requirements to a database, so any database system can be used. In the open source environment, the choice is usually to MySQL.

For the runtime of the BPM solution the application server provides two main functions. First, he stores the process data in the database on a so-called Database pool. Second it provides a security realm. The security realm ensures that users can authenticate against the application and unauthorized access is prevented.

The Imixs workflow solution provides extensive capabilities available to protect data against unauthorized access. This feature is defined through the process model. To access the system at least one user is required as a member of the group "IMIXS-WORKFLOW-Manager"! Members of this group are also entitled to synchronize process models. The configuration of the database pool and the security realm is straight forward. A complete installation guide for Glassfish and JBoss can be found on the Imixs project site - Installation.

Configuration of Eclipse and Maven

To work with the Eclipse IDE the Imixs Modeler Plugin  to manage the process model, and the Maven Plugin from Sonatype for the build process of the JEE project is needed. Both plugins can be easily installed within Eclipse via the menu command "Help>> install new software" from the following URLs:

  • http://www.imixs.org/org.imixs.eclipse.updatesite
  • http://m2eclipse.sonatype.org/sites/m2e
The web interface of the BPM solution should be implemented using RichFaces. RichFaces is a component library for Java Server Faces (JSF) to create Ajax based Web applications. To use RichFaces the JBoss Maven repository must be included into the Maven repository configuration. The easiest way to make the repository visible for Maven is to create a profile in "maven_installation_folder/conf/settings.xml". The settings.xml file is found on Windows systems in c:\Users\USERNAME\.m2. This is the content of the profile:


<?xml version="1.0" encoding="UTF-8"?>
<settings 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/xsd/settings-1.0.0.xsd">
                <!-- JBoss RichFaces Repository -->
                    <name>Jboss Repository for

Here we go!

After the Eclipse IDE and the server infrastructure is configured the construction of the BPM solution can be started. Since the Imixs workflow project is completely based on Maven, creating a new application is very simple. Through the selection of a so-called Maven Archetype, a template can be used, which contains all necessary components of an Imixs BPM solution.

A new Maven project can be generated in Eclipse via the following menu:

"File >> new Project...."


The project type "Maven >> Maven Project" leads to the Maven Project Wizard. This wizard allows the creation of a new project based on a Maven template. On the second wizard page "Select an Archetype" all known templates are displayed:

Since the Imixs JEE template has not been used so far, it must be added once to the list with the command button "Add Archetype" and the following properties:

  • Archetype Group Id: org.imixs.application
  • Archetype Artivact Id: imixs-workflow-jee-archetype
  • Archetype Version: 0.0.4


Maven will download the template immediately so it can be selected next. On the last wizard page various parameters for the new project can be provided:


The Group Id and Artifact Id can be chosen.

The archetype properties should be set to the server information about the database pool and security realm previously made. Three parameters can be configured for the Imixs BPM project:

  • jta-data-source: This value defines the database pool used by the server to store the process data into a database
  • realm: the security realm to be used for authentication
  • context-root: The context-root provides the web address under which the application can be called. (E.g.: http://localhost:8080/workflow)

Press "Finish" to generate the project sources. Maven will automatically ensure that all required libraries are available and download them from the Internet. This is much easier to work as no Java libraries must be manually download and installed by the developer. Thus the RichFaces components are automatically included in the project.

Next you will see 4 projects in the Eclipse Package Explorer. The first project (in this case my-bpm-app) can be used to build the hole project with all modules. The sub projects -ear,-ejb, and -web containing the corresponding Java EE module. 

Build.... deploy.... and run the application

In order to build the final application, it is sufficient to run the command "Run as >> Maven Install" from the context menu of the main project (my-app-bpm). Maven automatically starts the entire build process and creates an executable enterprise archive (EAR) that can be deployed into the Glassfish server.

In the Eclipse console view the build status can be seen. The build is successful when the line "BUILD SUCCESS" will appear:

[INFO] Unnamed - com.foo:my-bpm-app-ejb:ejb:0.0.1-SNAPSHOT  SUCCESS [2.756s]
[INFO] Unnamed - com.foo:my-bpm-app-web:war:0.0.1-SNAPSHOT  SUCCESS [3.899s]
[INFO] Unnamed - com.foo:my-bpm-app-ear:ear:0.0.1-SNAPSHOT  SUCCESS [3.658s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 11.135s
[INFO] Finished at: Sat Jul 17 17:00:55 CEST 2010
[INFO] Final Memory: 3M/15M
[INFO] ------------------------------------------------------------------------

Now the application can be installed on the application server. The final EAR module is located in the Maven directory at:


To deploy the EAR file into the Glassfish server open the Glassfish Web console


and select the following menu:

Applications >> Deploy


Next chose the the EAR file from the /.m2 directory and press the command button "OK". During the deployment the Java EE Framework will automatically create the necessary tables structures in the specified database. A manual generation of a specific schema is not necessary.

Create a process model

Before the application can be started via the web browser, a process model has to be provided first. The BPM application in Eclipse already has a sample workflow model. This model is located under the main project at:


The file ticket.ixm can be opened and edited with the Imixs Modeler. In the tab "Synchronize" the model data can be synchronized via a REST service to the server. The URL for the Web Services is:


If the Context Root was changed the REST service URL is like:


Where ROOT_CONTEXT is the name of your web application root context.
Clicking the link "synchronize model" the model can be transferred into the workflow application. This requires an authentication with the previously created user account which is a member of the access group "Imixs-WORKFLOW-Manager".


Finally, the workflow application can now be started via the web browser:



Through the pull down menu  "My Tasks >> start new process >> Ticket" a first process can be started.

Of course, the model can be modified and extended using the Imixs Modeler Tool in Eclipse. For thus changes the application does not have to be restarted or redeployed.

Improve the web application

Now the created workflow application can be improved to your own requirements. If you take a closer look into the project you will find that the project consists of only a few Java classes. Most of the functionality comes directly from the Imixs JEE components. To customize the application, it is usually sufficient to change the JSF (.xhtml) pages in the Web module, and the Java class "WorkflowMB". So you need not be a JEE expert.

To learn more about the used JSF classes you will find examples and source code at the Imixs JSF Tool project page.

If you have any questions, post your comments here.