This document will guide you through the installation of camunda BPM and its components on an IBM WebSphere Application Server.
Enterprise FeaturePlease note that this feature is only included in the enterprise edition of the camunda BPM platform, it is not available in the community edition.
Reading the Guide
$WAS_HOMEpoints to the WebSphere application server main directory (typically something like
$PLATFORM_VERSIONdenotes the version of the camunda BPM platform you want to install or already have installed, e.g.
$WAS_DISTRIBUTIONrepresents the downloaded camunda BPM distribution for the WAS, e.g.
The distribution is available at the camunda enterprise release page. You will be asked to enter the credentials you received during the trial or subscription process.
The camunda BPM platform requires a set of resources that need to be configured at the application server level:
In order to perform the steps listed in this guide, make sure you understand the concept of management scopes introduced by the IBM WebSphere Application Server. We assume that resources are defined at the "Node" scope.
The camunda BPM engine uses one or multiple process engines. Use your application server management tooling for the configuration of the datasources. The JNDI name of the datasource must be equal to the name used in the datasource-Element of the process engine(s) configured in the bpm-platform.xml file.
The default JNDI name used by the process engine is
The following screenshot shows the configuration of an XA datasource:
Note that you may configure multiple datasources used by different process engine instances. See the User Guide for details.
This section explains how you can use the WebSphere Integrated Solutions Console to configure a work manager to be used by the camunda BPM platform jobexecutor. It is recommended to check the manual of the application server for additional details.
Go to Resources / Asynchronous Bean / Work Managers and select the appropriate scope, for example:
Create a new work manager in the scope using the Button New....
Configure the new Work Manager. The following is a selection of sensible default values:
|Name||camunda-platform-jobexecutor-WM||The name of the Work Manager.|
Default JNDI name for WorkManager.
This setting value is mandatory and must not be changed.
|Description||"The work manager used by the camunda platform job executor"||Describes the work manager. Any value can be used.|
|Work Request Queue Size||5||Specifies the size of the work request queue. The work request queue is a buffer that holds scheduled work objects and may be a value of 1 or greater. The thread pool pulls work from this queue. If you do not specify a value or the value is 0, the queue size is managed automatically. Large values can consume significant system resources.|
|Work request queue full action||Fail||Specifies the action that is taken when the thread pool is exhausted, and the work request queue is full. This action starts when you submit non-daemon work to the work manager. The default value is block but should be changed to "Fail".|
|Number of alarm threads||2||Specifies the desired maximum number of threads that are used for alarms. The default value is 2.|
|Minimum number of threads||2||Specifies the minimum number of threads that are available in this work manager. Should not be below "2" since one thread is blocked by the job acquisition. If you configure multiple job acquisitions, the Minimal Size should not be below Nr. of Acquisitions + 1.|
|Maximum number of threads||4||Specifies the maximum number of threads that are available in this work manager used by the jobexecutor. Should be greater than "Minimum Size".|
|Thread Priority||5||Specifies the priority of the threads that are available in this work manager.|
|Growable||False||Specifies whether the number of threads in this work manager can be increased automatically when the maximum number of threads is reached.The default value is true, but should be changed to "False"|
The following screenshot shows an example configuration of the work manager and its thread pool properties.
The camunda BPM platform distribution for IBM WebSphere Application Server includes one module in the modules folder:
camunda-ee-ibm-was-$PLATFORM_VERSION.zip |-- modules/ |-- camunda-ibm-websphere-ear-$PLATFORM_VERSION.ear
The camunda-ibm-websphere-ear is a Java EE application enterprise archive (EAR) providing the camunda BPM platform services. It contains an embedded rar module. This camunda-ibm-websphere-rar module is a JCA Resource Adapter providing the jobexecutor service to the camunda BPM platform.
The EAR must be installed to your IBM WebSphere Application Server.
In this section, we explain how the camunda-ibm-websphere-ear module can be installed using the WebShere Integrated Solutions Console.
camunda-ibm-websphere-ear-$PLATFORM_VERSION.earfile from the modules folder of the camunda BPM platform for IBM WebSphere Application Server distribution. Click Next.
After installing an Process Application (PA) in your IBM WebSphere Application Server, which does not include the camunda BPM dependencies, you must assign the previously created "Camunda" shared library with the Process Application deployment. This should only be necessary when you use the "shared" engine deployment approach and not the "embedded" process engine one (aka self-contained Process Application).
When installing the camunda BPM platform Application, you may see error messages indicating that you are referencing resources from the wrong scope. Make sure you define the resources in the right scope so all components are visible to each other. Make sure you understand the IBM WebSphere management concepts "Cell", "Node" and "Server".
The camunda REST API WAR file resides under
webapps/camunda-engine-rest-$PLATFORM_VERSION-was.war in the WAS distribution archive.
In this section we explain how to install the WAR file using the WebSphere enterprise application Wizard provided within the WebSphere Integrated Solutions Console:
camunda-engine-rest-VERSION-was.warfile from the distribution and upload it.
After completing the wizard, REST API should be successfully installed on the application server. Don't forget to save your changes to the master configuration. In some situations, you also have to start the web application manually from the Applications / Application Types / WebSphere enterprise applications page.
The web application archive that contains camunda Cockpit and Tasklist resides under
webapps/camunda-was-$PLATFORM_VERSION.war in the WAS distribution archive.
In this section we explain how to install the WAR file using the Websphere enterprise application Wizard provided by the Websphere Integrated Solutions Console:
camunda-was-VERSION.warfile from the distribution and upload it.
After completing the wizard, the applications should be successfully installed on the application server. Don't forget to save your changes to the master configuration. In some situations, you also have to start the web application manually from the Applications / Application Types / WebSphere enterprise applications page.
You can check if everything went well by accessing Cockpit and Tasklist via
/camunda/app/tasklist or under the context path you configured.
In order to setup LDAP for the WebSphere distribution, you have to perform the following steps:
1. Add LDAP Library
Make sure the
camunda-identity-ldap-$PLATFORM_VERSION.jar is present in the
2. Adjust Process Engine Configuration
Edit the file
bpm-platform.xml located inside the folder
camunda-ibm-websphere-ear-$VERSION/camunda-ibm-websphere-service-$VERSION/META-INF/ and add the LDAP Identity Provider Plugin and the Administrator Authorization Plugin.
<?xml version="1.0" encoding="UTF-8"?> <bpm-platform xmlns="http://www.camunda.org/schema/1.0/BpmPlatform" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.camunda.org/schema/1.0/BpmPlatform http://www.camunda.org/schema/1.0/BpmPlatform "> ... <process-engine name="default"> ... <properties>...</properties> <plugins> <plugin> <class>org.camunda.bpm.identity.impl.ldap.plugin.LdapIdentityProviderPlugin</class> <properties> <property name="serverUrl">ldap://localhost:4334/</property> <property name="managerDn">uid=jonny,ou=office-berlin,o=camunda,c=org</property> <property name="managerPassword">s3cr3t</property> <property name="baseDn">o=camunda,c=org</property> <property name="userSearchBase"></property> <property name="userSearchFilter">(objectclass=person)</property> <property name="userIdAttribute">uid</property> <property name="userFirstnameAttribute">cn</property> <property name="userLastnameAttribute">sn</property> <property name="userEmailAttribute">mail</property> <property name="userPasswordAttribute">userpassword</property> <property name="groupSearchBase"></property> <property name="groupSearchFilter">(objectclass=groupOfNames)</property> <property name="groupIdAttribute">ou</property> <property name="groupNameAttribute">cn</property> <property name="groupMemberAttribute">member</property> </properties> </plugin> <plugin> <class>org.camunda.bpm.engine.impl.plugin.AdministratorAuthorizationPlugin</class> <properties> <property name="administratorUserName">admin</property> </properties> </plugin> </plugins> </process-engine> </bpm-platform>
administratorUserName property should contain the user id of the LDAP user you want to grant administrator authorizations to. You can then use this user to log into the webapplication and grant authorizations to additional users.