camunda BPM Installation Guide (IBM WebSphere)

This document will guide you through the installation of camunda BPM and its components on a IBM WebSphere Application Server.

The camunda platform requires a set of resources that need to be configured at the application server level: one or multiple datasources to be used by the engine and a work manager for the job executor.

In order to perform the steps listed in this guide, make sure you understand the concept of management scopes introduced by the 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 configuring 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.

Default JNDI Name

The default JNDI name is jdbc/ProcessEngine

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 WebShere Integrated Solutions Console for configuring 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.

Select the appropriate server under Resources / Asynchronous Beans / Work Managers and open the configuration page. Example: server1 Create a new work manager using the Button New.... Configure the new Work Manager. The following is a selection of sensible default values:

General Properties

Thread Pool Properties

The following screenshot shows an example configuration of the work manager and its thread pool properties.

The shared libraries include the camunda engine and some utility JARs. The shared libraries must be visible to both the camunda BPM platform as well es all process applications.

The shared libraries can be found in the lib folder of the distribution:

camunda-ee-ibm-was-$PLATFORM_VERSION.zip
|-- modules/
      |-- lib/  <-- The shared libs
           |-- camunda-engine-$PLATFORM_VERSION.jar
           |-- java-uuid-generator-XX.jar
           |-- mybatis-XX.jar
           |-- joda-time-XX.jar
      |-- camunda-ibm-websphere-ear-$PLATFORM_VERSION.ear
      |-- camunda-ibm-websphere-rar-$PLATFORM_VERSION.rar

The shared libraries must be copied to the $WAS_HOME/lib/ext folder of the IBM WebSphere Server installation. Restart the WebSphere Server after this operation.

The camunda platform includes two modules in the modules folder of the distribution:

camunda-ee-ibm-was-$PLATFORM_VERSION.zip
|-- modules/
      |-- camunda-ibm-websphere-ear-$PLATFORM_VERSION.ear
      |-- camunda-ibm-websphere-rar-$PLATFORM_VERSION.rar

The camunda-ibm-websphere-rar module is a JCA Resource Adapter providing the jobexecutor service to the camunda BPM platform. The camunda-ibm-websphere-ear is a Java EE application providing the camunda BPM platform services.

Both modules must be installed to your IBM WebSphere Application Server in the correct order. You must first install the camunda-ibm-websphere-rar module and then install the camunda-ibm-websphere-ear module.

In this section, we explain how the camunda-ibm-websphere-rar module can be installed using the WebShere Integrated Solutions Console.

The installation process is composed of three steps:

1. Install and configure the camunda-ibm-websphere-rar-$PLATFORM_VERSION.rar RAR file.
2. Define a Managed Connection Facotry for accessing the jobexecutor.
3. Define an Activation Policy for JobHandler MDBs.

Installing and configuring the RAR file

First, the camunda-ibm-websphere-rar-$PLATFORM_VERSION.rar RAR file must be installed:

1. Navigate to the Resource Adapters page located under Resources / Resource Adapters / Resource Adapters.
2. Select as Scope "Node".
3. Select the Install RAR button.
4. Select the camunda-ibm-websphere-rar-$PLATFORM_VERSION.rar from the modules folder of the camunda BPM platform for IBM WebShpere Application Server distribution. Click Next to go to the Properties page.
5. Fill in the properties form. As a name for the resource adapter, we propose camunda-ibm-websphere-rar.
6. Click on the new entry camunda-ibm-websphere-rar, if you choose the same name in the previous step.

Defining a Managed Connection Factory

1. Select "J2C Connection Factories".
2. Select "New"
3. Fill in the "General Properties" Form.
   • As the Name property, we propose "camunda BPM platform jobexecutor CF".
   • As a JNDI Name we propose "eis/JcaExecutorServiceConnectionFactory"
   • No authentication is necessary.

Defining an Activation Specification

1. Select "J2C activation specifications".
2. Select "New"
3. Fill in the "General Properties" Form.
   • As the Name property, we propose "camunda BPM platform jobexecutor SPEC".
   • As a JNDI Name we propose "eis/PlatformJobExecutorActivation"

Save your settings. This completes the installation of the resource adapter.

There are several custom properties available for the resource adapter regarding the work manager. You can reach them by following the Custom Properties link on the configuration page of the resource adapter:

In this section, we explain how the camunda-ibm-websphere-ear module can be installed using the WebShere Integrated Solutions Console.

1. Navigate to the Enterprise Applications page using the navigation path Applications / Application Types / WebSphere enterprise applications.
2. Click the "Install" Button.
3. Select the camunda-ibm-websphere-ear-$PLATFORM_VERSION.ear file from the modules folder of the camunda BPM platform for IBM WebShpere Application Server distribution. Click Next.
4. Select the "Detailed" Path.

5. In Step 1 Under application-name, type "camunda-bpm-platform". This setting is mandatory.

   Manadatory Application Name

   The camunda BPM platform application MUST be installed with the application name "camunda-bpm-platform".
6. Perform Steps 2-4 according to your requirements.

7. In Step 5,

   • Under "Listener Bindings" select the radio button "Activation Specification".
   • Under "Target Resource JNDI Name", provide the configured activation name for the jobexecutor (see Section "Defining an Activation Specification" above). The default is "eis/PlatformJobExecutorActivation".
   • Destination and authentication must be left blank.

   

