1. Home
  2. Guides
  3. Installation Guide
  4. Camunda BPM Installation Guide (JBoss / Wildfly)

Camunda BPM Installation Guide (JBoss / Wildfly)

Introduction

Overview

This document will guide you through the installation of camunda BPM and its components on a JBoss Application Server 7 / JBoss EAP 6 or Wildfly 8 Application Server.

Reading the Guide
Throughout this guide we will use a number of variables to denote common path names and constants:
$JBOSS_HOME/$WILDFLY_HOME points to the JBoss/Wildfly application server main directory.
$PLATFORM_VERSION denotes the version of the camunda BPM platform you want to install or already have installed, e.g. 7.0.0.

BPM Platform

Install the pre-built distro

  1. Download the pre-packaged distribution for JBoss AS 7 from http://camunda.org/release/camunda-bpm/jboss/ or Wildfly 8 from http://camunda.org/release/camunda-bpm/wildfly/.
  2. Unpack the distro to a directory.
  3. Adjust the datasource according to your needs (see below).
  4. Startup the server by running camunda-welcome.bat or by using the $JBOSS_HOME/bin/standalone.{bat/sh} script.

Accessing the H2 console

In JBoss/Wildfly you can easily access the H2 console to inspect your local H2 database (used in demo/evaluation scenarios):

  1. Go to http://localhost:8080/h2/h2
  2. Login with the following data:
    • jdbc:h2:./camunda-h2-dbs/process-engine
    • User: sa
    • Password: sa

Install the platform on a vanilla JBoss

  1. Download the camunda jboss distro from our server. Choose the correct version named $PLATFORM_VERSION/camunda-bpm-jboss-$PLATFORM_VERSION.zip or $PLATFORM_VERSION/camunda-bpm-jboss-$PLATFORM_VERSION.tar.gz.
  2. Unpack the modules folder of the archive.
  3. Merge all content into your $JBOSS_HOME/modules/ directory.
  4. Adjust your $JBOSS_HOME/standalone/configuration/standalone.xml (or the JBoss configuration applicable for your installation) as described below
  5. Adjust the datasource to your needs (see below), by default it uses the built in H2 database
  6. Startup the server

Adjusting the standalone.xml

Here we describe the changes necessary in the $JBOSS_HOME/standalone/configuration/standalone.xml. These are already done in the pre-packaged server.

Add the Camunda subsystem as extension. Also add the org.jboss.as.threads extension if not already present to the extension section of the standalone.xml:

<server xmlns="urn:jboss:domain:1.1">
  <extensions>
    ...
    <extension module="org.camunda.bpm.jboss.camunda-jboss-subsystem"/>
    <!-- Add the 'org.jboss.as.threads' extension if not already exists -->
    <extension module="org.jboss.as.threads"/>

Add the following elements in order to create a thread pool for the Job Executor in the <subsystem xmlns="urn:jboss:domain:threads:1.1"> section:

<subsystem xmlns="urn:jboss:domain:threads:1.1">
  <bounded-queue-thread-pool name="job-executor-tp" allow-core-timeout="true">
    <core-threads count="3" />
    <queue-length count="3" />
    <max-threads count="10" />
    <keepalive-time time="10" unit="seconds" />
  </bounded-queue-thread-pool>
</subsystem>

The name of the thread pool is then referenced in the camunda bpm subsystem job executor configuration. This also configures the default process engine.

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  <process-engines>
    <process-engine name="default" default="true">
      <datasource>java:jboss/datasources/ProcessEngine</datasource>
      <history-level>full</history-level>
      <properties>
        <property name="jobExecutorAcquisitionName">default</property>
        <property name="isAutoSchemaUpdate">true</property>
        <property name="authorizationEnabled">true</property>
        <property name="jobExecutorDeploymentAware">true</property>
      </properties>
    </process-engine>
  </process-engines>
  <job-executor>
    <thread-pool-name>job-executor-tp</thread-pool-name>
    <job-acquisitions>
      <job-acquisition name="default">
        <acquisition-strategy>SEQUENTIAL</acquisition-strategy>
        <properties>
          <property name="lockTimeInMillis">300000</property>
          <property name="waitTimeInMillis">5000</property>
          <property name="maxJobsPerAcquisition">3</property>
        </properties>
      </job-acquisition>
    </job-acquisitions>
  </job-executor>
</subsystem>

Creating a datasource

You need to create a datasource named java:jboss/datasources/ProcessEngine. The following datasource shows an example of using the built in H2 database for this, using a file within the ./ folder, typically bin.

