Camunda BPM Installation Guide (Oracle WebLogic)

This document will guide you through the installation of Camunda BPM and its components on an Oracle WebLogic Application Server.

The camunda BPM 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.
• A work manager for the job executor.

The camunda BPM platform uses one or multiple process engines. Use the Oracle WebLogic Server Administration Console 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.

Default JNDI Name

The default JNDI name is jdbc/ProcessEngine

The following screenshot shows the mandatory configuration of a datasource for camunda bpm:

In this section we explain how to add a datasource using the Oracle WebLogic Server Administration Console:

1. Open the Oracle WebLogic Server Administration Console.
2. Navigate to the "Domain Structure / YOUR_DOMAIN / Services / Data Sources" page.
3. Click the "New" Button and select "Generic Data Source".
4. On the next page, enter a name for the datasource.
5. Enter the required JNDI Name "jdbc/ProcessEngine", which is mandatory for the camunda BPM platform.
6. Continue to the next pages and fill in your database credentials.
7. When you finished the creation of the datasource, click the "Finish" Button to complete the installation.
8. Check the box in front of your datasource and test if it works.

Note that you can configure multiple datasources used by different process engine instances. See the User Guide for details.

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 as all process applications.

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

camunda-ee-oracle-wls-$PLATFORM_VERSION.zip
|-- modules/
      |-- lib/  <-- The shared libs
           |-- camunda-engine-$PLATFORM_VERSION.jar
           |-- java-uuid-generator-XX.jar
           |-- mybatis-XX.jar
           |-- ...
      |-- camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear

The shared libraries must be copied to the $WLS_DOMAIN_HOME/lib folder of your Oracle WebLogic Server installation. Do "NOT" copy it to your $WL_HOME/lib folder. Restart the Oracle WebLogic Server after this operation.

The Camunda BPM platform includes one module in the modules folder of the distribution:

camunda-ee-oracle-wls-$PLATFORM_VERSION.zip
|-- modules/
      |-- camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear

The camunda-oracle-weblogic-ear is a Java EE application providing the Camunda BPM platform services. It contains an embedded JCA Resource Adapter, the camunda-oracle-weblogic-rar, which provides the jobexecutor service to the camunda BPM platform. It must be installed to your Oracle Weblogic Application Server.

In this section, we explain how the camunda-oracle-weblogic-ear module can be installed using the Oracle WebLogic Server Administration Console.

The installation process is composed of two steps:

1. Install the camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear EAR file.
2. Configure the deployment order of camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear EAR file.

Installing the EAR file

First the camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear RAR file must be installed:

1. Open the Oracle WebLogic Server Administration Console.
2. Navigate to the "Domain structure / YOUR_DOMAIN / Deployments" page.
3. Select the "Install" button.
4. Using the File Browser, select the camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear from the modules folder of the camunda BPM platform for Oracle WebLogic Application Server distribution and continue to the "Next" page.
5. Select "Install this deployment as an application" and continue to the "Next" page.

6. Fill in camunda-bpm-platform as name for the enterprise application deployment. This setting is mandatory and MUST NOT be changed.

   

7. Continue to the "Next" page.

8. Select "Yes, take me to the deployment's configuration screen" and click the "Finish" button to complete the installation.
9. (optional) Configure location of the bpm-platform.xml file

Configure the deployment order

1. In the deployment's configuration screen, change the value of the "Deployment Order" from "100" to "90", so the Enterprise Application starts before process application deployments.
2. Click "Save" to persist the change.

Example: Deployment order set to "90".

Configure the JCA Work Manager

1. In the EAR's deployment configuration screen under modules, select the camunda-oracle-weblogic-rar.rar entry. Click on the "Configuration" tab on the following page.
2. Now select the "Workload" tab.
3. Here, you see a preconfigured JCA Work Manager named "wm/camunda-bpm-workmanager". Click on it.
4. For "Minimum Threads Constraint", select the preconfigured "camunda-bpm-workmanager-min-threads" option. Per default, we configure 2 threads as a minimum. At least 2 threads are required, but you can increase them when you think you do a lot of asynchronous work.
5. For "Maximum Threads Constraint", select the preconfigured "camunda-bpm-workmanager-max-threads" option. Per default, we configure 5 threads, but you can increase them when you think you do a lot of asynchronous work.
6. For "Stuck Thread Action", select "Ignore stuck threads", because we have a long running daemon thread which acquires the jobs to execute. This forces Oracle WebLogic to skip the Stuck Thread Warning which would otherwise appear in the server log every ten minutes.
7. For "Capacity Constraint", select the preconfigured "camunda-bpm-workmanager-capacity" option. Per default, we configure a queue size of 10 for the workmanager, but you can always tune it accordingly to your needs.
8. Click "Save" to persist your changes.

