camunda BPM Installation Guide (Oracle WebLogic)

This document will guide you through the installation of camunda BPM and its components on a 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 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 WebLogic Server Administration Console:

1. Open the 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-identity-ldap-$PLATFORM_VERSION.jar
           |-- camunda-bpmn-model-$PLATFORM_VERSION.jar
           |-- camunda-xml-model-$PLATFORM_VERSION.jar
      |-- camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear
      |-- camunda-oracle-weblogic-rar-$PLATFORM_VERSION.rar

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 Weblogic Server after this operation.

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

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

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

Both modules must be installed to your Oracle Weblogic Application Server in the correct order. You must first install the camunda-oracle-weblogic-rar module and then install the camunda-oracle-weblogic-ear module. The startup order is also important. It is necessary that the Resource Adapter starts before the EAR module.

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

The installation process is composed of three steps:

1. Install the camunda-oracle-weblogic-rar-$PLATFORM_VERSION.rar RAR file.
2. Configure the deployment order.
3. Configure the RAR-scoped JCA Work Manager to your needs.

Installing the RAR file

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

1. Open the 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-rar-$PLATFORM_VERSION.rar 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 a name for the resource adapter deployment, we propose camunda-oracle-weblogic-rar.
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.

Configure the deployment order

1. In the deployment's configuration screen, change the value of the "Deployment Order" from "100" to "80", so the Resource Adapter starts before the usual deployments.
2. Click "Save" to persist the change.

Example: Deployment order set to "80".

Configure the JCA Work Manager

1. In the deployment's configuration screen, select the "Configuration" tab.
2. Now select the newly available "Workload" tab.
3. Here, you should 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 WebLogic to skip the Stuck Thread Warning which would otherwise appear in the server log every ten minutes .
7. Click "Save" to persist your changes.

Workload tab of camunda-oracle-weblogic-rar deployment:

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

This completes the installation of the resource adapter.

In this section, we explain how the camunda-oracle-weblogic-ear module can be installed using the 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 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 after the Resource Adapter but before the process application deployments.
2. Click "Save" to persist the change.
3. Start the camunda-bpm-platform application if it is not already running. If this initially fails, try to restart the server. The resource adapter references are not always resolved properly. It will be fine after a restart.

Example: Deployment order set to "90".

Completed installation of camunda bpm platform EAR and RAR in WebLogic Server

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

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

1. Open the 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 WLS distribution archive.

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

1. Open the 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 WebLogic 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 $WLS_DOMAIN_HOME/lib folder.

2. Adjust Process Engine Configuration

Edit the file bpm-platform.xml located inside the folder camunda-oracle-weblogic-ear-$PLATFORM_VERSION/camunda-oracle-weblogic-service-$PLATFORM_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 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.