Note: If you start the script from a different location the database is stored there!

<datasource jta="true" enabled="true" use-java-context="true" use-ccm="true"
            jndi-name="java:jboss/datasources/ProcessEngine" 
            pool-name="ProcessEngine">
  <connection-url>jdbc:h2:./camunda-h2-dbs/process-engine;DB_CLOSE_DELAY=-1;MVCC=TRUE;DB_CLOSE_ON_EXIT=FALSE</connection-url>
  <driver>h2</driver>
  <security>
    <user-name>sa</user-name>
    <password>sa</password>
  </security>
</datasource>

Using H2 as a database is ideal for development purposes but is not recommended for usage in a productive environment. These links point you to resources for other databases:

Using an XA datasource

We strongly recommend to use an XA data-source in production environments. Since you normally access other transactional resources from within your process, the risk of having inconsistencies is otherwise high. For H2 it could be done with this configuration:

<xa-datasource jndi-name="java:jboss/datasource/ProcessEngine" pool-name="ProcessEngine" enabled="true" use-ccm="false">
  <xa-datasource-property name="URL">jdbc:h2:./camunda-h2-dbs/process-engine;DB_CLOSE_DELAY=-1;MVCC=TRUE;DB_CLOSE_ON_EXIT=FALSE</xa-datasource-property>
  <driver>h2</driver>
  <xa-pool>
    <max-pool-size>10</max-pool-size>
    <is-same-rm-override>false</is-same-rm-override>
    <interleaving>false</interleaving>
    <pad-xid>false</pad-xid>
    <wrap-xa-resource>false</wrap-xa-resource>
  </xa-pool>
  <security>
    <user-name>sa</user-name>
    <password>sa</password>
  </security>
  <validation>
    <validate-on-match>false</validate-on-match>
    <background-validation>false</background-validation>
    <background-validation-millis>0</background-validation-millis>
  </validation>
  <statement>
    <prepared-statement-cache-size>0</prepared-statement-cache-size>
    <share-prepared-statements>false</share-prepared-statements>
  </statement>
</xa-datasource>

For other databases, confer the following resources:

Install the platform on a vanilla Wildfly

  1. Download the camunda Wildfly distro from our server. Choose the correct version named $PLATFORM_VERSION/camunda-bpm-wildfly-$PLATFORM_VERSION.zip or $PLATFORM_VERSION/camunda-bpm-wildfly-$PLATFORM_VERSION.tar.gz.
  2. Unpack the modules folder of the archive.
  3. Merge all content into your $WILDFLY_HOME/modules/ directory.
  4. Adjust your $WILDFLY_HOME/standalone/configuration/standalone.xml (or the Wildfly configuration applicable for your installation) as described below
  5. Adjust the datasource to your needs (see below), by default it uses the built in H2 database
  6. Startup the server

Adjusting the standalone.xml

Here we describe the changes necessary in the $WILDFLY_HOME/standalone/configuration/standalone.xml. These are already done in the pre-packaged server.

Add the camunda subsystem as extension:

<server xmlns="urn:jboss:domain:2.1">
  <extensions>
    ...
    <extension module="org.camunda.bpm.wildfly.camunda-wildfly-subsystem"/>

Add the following elements in order to create a thread pool for the Job Executor:

<subsystem xmlns="urn:jboss:domain:threads:1.1">
  <bounded-queue-thread-pool name="job-executor-tp" allow-core-timeout="true">
    <core-threads count="3" />
    <queue-length count="3" />
    <max-threads count="10" />
    <keepalive-time time="10" unit="seconds" />
  </bounded-queue-thread-pool>
</subsystem>

The name of the thread pool is then referenced in the camunda bpm subsystem job executor configuration. This also configures the default process engine.

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  <process-engines>
    <process-engine name="default" default="true">
      <datasource>java:jboss/datasources/ProcessEngine</datasource>
      <history-level>full</history-level>
      <properties>
        <property name="jobExecutorAcquisitionName">default</property>
        <property name="isAutoSchemaUpdate">true</property>
        <property name="authorizationEnabled">true</property>
        <property name="jobExecutorDeploymentAware">true</property>
      </properties>
    </process-engine>
  </process-engines>
  <job-executor>
    <thread-pool-name>job-executor-tp</thread-pool-name>
    <job-acquisitions>
      <job-acquisition name="default">
        <acquisition-strategy>SEQUENTIAL</acquisition-strategy>
        <properties>
          <property name="lockTimeInMillis">300000</property>
          <property name="waitTimeInMillis">5000</property>
          <property name="maxJobsPerAcquisition">3</property>
        </properties>
      </job-acquisition>
    </job-acquisitions>
  </job-executor>