Now you can start the camunda-bpm-platform application if it is not already running. If this initially fails, try to restart the server.

Example: Finished configuration of the JCA Work Manager used by the resource adapter.

The Camunda REST API WAR file resides under webapps/camunda-engine-rest-$PLATFORM_VERSION-wls.war in the Oracle WebLogic Application Server distribution archive.

In this section we explain how to install the WAR file using the Oracle WebLogic Server Administration Console:

1. Open the Oracle WebLogic Server Administration Console.
2. Navigate to the Domain Structure / YOUR_DOMAIN / Deployments page.
3. Click the Install button. The first page of the wizard opens.
4. Using the File Browser, select the camunda-engine-rest-$PLATFORM_VERSION-wls.war file from the distribution and upload it.
5. Continue to the Next page.
6. Select Install this deployment as an application and continue to the Next page.
7. Adapt the optional settings to your needs and click the Finish button to complete the installation.

After completing the wizard, the REST API should be successfully installed on the application server. The context root for the REST API is /engine-rest by default. In some situations, you also have to start the web application manually from the Domain Structure / YOUR_DOMAIN / Deployments page.

The web application archive that contains camunda Cockpit and Tasklist resides under webapps/camunda-webapp-ee-wls-$PLATFORM_VERSION.war in the Oracle WebLogic Application Server distribution archive.

In this section we explain how to install the WAR file using the Oracle WebLogic Server Administration Console:

1. Open the Oracle WebLogic Server Administration Console.
2. Navigate to the Domain Structure / YOUR_DOMAIN / Deployments page.
3. Click the Install button. The first page of the Wizard opens.
4. Using the File Browser, select the camunda-webapp-ee-wls-$PLATFORM_VERSION.war file from the distribution and upload it.
5. Continue to the Next page.
6. Select Install this deployment as an application and continue to the Next page.
7. Click the Finish button to complete the installation.

After completing the wizard, the Cockpit and Tasklist should be accessible on the default context path /camunda. In some situations, you also have to start the web application manually from the Domain Structure / YOUR_DOMAIN / Deployments page.

You can check if everything went well by accessing Cockpit, Tasklist and Admin via /camunda/app/cockpit, /camunda/app/tasklist and /camunda/app/admin or under the context path you configured.

In order to setup LDAP for the Oracle WebLogic distribution, you have to perform the following steps:

Add the LDAP Library

Make sure the camunda-identity-ldap-$PLATFORM_VERSION.jar is present in the $WLS_DOMAIN_HOME/lib folder.

Adjust the Process Engine Configuration

Edit the file bpm-platform.xml located inside the Camunda BPM enterprise archive at camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear/camunda-oracle-weblogic-service.jar/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 web application and grant authorizations to additional users.

See our user guide for complete documentation on the LDAP Identity Provider Plugin and the Administrator Authorization Plugin.

Enable Hal Resource caching

If you use LDAP as Indentity Provider, you should consider activating caching of Users and Groups in the camunda webapplication. In order to activate this, add the following configuration to the web.xml file of camunda webapplication (camunda-webapp-wls-$PLATFORM_VERSION.war/WEB-INF/web.xml):

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

  <!-- ... -->

  <listener>
    <listener-class>org.camunda.bpm.engine.rest.hal.cache.HalRelationCacheBootstrap</listener-class>
  </listener>

  <context-param>
    <param-name>org.camunda.bpm.engine.rest.hal.cache.config</param-name>
    <param-value>
      {
        "cacheImplementation": "org.camunda.bpm.engine.rest.hal.cache.DefaultHalResourceCache",
        "caches": {
          "org.camunda.bpm.engine.rest.hal.user.HalUser": {
            "capacity": 100,
            "secondsToLive": 900
          },
          "org.camunda.bpm.engine.rest.hal.group.HalGroup": {
            "capacity": 100,
            "secondsToLive": 900
          }
        }
      }
    </param-value>
  </context-param>

  <!-- ... -->

</web-app>

The following steps describe how to upgrade the Camunda artifacts on an Oracle WebLogic application server in a shared process engine setting. For the entire migration procedure, refer to the migration guide. If not already done, make sure to download the Camunda BPM 7.2 Oracle WebLogic distribution.

The upgrade procedure takes the following steps:

1. Uninstall the Camunda libraries and archives
2. Add the new Camunda libraries
3. Install optional Camunda dependencies
4. Configure process engines
5. Install the Camunda archive
6. Install the Camunda BPM web applications