8. In Step 6-8,
   • Do not override the default JNDI Names

9. In Step 9,

   • Set the Target Resource JNDI Name to the name of the managed connection factory provided for the jobexecutor (see Section "Defining a Managed Connection Factory" above). The default setting is "eis/JcaExecutorServiceConnectionFactory".

   

10. In Steps 10-12, go with the default settings.

11. Click "Finish".
12. Save the configuration.
13. Start the camunda-bpm-platform application. If this fails initially, try to restart the server. The resource adapter references are not always resolved properly. It will be fine after a restart.

Defining WebShere Resources in the right scope

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 jobexecutor resources in the right scope. Make sure you understand the IBM WebSphere management concepts "Cell", "Node" and "Server".

Known Issue - Exception when creating an initial user profile

At cycle login you may get an error when trying to setup an initial user profile. The Exception contains the following error message: java.lang.VerifyError in class org/springframework/aop/aspectj/MethodInvocationProceedingJoinPoint. This is a known bug in WebSphere v. 8.5.5. Download the fix package 8.5.5.0-WS-WASProd-IFPM90932 from the IBM support center and install it via the IBM Installation Manager.

The camunda REST API WAR file resides under webapps/camunda-engine-rest-$PLATFORM_VERSION-was.war in the WAS distribution archive.

In the following we explain how to install the WAR file using the Websphere enterprise application Wizard provided inside the Websphere Integrated Solutions Console:

1. Open the Websphere Integrated Solutions Console.
2. Navigate to the Applications / Application Types / WebSphere enterprise applications Page.
3. Click the Install Button
4. The first page of the Wizard opens. Using the File Browser, select the camunda-engine-rest-VERSION-was.war file from the distribution and upload it.
5. Continue to the next page.
6. Select the "Fast Path" on the next page.
7. Step 1. Usually, no changes are required.
8. Step 2. Usually, no changes are required.
9. Step 3. Usually, no changes are required.
10. Step 4. Define a context root for the REST API. We propose to use /engine-rest
11. Step 5. Usually, no changes are required.

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.

Note: We do not recommend to install camunda Cycle together with the other platform components (webapps, engine, REST Api) on the same runtime environment. Such a combined installation is not supported.

Create the database schema for camunda Cycle

The next step consists in creating a database schema for camunda Cycle. The camunda platform distribution ships with a set of SQL create scripts that can be executed by a database administrator. The SQL create scripts reside in the camunda platform distribution in the sql/create folder, like sql/create/*_cycle_VERSION.sql.

There is an individual SQL script for each supported database. Select the script appropriate for your database and run it with your database administration tool. (e.g. SqlDeveloper for Oracle).

We recommend to create a separate database or database schema for camunda Cycle.

Create a datasource

Now you must define a datasource in IBM Websphere Application Server. We assume here that you are familiar with the procedure. If in doubt, check the appropriate sections in the manual of your application server.

The datasource should be named jdbc/CycleDS. In order to use a custom datasource name, you have to edit the file named Cycle-persistence.xml residing at

Cycle-was-VERSION.war/WEB-INF/classes/META-INF/cycle-persistence.xml

Installation

The camunda Cycle WAR file resides under webapps/cycle-was-$PLATFORM_VERSION.war in the WAS distribution archive.

In the following we explain how to install the WAR file using the Websphere enterprise application Wizard provided inside the Websphere Integrated Solutions Console:

1. Open the Websphere Integrated Solutions Console.
2. Navigate to the Applications / Application Types / WebSphere enterprise applications Page.
3. Click the Install Button
4. The first page of the Wizard opens. Using the File Browser, select the cycle-was-VERSION.war file from the distribution and upload it.
5. Continue to the next page.
6. Select the "Fast Path" on the next page.
7. Step 1. Usually, no changes are required.
8. Step 2. Usually, no changes are required.
9. Step 3. Usually, no changes are required.
10. Step 4. Define a context root for Cycle. We propose to use /cycle
11. Step 5. Usually, no changes are required.

After completing the wizard, Cycle 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.

Using SaaS Signavio / camunda webmodeler over HTTPS

The web application archive that contains camunda Cockpit and Tasklist resides under webapps/camunda-was-$PLATFORM_VERSION.war in the WAS distribution archive.

In the following we explain how to install the WAR file using the Websphere enterprise application Wizard provided by the Websphere Integrated Solutions Console:

1. Open the Websphere Integrated Solutions Console.
2. Navigate to the Applications / Application Types / WebSphere enterprise applications Page.
3. Click the Install Button
4. The first page of the Wizard opens. Using the File Browser, select the camunda-was-VERSION.war file from the distribution and upload it.
5. Continue to the next page.
6. Select the "Fast Path" on the next page.
7. Step 1. Usually, no changes are required.
8. Step 2. Usually, no changes are required.
9. Step 3. Usually, no changes are required.
10. Step 4. Define a context root for the applications. We propose to use /camunda
11. Step 5. Usually, no changes are required.

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 whether everything went well by accessing Cockpit and Tasklist via /camunda/app/cockpit and /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 $WAS_HOME/lib/ext folder.

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>

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

See userguide for complete documentation on the LDAP Identity Provider Plugin and the Administrator Authorization Plugin.