</subsystem>

Creating a datasource

You need to create a datasource named java:jboss/datasources/ProcessEngine. The following datasource shows an example of using the built in H2 database for this, using a file within the ./ folder, typically bin.

Note: If you start the script from a different location the database is stored there!

<datasource jta="true" enabled="true" use-java-context="true" use-ccm="true"
            jndi-name="java:jboss/datasources/ProcessEngine" 
            pool-name="ProcessEngine">
  <connection-url>jdbc:h2:./camunda-h2-dbs/process-engine;DB_CLOSE_DELAY=-1;MVCC=TRUE;DB_CLOSE_ON_EXIT=FALSE</connection-url>
  <driver>h2</driver>
  <security>
    <user-name>sa</user-name>
    <password>sa</password>
  </security>
</datasource>

Using H2 as a database is ideal for development purposes but is not recommended for usage in a productive environment. These links point you to resources for other databases:

Using an XA datasource

We strongly recommend to use an XA data-source in production environments. Since you normally access other transactional resources from within your process, the risk of having inconsistencies is otherwise high. For H2 it could be done with this configuration:

<xa-datasource jndi-name="java:jboss/datasource/ProcessEngine" pool-name="ProcessEngine" enabled="true" use-ccm="false">
  <xa-datasource-property name="URL">jdbc:h2:./camunda-h2-dbs/process-engine;DB_CLOSE_DELAY=-1;MVCC=TRUE;DB_CLOSE_ON_EXIT=FALSE</xa-datasource-property>
  <driver>h2</driver>
  <xa-pool>
    <max-pool-size>10</max-pool-size>
    <is-same-rm-override>false</is-same-rm-override>
    <interleaving>false</interleaving>
    <pad-xid>false</pad-xid>
    <wrap-xa-resource>false</wrap-xa-resource>
  </xa-pool>
  <security>
    <user-name>sa</user-name>
    <password>sa</password>
  </security>
  <validation>
    <validate-on-match>false</validate-on-match>
    <background-validation>false</background-validation>
    <background-validation-millis>0</background-validation-millis>
  </validation>
  <statement>
    <prepared-statement-cache-size>0</prepared-statement-cache-size>
    <share-prepared-statements>false</share-prepared-statements>
  </statement>
</xa-datasource>

For other databases, confer the following resources:

Install Optional Camunda Dependencies

This section describes how to install optional Camunda dependencies onto a JBoss server. None of these are required to work with the core platform. Before continuing, make sure that the Camunda BPM platform is already installed according to this step.

Note

When using a pre-packaged JBoss distribution, the optional extensions are already installed and activated.

The following covers the installation of these extensions:

Install Camunda Connect

Add the following modules (if not existing) from the folder $JBOSS_DISTRIBUTION/modules/ to the folder $JBOSS_HOME/modules/:

  • org/camunda/connect/camunda-connect-core
  • org/camunda/connect/camunda-connect-http-client
  • org/camunda/connect/camunda-connect-soap-http-client
  • org/camunda/bpm/camunda-engine-plugin-connect
  • org/camunda/commons/camunda-commons-logging
  • org/camunda/commons/camunda-commons-utils
  • org/apache/httpcomponents/httpclient
  • org/apache/httpcomponents/httpcore
  • commons-codec/commons-codec
  • commons-logging/commons-logging

In order to activate Camunda Connect functionality for a process engine, a process engine plugin has to be registered in $JBOSS_HOME/standalone/configuration/standalone.xml as follows:

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  ...
  <process-engines>
    <process-engine name="default" default="true">
      ...
      <plugins>
        ... existing plugins ...
        <plugin>
          <class>org.camunda.connect.plugin.impl.ConnectProcessEnginePlugin</class>
        </plugin>
      </plugins>
      ...
    </process-engine>
  </process-engines>
  ...
</subsystem>

Install Camunda Spin

Add the following modules (if not existing) from the folder $JBOSS_DISTRIBUTION/modules/ to the folder $JBOSS_HOME/modules/:

  • org/camunda/spin/camunda-spin-core
  • org/camunda/spin/camunda-spin-dataformat-json-jackson
  • org/camunda/spin/camunda-spin-dataformat-xml-dom
  • org/camunda/bpm/camunda-engine-plugin-spin
  • org/camunda/commons/camunda-commons-logging
  • org/camunda/commons/camunda-commons-utils
  • com/fasterxml/jackson/core/jackson-core
  • com/fasterxml/jackson/core/jackson-databind
  • com/fasterxml/jackson/core/jackson-annotations
  • com/jayway/jsonpath/json-path