In each of the following steps, the identifiers $*_VERSION refer to the current version and the new versions of the artifacts.

1. Uninstall the Camunda Applications and Archives

First, uninstall the Camunda web applications, namely the Camunda REST API (artifact name like camunda-engine-rest) and the Camunda applications Cockpit, Tasklist and Admin (artifact name like camunda-webapp).

Uninstall the camunda EAR. Its name should be camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear. Then, uninstall the Camunda job executor adapter, called camunda-oracle-weblogic-$PLATFORM_VERSION.rar.

2. Replace the Camunda Libraries

After shutting down the server, replace the following libraries in $WLS_DOMAIN_HOME/lib with their equivalents from $WLS_DISTRIBUTION/modules/lib:

• camunda-engine-$PLATFORM_VERSION.jar
• camunda-bpmn-model-$PLATFORM_VERSION.jar
• camunda-xml-model-$PLATFORM_VERSION.jar
• mybatis-$MYBATIS_VERSION.jar

If present, also replace the following optional artifact:

• camunda-identity-ldap-$PLATFORM_VERSION.jar

Add the following library from $WLS_DISTRIBUTION/modules/lib to the folder $WLS_DOMAIN_HOME/lib:

• camunda-cmmn-model-$PLATFORM_VERSION.jar

3. Install Optional Camunda Dependencies

There are artifacts for Camunda Connect, Camunda Spin, the Freemarker template language and Groovy scripting that may optionally be added to the shared library folder. Since all these artifacts add new functionality, the following steps are not required for migration.

Note: The default Camunda configuration file contained by the Camunda EAR automatically activates the newly introduced, optional Camunda dependencies, Camunda Spin and Connect. If you do not use a custom BPM platform configuration as described here and do not intend to do so, you must install the Camunda Spin and Connect core libraries to the shared libraries folder.

Camunda Connect

If Camunda Connect is intended to be used, copy the following library from $WLS_DISTRIBUTION/modules/lib to the folder $WLS_DOMAIN_HOME/lib:

• camunda-connect-core-$CONNECT_VERSION.jar
• camunda-commons-logging-$COMMONS_VERSION.jar
• camunda-commons-utils-$COMMONS_VERSION.jar
• slf4j-api-$SLF4J_VERSION.jar
• slf4j-jdk14-$SLF4J_VERSION.jar

If you use a custom BPM platform configuration file, Camunda Connect functionality has to be activated for a process engine by registering a process engine plugin (note that if you use the default configuration, this step is not necessary):

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform ... ">
  <process-engine name="default">
    ...
    <plugins>
      ... existing plugins ...
      <plugin>
        <class>org.camunda.connect.plugin.impl.ConnectProcessEnginePlugin</class>
      </plugin>
    </plugins>
    ...
  </process-engine>

</bpm-platform>

Camunda Spin

If Camunda Spin is intended to be used, copy the following library from $WLS_DISTRIBUTION/modules/lib to the folder $WLS_DOMAIN_HOME/lib:

• camunda-spin-core-$CONNECT_VERSION.jar
• camunda-commons-logging-$COMMONS_VERSION.jar
• camunda-commons-utils-$COMMONS_VERSION.jar
• slf4j-api-$SLF4J_VERSION.jar
• slf4j-jdk14-$SLF4J_VERSION.jar

If you use a custom BPM platform configuration file, Camunda Spin functionality has to be activated for a process engine by registering a process engine plugin (note that if you use the default configuration, this step is not necessary):

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform ... ">
  <process-engine name="default">
    ...
    <plugins>
      ... existing plugins ...
      <plugin>
        <class>org.camunda.spin.plugin.impl.SpinProcessEnginePlugin</class>
      </plugin>
    </plugins>
    ...
  </process-engine>

</bpm-platform>

Groovy Scripting

If Groovy is to be used as a scripting language, add the following artifacts to the folder $WLS_DOMAIN_HOME/lib:

• groovy-all-$GROOVY_VERSION.jar

Freemarker Integration

If the Camunda integration for Freemarker is intended to be used, add the following artifacts to the folder $WLS_DOMAIN_HOME/lib:

• camunda-template-engines-freemarker-$TEMPLATE_VERSION.jar
• freemarker-2.3.20.jar
• camunda-commons-logging-$COMMONS_VERSION.jar
• camunda-commons-utils-$COMMONS_VERSION.jar
• slf4j-api-$SLF4J_VERSION.jar

4. Configure Process Engines

Script Variable Storing

