The following steps describe how to update the Camunda artifacts on a JBoss AS 7, Wildfly 8 and Wildfly 10 server in a shared process engine scenario. For the entire procedure, refer to the update guide. If not already done, make sure to download the Camunda 7.5 JBoss distribution, Camunda 7.5 Wildfly 8 or Camunda 7.5 Wildfly 10 distribution. In the following instructions $APP_SERVER should be replaced with either jboss or wildfly, depending on the used application server.

The update procedure takes the following steps:

1. Update the Camunda 7 Modules
2. Update Optional Camunda 7 Modules
3. Maintain Process Engine Configuration
4. Maintain Process Applications
5. Update 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. Update the Camunda 7 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-dmn-model
• org/camunda/bpm/model/camunda-xml-model
• org/camunda/bpm/dmn/camunda-engine-dmn
• org/camunda/bpm/dmn/camunda-engine-feel-api
• org/camunda/bpm/dmn/camunda-engine-feel-juel
• org/camunda/commons/camunda-commons-logging
• org/camunda/commons/camunda-commons-typed-values
• org/camunda/commons/camunda-commons-utils

2. Update Optional Camunda 7 Modules

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

LDAP Integration

Replace the following module from the folder $APP_SERVER_HOME/modules/ with its new version 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
• org/camunda/connect/camunda-connect-soap-http
• 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

Additionally, also replace the following dependent modules:

• com/fasterxml/jackson/core/jackson-annotations
• com/fasterxml/jackson/core/jackson-core
• com/fasterxml/jackson/core/jackson-databind

Groovy Scripting

Replace the following module from the folder $APP_SERVER_HOME/modules/ with its new version from the folder $APP_SERVER_DISTRIBUTION/modules/ if present:

• org/codehaus/groovy/groovy-all

3. Maintain Process Engine Configuration

This section describes changes in the engine’s default behavior. While the change is reasonable, your implementation may rely on the previous default behavior. Thus, the previous behavior can be restored for shared process engines by explicitly setting a configuration option.

Configuration of Job Executor Thread Pool in Camunda Wildfly 8 subsystem

Beginning with 7.5, the Thread Pool used by the Job Executor is defined as part of the Camunda 7 Wildfly subsystem instead of the JBoss Threads subsystem. The reason is the deprecation and removal of the JBoss Threads subsystem since Wildfly 9. To be compatible with Wildfly 8-10, Camunda rewrote the existing subsystem.
As a consequence, you must transfer your existing Thread Pool configuration from the JBoss Threads subsystem to the Camunda subsystem using the following steps.

1. First, transfer the JBoss Threads configuration to the Camunda 7 subsystem. Search for the JBoss Threads subsystem configuration in your standalone.xml configuration. It looks similar to this example:

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

   Search for the configuration responsible for the Job Executor Thread Pool. For each of the configuration elements and attributes of the JBoss Threads subsystem Job Executor configuration, a representation in the Camunda subsystem exists under the job-executor-element since 7.5.
   Using the above example snippet of the JBoss Threads configuration and the JBoss Threads to Camunda subsystem mapping table at the end of this section, the new Camunda subsystem configuration would look like the following example snippet:

   <subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
    <job-executor>
      <thread-pool-name>job-executor-tp</thread-pool-name>
      <core-threads>3</core-threads>
      <max-threads>10</max-threads>
      <queue-length>3</queue-length>
      <keepalive-time>10</keepalive-time>
      <job-acquisitions>
        ...
      </job-acquisitions>
    </job-executor>
    ...
   </subsystem>
   

2. As second step, since you have now configured the Thread Pool in the Camunda subsystem, remove the JBoss Threads subsystem configuration entry related to the Camunda Job Executor Thread Pool. When there is no other thread-pool configuration entry left, you could also delete the JBoss Threads subsystem entirely.

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

3. As an optional cleanup step, you can delete the JBoss Threads subsystem entry in the extensions element on top of the standalone.xml file, if you no longer need it.

   <server xmlns="urn:jboss:domain:2.2">
    <extensions>
      ...
      <extension module="org.jboss.as.threads"/> <-- REMOVE THIS LINE
      ...
    </extensions>
    ...
   </server>
   

JBoss Threads to Camunda subsystem mapping table

The following mapping table shows the JBoss Threads properties and their counterpart in the Camunda Subsystem to ease the transition of the Job Executor Thread Pool configuration to the Camunda subsystem.

JBoss Threads Property name	Camunda Subsystem Property name	Description
name="job-executor-tp"	<thread-pool-name> job-executor-tp </thread-pool-name>	Specify the name of the thread pool. Can be discarded because it is not longer needed. Default Value: job-executor-tp
<core-threads count="3" />	<core-threads> 3 </core-threads>	Sets the minimum number of threads that are always present in the thread pool. Default Value: 3
<max-threads count="10" />	<max-threads> 10 </max-threads>	Sets the maximum number of threads that can be present in the thread pool. Default Value: 5
<queue-length count="3" />	<queue-length> 3 </queue-length>	Sets the size of the queue for the thread pool => maximum number of tasks storeable in the queue until it signals that it is full. Default Value: 10
<keepalive-time time="10" unit="seconds" />	<keepalive-time> 10 </keepalive-time>	Specify the time in seconds that threads will be kept alive for when there are no tasks present, before threads are terminated until the core-threads number is reached. Default Value: 10
allow-core-timeout="true"	<allow-core-timeout> true </allow-core-timeout>	Specify if core threads are allowed to timeout and shutdown when they idle for the timespan specified by keepalive-time. Default Value: true

For further information on available configuration for the Job Executor Thread Pool, see the docs for Camunda JBoss/WildFly Subsystem

4. Maintain Process Applications

This section describes changes in the internal API of the engine. If you have implemented one of the APIs and replaced the default implementation then you have to adjust your custom implementation. Otherwise, you can skip this section.

Incident Handler

The interface of an Incident Handler has changed. Instead of a long parameter list, the methods pass a context object which bundles all required information, like process definition id, execution id and tenant id. Since the existing methods have been overridden, custom implementations of an incident handler have to be adjusted.

Correlation Handler

A new method has been added to the interface of a Correlation Handler . The new method correlateStartMessage() allows to explicitly trigger a message start event of a process definition. If the default implementation is replaced by a custom one then it has to be adjusted.

Job Handler

The interface of a Job Handler has changed to support multi-tenancy and separate the parsing of the configuration.

5. Update Camunda Web Applications

Update REST API

The following steps are required to update 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 Artifact Repository. Alternatively, switch to the private repository for the enterprise version (username 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.

Update Cockpit, Tasklist, and Admin

The following steps are required to update 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 Artifact Repository. Alternatively, switch to the private repository for the enterprise version (username 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.