In order to activate Camunda Spin functionality for a process engine, a process engine plugin has to be registered in $JBOSS_HOME/standalone/configuration/standalone.xml as follows:

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  ...
  <process-engines>
    <process-engine name="default" default="true">
      ...
      <plugins>
        ... existing plugins ...
        <plugin>
          <class>org.camunda.spin.plugin.impl.SpinProcessEnginePlugin</class>
        </plugin>
      </plugins>
      ...
    </process-engine>
  </process-engines>
  ...
</subsystem>

Install Groovy Scripting

Add the following modules (if not existing) from the folder $JBOSS_DISTRIBUTION/modules/ to the folder $JBOSS_HOME/modules/:

  • org/codehaus/groovy/groovy-all

Install Freemarker Integration

Add the following modules (if not existing) from the folder $JBOSS_DISTRIBUTION/modules/ to the folder $JBOSS_HOME/modules/:

  • org/camunda/template-engines/camunda-template-engines-freemarker
  • org/freemarker/freemarker
  • org/camunda/commons/camunda-commons-logging
  • org/camunda/commons/camunda-commons-utils

Web Applications

Install the REST API web application

To install the REST API, a JBoss / Wildfly installation with the org.camunda.bpm.camunda-engine module is required. See the above section on how to install the pre-built distro or install the platform on a vanilla JBoss / Wildfly.

Note: The distro already ships the REST API exposing it on the context path /engine-rest.

The following steps are required to deploy the REST API on a JBoss instance:

  1. Download the REST API web application archive from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-engine-rest-$PLATFORM_VERSION.war.
  2. Optionally, you may change the context path to which the REST API will be deployed (default is /engine-rest). Edit the file WEB-INF/jboss-web.xml in the war file and update the context-root element accordingly.
  3. Copy the war file to $JBOSS_HOME/standalone/deployments.
  4. Startup JBoss AS / Wildfly.
  5. Access the REST API on the context path you configured. For example, http://localhost:8080/engine-rest/engine should return the names of all engines of the platform, provided that you deployed the application in the context /engine-rest.

Install camunda Cockpit and Tasklist

To install camunda Cockpit and Tasklist, a JBoss / Wildfly installation with the org.camunda.bpm.camunda-engine module is required. See the above section on how to install the pre-built distro or install the platform on a vanilla JBoss / Wildfly.

Note: The distro already ships the applications. They may be accessed via /camunda/app/cockpit and /camunda/app/tasklist, respectively.

The following steps are required to deploy the applications on a JBoss / Wildfly instance:

  1. Download the camunda web application that contains both applications from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-webapp-jboss-$PLATFORM_VERSION.war.
  2. Optionally, you may change the context path to which the application will be deployed (default is /camunda). Edit the file WEB-INF/jboss-web.xml in the war file and update the context-root element accordingly.
  3. Copy the war file to $JBOSS_HOME/standalone/deployments.
  4. Startup JBoss AS / Wildfly.
  5. Access Cockpit and Tasklist via /camunda/app/cockpit and /camunda/app/tasklist or under the context path you configured.

LDAP Configuration

Configuring LDAP for camunda Cockpit and Tasklist

In order to setup LDAP for the JBoss Application Server distribution, you have to perform the following steps:

Adjust the Process Engine Configuration

Edit the file standalone.xml (or domain.xml) provided by the JBoss / Wildfly Application Server and add the LDAP Identity Provider Plugin and the Administrator Authorization Plugin.

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  <process-engines>
    <process-engine name="default" default="true"> ...
      <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">ou=employees</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">ou=roles</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>
  </process-engines> ...
</subsystem>

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 in to 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-jboss-$PLATFORM_VERSION.war/WEB-INF/lib):

<?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>

Migration

Migrate from Camunda BPM 7.1 to Camunda BPM 7.2

The following steps describe how to upgrade the Camunda artifacts on a JBoss AS 7 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 JBoss distribution.

The upgrade procedure takes the following steps:

  1. Upgrade the Camunda BPM modules
  2. Configure process engines
  3. Configure optional Camunda BPM extensions (optional)
  4. Upgrade Camunda web applications

Whenever the instructions are to replace a module, make sure to delete the previous version of the module first to avoid orphan jars.