As of 7.2, the default behavior of script variables has changed. Script variables are set in e.g. a BPMN Script Task that uses a language such as JavaScript or Groovy. In previous versions, the process engine automatically stored all script variables as process variables. Starting with 7.2, this behavior has changed and the process engine does not automatically store script variables any longer. You can re-enable the legacy behavior by setting the boolean property autoStoreScriptVariables to true for any process engine in the bpm-platform.xml:

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform ... ">
  ...
  <process-engine name="default">
    ...
    <properties>
      ... existing properties ...
      <property name="autoStoreScriptVariables">true</property>
    </properties>
    ...
  </process-engine>
  ...
</bpm-platform>

As an alternative, process application developers can migrate script code by replacing all implicit declarations of process variables in their scripts with an explicit call to execution.setVariable('varName', 'value').

5. Install the Camunda Archive

Install the Camunda EAR, i.e., the file $WLS_DISTRIBUTION/modules/camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear.

As of version 7.2, the Camunda job executor resource adapter (RAR) that you uninstalled in step 1 is part of the Camunda EAR and therefore does not need to be installed separately.

6. Install the Camunda Web Applications

Camunda REST API

Deploy the web application $WLS_DISTRIBUTION/webapps/camunda-engine-rest-$PLATFORM_VERSION-wls.war to your Oracle WebLogic instance.

Camunda Cockpit, Tasklist, and Admin

Deploy the web application $WLS_DISTRIBUTION/webapps/camunda-webapp-ee-wls-$PLATFORM_VERSION.war to your Oracle WebLogic instance.

The following steps describe how to upgrade the Camunda artifacts on an Oracle WebLogic application server in a shared process engine setting. For the entire migration procedure, refer to the migration guide. If not already done, make sure to download the Camunda BPM 7.3 Oracle WebLogic distribution.

The upgrade procedure takes the following steps:

1. Uninstall the Camunda libraries and archives
2. Replace Camunda core libraries
3. Replace optional Camunda dependencies
4. Maintain BPM platform configuration (optional)
5. Install the Camunda archive
6. Install the Camunda BPM web applications

In each of the following steps, the identifiers $*_VERSION refer to the current version and the new versions of the artifacts.

1. Uninstall the Camunda Applications and Archives

First, uninstall the Camunda web applications, namely the Camunda REST API (artifact name like camunda-engine-rest) and the Camunda applications Cockpit, Tasklist and Admin (artifact name like camunda-webapp).

Uninstall the camunda EAR. Its name should be camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear.

2. Replace Camunda Core Libraries

After shutting down the server, replace the following libraries in $WLS_DOMAIN_HOME/lib with their equivalents from $WLS_DISTRIBUTION/modules/lib:

• camunda-engine-$PLATFORM_VERSION.jar
• camunda-bpmn-model-$PLATFORM_VERSION.jar
• camunda-cmmn-model-$PLATFORM_VERSION.jar
• camunda-xml-model-$PLATFORM_VERSION.jar

3. Replace Optional Camunda Dependencies

In addition to the core libraries, there may be optional artifacts in $WLS_DOMAIN_HOME/lib for LDAP integration, Camunda Connect, and Camunda Spin. If you use any of these extensions, the following upgrade steps apply:

LDAP integration

Copy the following libraries from $WLS_DISTRIBUTION/modules/lib to the folder $WLS_DOMAIN_HOME/lib if present:

• camunda-identity-ldap-$PLATFORM_VERSION.jar

Camunda Connect

Copy the following libraries from $WLS_DISTRIBUTION/modules/lib to the folder $WLS_DOMAIN_HOME/lib if present:

• camunda-connect-core-$CONNECT_VERSION.jar

Camunda Spin

Copy the following libraries from $WLS_DISTRIBUTION/modules/lib to the folder $WLS_DOMAIN_HOME/lib if present:

• camunda-spin-core-$SPIN_VERSION.jar

4. Maintain the BPM platform configuration

If you have previously replaced the default BPM platform configuration by a custom configuration following any of the ways outlined in the deployment descriptor reference, it may be necessary to restore this configuration. This can be done by repeating the configuration replacement steps for the upgraded platform.

5. Install the Camunda Archive

Install the Camunda EAR, i.e., the file $WLS_DISTRIBUTION/modules/camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear.

6. Install the Camunda Web Applications

Camunda REST API

Deploy the web application $WLS_DISTRIBUTION/webapps/camunda-engine-rest-$PLATFORM_VERSION-wls.war to your Oracle WebLogic instance.

Camunda Cockpit, Tasklist, and Admin

Deploy the web application $WLS_DISTRIBUTION/webapps/camunda-webapp-ee-wls-$PLATFORM_VERSION.war to your Oracle WebLogic instance.