cogIntegrates Activiti BPM Engine in XWiki
Developed by

Sorin Burjan

Active Installs0
0 Votes
LicenseGNU Lesser General Public License 2.1

Tested with XWiki Enterprise 5.0+

Installable with the Extension Manager


General Architecture

This section describes the architecture of the application from a technical point of view. It is meant to aid developers to better understand the architecture.

The application consists of 6 Maven modules:

  • application-activiti-api
  • application-activiti-bridge
  • application-activiti-listener
  • application-activiti-test
  • application-activiti-ui


This is the CORE module which contains the Java API and the ScriptService API. It is responsable for:

  • Starting the Activiti Engine
  • Maps XWiki users into Activiti users. It has a custom Identity Service which replaces Activiti's default one.
  • Inject the XWiki Script Services into the Activiti Engine so Activiti can call XWiki's services from its engine
  • Expose Java API and Script Service API which can be called from Velocity or other XWiki Components which want to interact with Activiti


It is a component which has the role to create a bridge between Activiti and XWiki's Old Core/ legacy code. This has been created as a best practice. For more information please visit Writing XWiki Components page.


It is a Component used for listening events which happen in XWiki, mostly DocumentCreated, DocumentUpdated events. It offers a way to send signals toprocesses deployed  into Activiti Engine which are listening for external events.


Tests for the application


The front-end of the application. It contains:

a dedicated section in the Administration for managing and seing the global status of the deployed processes and their running instances

User Guide

Admin Guide

As seen in the installation guide, administration of the application is integrated within XWiki's Administration interface, and consists of 3 sections:

Activiti Repository

This section is responsible for displaying the deployed process definitions and various informations about them, like process definition version, process definition key, process definition ID, process definition description.

Also, deploying a new process definition can be achieved by uploading a BPMN 2.0 file from this page.


Activiti Runtime

This section is responsible for displaying informations about the running process instances. It also displays information about the Active tasks, current assignee, but also about the history of the completed processes or tasks.


Activiti Event Mapping

This section is responsible for managing the listeners mapped to Activiti. This is used to send signals to the Activiti Engine, thus to the listening processes, when a certain action happens within XWiki. It listens on 3 diferend XWiki events: Document Created, Document Deleted and Document Updated.


Regular User Guide

Normal users can access their interface of the Activiti application from the Applications panel. There, they will see all their assigned tasks or start processes.

Creating a process

Modelling the Activiti process

Using the Eclipse plugin assumes a medium knowledge and understanding of the Activiti framework and architecture.

In order to create the model of the process, you must install the Activiti BPMN Eclipse Plugin. The installation guide and the user manual can be found on the Activiti homepage.

Besides the supported form types supported by Activiti, the current implementation adds 3 more:

  • textArea (Custom implementation for displaying textareas which has String as backend)
  • XWikiDocumentReference used for generating URL's from a XWiki EntityReference for an XWiki Document
  • XWikiUsernameReference used for generating URL's from a XWiki EntityReference for an XWiki username

The forms for the Task Nodes are rendered by the page UserTaskFormGenerator. Depending of each type defined in the Eclipse Designer, the page will render the according form element. This is highly customizable. The vanilla version is created to be as generic as possible.

Sample process definitions

There is a set of small process definition that offer a easy first hands-on experience of the application.

In order to use them, you simply have to upload the *.bpmn file into the application from the Administration Repository section. No build is necessary. If you want to play with the process definitions, you can open them using the Eclipse plugin.

Building from sources

To build from sources locally, you need to have the XWiki repositories added in your settings.xml file. To achieve this, please follow the instructions found on Building XWiki from sources.
Besides that, you also need to add the Activiti's repository to the settings.xml file:

 <id>Alfresco Maven Repository</id>

Known limitations or issues

  • The current implementation uses H2 as a database to store Activiti's database
  • The current implementation does not support multiwiki environments. Meaning, all the deployed processes are shared across the whole XWiki farm. Install the XWiki activiti xar file in the main wiki AND in the local wiki where you want to use it. It has never been fully tested on a XEM Environment.
  • No internationalization

Prerequisites & Installation Instructions

Manual Installation

  • First, download the sources and build locally, or download directly the artefacts from the Maven repository, or get the artefacts from this attachment
  • Copy the project jars to the lib directory of the XWiki webapp
    • xwiki-activiti-api-*.jar
    • xwiki-activiti-bridge-*.jar
    • xwiki-activiti-listener-*.jar
  • Since the project jars depend on Activiti, you have to copy Activiti jar and its dependencies in the same directory:
    • activiti-engine-*.jar
    • activiti-bpmn-model-*.jar
    • activiti-bpmn-converter-*.jar
    • com.h2database:h2-*.jar (currently the integration uses H2 database for storing Activiti Engine Database)
    • org.mybatis:mybatis-*.jar (need by Activiti to be able to use the H2 database)
    • org.springframework.spring-core:spring-core-*.jar
    • org.springframework.spring-beans:spring-beans-*.jar
    • org.springframework.spring-asm:spring-asm-*.jar
  • You can start the XWiki server and now, login with an user which has administration privileges and import the xwiki-activiti-ui.xar (downloaded from the Download button on this page or build from the sources) from the Administration section.
  • Now you should see 3 entries in the Administration Application
    • Activiti Event Mapping
    • Activiti Repository
    • Activiti Runtime
If the Java part installation is OK, you should see a similar message in the console
2013-11-13 01:53:07,380 [http://localhost:8080/xwiki/bin/admin/XWiki/XWikiPreferences?editor=globaladmin&section=Activiti+Repository] INFO  o.x.a.i.DefaultActivitiEngine  - Initializing Activiti Engine
2013-11-13 01:53:24,196 [http://localhost:8080/xwiki/bin/admin/XWiki/XWikiPreferences?editor=globaladmin&section=Activiti+Repository] INFO  o.x.a.i.DefaultActivitiEngine  - Injecting into Activiti the following XWiki ScriptServices: [cdoc, response, services, xcontext, syntaxFactory, tdoc, request, doc, xwiki, msg, util]
  • This means that everything is OK, the Activiti Engine has been initialized and you're ready to deploy a process definition.

Automatic installation with Extension Manager

Due to a limitation of Extension Manager, the application cannot be installed easily. The technical reason for which this is not possible is that Extension Manager does not support exclusions of artifacts.The activiti-engine dependency transitively brings commons-logging, which is not allowed in XWiki.

Release Notes


First Release. Please  check documentation for more informations.


Dependencies for this extension (org.xwiki.contrib:application-activiti-ui 1.0):

  • org.xwiki.contrib:application-activiti-api 1.0
  • org.xwiki.contrib:application-activiti-bridge 1.0
  • org.xwiki.contrib:application-activiti-listener 1.0
Tags: workflow

Get Connected