1. Upgrade the Camunda BPM Modules

Replace the following modules from the folder $JBOSS_HOME/modules/ with their new versions from the folder $JBOSS_DISTRIBUTION/modules/:

  • org/camunda/bpm/camunda-engine
  • org/camunda/bpm/jboss/camunda-jboss-subsystem
  • org/camunda/bpm/model/camunda-bpmn-model
  • org/camunda/bpm/model/camunda-xml-model
  • org/mybatis/mybatis

If present, also replace the following optional module:

  • org/camunda/bpm/identity/camunda-identity-ldap

Add the following modules from the folder $JBOSS_DISTRIBUTION/modules/ to the folder $JBOSS_HOME/modules/:

  • org/camunda/bpm/model/camunda-cmmn-model
  • org/camunda/commons/camunda-commons-logging
  • org/camunda/commons/camunda-commons-utils
  • org/camunda/connect/camunda-connect-core
  • org/camunda/connect/camunda-connect-http-client
  • org/camunda/connect/camunda-connect-soap-http-client
  • org/camunda/bpm/camunda-engine-plugin-connect
  • org/apache/httpcomponents/httpclient
  • org/apache/httpcomponents/httpcore
  • commons-codec/commons-codec
  • commons-logging/commons-logging
  • org/camunda/spin/camunda-spin-core
  • org/camunda/spin/camunda-spin-dataformat-json-jackson
  • org/camunda/spin/camunda-spin-dataformat-xml-dom
  • org/camunda/bpm/camunda-engine-plugin-spin
  • com/fasterxml/jackson/core/jackson-core
  • com/fasterxml/jackson/core/jackson-databind
  • com/fasterxml/jackson/core/jackson-annotations
  • com/jayway/jsonpath/json-path
  • org/codehaus/groovy/groovy-all
  • org/camunda/template-engines/camunda-template-engines-freemarker
  • org/freemarker/freemarker

2. 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 standalone.xml:

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  ...
  <process-engines>
    <process-engine name="default" default="true">
      ...
      <properties>
        ... existing properties ...
        <property name="autoStoreScriptVariables">true</property>
      </properties>
      ...
    </process-engine>
  </process-engines>
  ...
</subsystem>

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').

3. Configure Optional Camunda BPM modules

In addition, there are modules for Camunda Connect, Camunda Spin, the Freemarker template language and Groovy scripting that extend the Camunda BPM functionality. Since all these artifacts add new functionality, the following steps are not required for migration.

Camunda Connect

In order to activate Camunda Connect functionality for a process engine, a process engine plugin has to be registered in $JBOSS_HOME/standalone/configuration/standalone.xml as follows:

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  ...
  <process-engines>
    <process-engine name="default" default="true">
      ...
      <plugins>
        ... existing plugins ...
        <plugin>
          <class>org.camunda.connect.plugin.impl.ConnectProcessEnginePlugin</class>
        </plugin>
      </plugins>
      ...
    </process-engine>
  </process-engines>
  ...
</subsystem>

Camunda Spin

In order to activate Camunda Spin functionality for a process engine, a process engine plugin has to be registered in $JBOSS_HOME/standalone/configuration/standalone.xml as follows:

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  ...
  <process-engines>
    <process-engine name="default" default="true">
      ...
      <plugins>
        ... existing plugins ...
        <plugin>
          <class>org.camunda.spin.plugin.impl.SpinProcessEnginePlugin</class>
        </plugin>
      </plugins>
      ...
    </process-engine>
  </process-engines>
  ...
</subsystem>

4. Upgrade Camunda Web Applications

Upgrade Camunda REST API

The following steps are required to upgrade the camunda REST API on a JBoss instance:

  1. Undeploy an existing web application with a name like camunda-engine-rest
  2. Download the REST API web application archive from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-engine-rest-$PLATFORM_VERSION.war.
  3. Deploy the web application archive to your JBoss instance.

Upgrade Camunda Cockpit, Tasklist, and Admin

The following steps are required to upgrade the Camunda web applications Cockpit, Tasklist, and Admin on a JBoss instance:

  1. Undeploy an existing web application with a name like camunda-webapp
  2. Download the Camunda web application archive from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-webapp-jboss-$PLATFORM_VERSION.war.
  3. Deploy the web application archive to your JBoss instance.

LDAP Entity Caching

With 7.2, it is possible to enable entity caching for Hypertext Application Language (HAL) requests that the Camunda web applications make. This can be especially useful when you use Camunda in combination with LDAP. To activate caching, the Camunda webapp artifact has to be modified and the pre-built application cannot be used as is. See the REST Api Documentation for details.

