Install the Full Distribution on Oracle WebLogic Application Server

This section will describe how you can install the Camunda Platform and its components on Oracle WebLogic.

Reading this Guide

This guide uses a number of variables to denote common path names and constants.

$WLS_DOMAIN_HOME points to the Oracle WebLogic application server domain directory (typically something like /opt/oracle/WebLogic/domains/mydomain).
$PLATFORM_VERSION denotes the version of the Camunda Platform you want to or have installed, e.g. 7.X.Y.
$WLS_DISTRIBUTION represents the downloaded Camunda Platform distribution for the Oracle WebLogic Application Server, e.g., camunda-ee-oracle-wls-$PLATFORM_VERSION.zip.

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.

Setup

Before you can install the Camunda components, you need to perform a number of required setup steps.

Resource Configuration

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

Create the Database Schema and Tables

In the default configuration of the distribution, the database schema and all required tables are automatically created in an H2 database when the engine starts up for the first time. If you do not want to use the H2 database, you have to

Create a database schema for the Camunda Platform yourself.
Install the database schema to create all required tables and default indices using our database schema installation guide.

When you create the tables manually, then you have to configure the engine to not create tables at startup by setting the databaseSchemaUpdate property to false (or, in case you are using Oracle, to noop). In WebLogic, this is done in the bpm-platform.xml, located in the $WLS_HOME\modules\camunda-oracle-weblogic-ear-$VERSION.ear\camunda-oracle-weblogic-service.jar\META-INF\ folder.

JDBC/Datasource Configuration

The Camunda 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 Platform:

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

Open the Oracle WebLogic Server Administration Console.
Navigate to the “Domain Structure / YOUR_DOMAIN / Services / Data Sources” page.
Click the “New” Button and select “Generic Data Source”.
On the next page, enter a name for the datasource.
Enter the required JNDI Name “jdbc/ProcessEngine”, which is mandatory for the Camunda Platform.
Continue to the next pages and fill in your database credentials.
When you finished the creation of the datasource, click the “Finish” Button to complete the installation.
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.

Required Components

The following steps are required to deploy the Camunda Platform onto an Oracle WebLogic server.

Install the Camunda Platform Domain Libraries

The domain libraries include the Camunda engine and some utility JARs. The domain libraries must be visible to both the Camunda Platform as well as all process applications.

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

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

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

Use a Custom Location for the Domain Libraries

You can change the location of the domain libraries with the -Dweblogic.ext.dirs startup option.

Install the Camunda Platform Modules

The Camunda 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 Platform services. It contains an embedded JCA Resource Adapter, the camunda-oracle-weblogic-rar, which provides the jobexecutor service to the Camunda Platform. It must be installed to your Oracle WebLogic Application Server.

Install the Camunda Platform Application

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:

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

Install the EAR File

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

Open the Oracle WebLogic Server Administration Console.
Navigate to the “Domain structure / YOUR_DOMAIN / Deployments” page.
Select the “Install” button.
Using the File Browser, select the camunda-oracle-weblogic-ear-$PLATFORM_VERSION.ear from the modules folder of the Camunda Platform for Oracle WebLogic Application Server distribution and continue to the “Next” page.
Select “Install this deployment as an application” and continue to the “Next” page.
Fill in camunda-bpm-platform as name for the enterprise application deployment.

Heads Up!

The names of the JNDI Bindings for Camunda Platform Services consist of the name of the enterprise application deployment.

Please note: If you change the name of the enterprise application deployment, the JNDI names change as well.
Continue to the “Next” page.
Select “Yes, take me to the deployment’s configuration screen” and click the “Finish” button to complete the installation.
(optional) Configure location of the bpm-platform.xml file.

Configure the Deployment Order

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.
Click “Save” to persist the change.

Example: Deployment order set to “90”.

Configure the JCA Work Manager

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.
Now select the “Workload” tab.
Here, you see a preconfigured JCA Work Manager named “wm/camunda-bpm-workmanager”. Click on it.
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.
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.
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.
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.
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.

Optional Components

This section describes how to install optional components onto an Oracle WebLogic server. None of these are required to work with the core platform.

Cockpit, Tasklist and Admin

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:

Open the Oracle WebLogic Server Administration Console.
Navigate to the Domain Structure / YOUR_DOMAIN / Deployments page.
Click the Install button. The first page of the Wizard opens.
Using the File Browser, select the camunda-webapp-ee-wls-$PLATFORM_VERSION.war file from the distribution and upload it.
Continue to the Next page.
Select Install this deployment as an application and continue to the Next page.
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.

REST API

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