Migrate from Camunda BPM 7.2 to Camunda BPM 7.3

The following steps describe how to upgrade the Camunda artifacts on a JBoss AS 7 and Wildfly 8 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 JBoss distribution or Camunda BPM 7.3 Wildfly distribution. In the following instructions $APP_SERVER should be replaced with either jboss or wildfly depending on the used application server.

The upgrade procedure takes the following steps:

  1. Upgrade the Camunda BPM modules
  2. Upgrade optional Camunda BPM modules
  3. Upgrade Camunda web applications

Whenever the instructions are to replace a module, make sure to delete the previous version of the module first to avoid orphan jars.

Upgraded Wildfly Version

The pre-built Camunda 7.3 distribution ships with Wildfly 8.2.0.Final, whereas 7.2 comes with Wildfly 8.1.0.Final. Camunda 7.3 is supported on Wildfly 8.1 and 8.2 such that an upgrade is not required when migrating from 7.2 to 7.3.

Should you want to upgrade Wildfly along with Camunda, perform the following steps either before or after upgrading Camunda:

  • Copy all your Camunda-related modules from $WILDFLY_HOME/modules to the new Wildfly server's module-directory.
  • Apply all modifications to Wildfly configuration files such as standalone.xml to the files located in the new Wildfly server's directory.
  • Undeploy all process applications and copy them to the new Wildfly server's directory for redeployment.

See the Wildfly 8.2.0.Final release notes for any relevant changes compared to 8.1.0.Final.

1. Upgrade the Camunda BPM modules

Replace the following modules from the folder $APP_SERVER_HOME/modules/ with their new versions from the folder $APP_SERVER_DISTRIBUTION/modules/:

  • org/camunda/bpm/camunda-engine
  • org/camunda/bpm/$APP_SERVER/camunda-$APP_SERVER-subsystem
  • org/camunda/bpm/model/camunda-bpmn-model
  • org/camunda/bpm/model/camunda-cmmn-model
  • org/camunda/bpm/model/camunda-xml-model

2. Upgrade Optional Camunda BPM modules

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

LDAP integration

Replace the following modules from the folder $APP_SERVER_HOME/modules/ with their new versions from the folder $APP_SERVER_DISTRIBUTION/modules/ if present:

  • org/camunda/bpm/identity/camunda-identity-ldap

Camunda Connect

Replace the following modules from the folder $APP_SERVER_HOME/modules/ with their new versions from the folder $APP_SERVER_DISTRIBUTION/modules/ if present:

  • org/camunda/connect/camunda-connect-core
  • org/camunda/connect/camunda-connect-http-client
  • org/camunda/connect/camunda-connect-soap-http-client
  • org/camunda/bpm/camunda-engine-plugin-connect

Camunda Spin

Replace the following modules from the folder $APP_SERVER_HOME/modules/ with their new versions from the folder $APP_SERVER_DISTRIBUTION/modules/ if present:

  • org/camunda/spin/camunda-spin-core
  • org/camunda/spin/camunda-spin-dataformat-json-jackson
  • org/camunda/spin/camunda-spin-dataformat-xml-dom
  • org/camunda/bpm/camunda-engine-plugin-spin
  • com/fasterxml/jackson/core/jackson-core
  • com/fasterxml/jackson/core/jackson-databind
  • com/fasterxml/jackson/core/jackson-annotations

3. Upgrade Camunda Web Applications

Upgrade Camunda REST API

The following steps are required to upgrade the camunda REST API on a JBoss/Wildfly instance:

  1. Undeploy an existing web application with a name like camunda-engine-rest
  2. Download the REST API web application archive from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-engine-rest-$PLATFORM_VERSION.war.
  3. Deploy the web application archive to your JBoss/Wildfly instance.

Upgrade Camunda Cockpit, Tasklist, and Admin

The following steps are required to upgrade the Camunda web applications Cockpit, Tasklist, and Admin on a JBoss/Wildfly instance:

  1. Undeploy an existing web application with a name like camunda-webapp
  2. Download the Camunda web application archive from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-webapp-jboss.war.
  3. Deploy the web application archive to your JBoss/Wildfly instance.

LDAP Entity Caching

Beginning with 7.2, it is possible to enable entity caching for Hypertext Application Language (HAL) requests that the Camunda web applications make. If you have previously used caching, you can enable this feature by modifying the Camunda webapp artifact. See the REST Api Documentation for details.