3.2. Migrating from 6.0.x to 6.1

3.2.1. Migrating Client Application APIs from 6.0.x to 6.1

In this section, we will discuss the migration steps that are specific to migrating from Red Hat JBoss BPM Suite 6.0.x to 6.1.

Important

When using Red Hat JBoss BRMS/BPM Suite prior to 6.1 deployed on Red Hat JBoss EAP, it was possible to load JBoss BRMS/BPM Suite libraries from the JBoss EAP modules by correctly configuring jboss-deployment-structure.xml. In JBoss BRMS and JBoss BPM Suite 6.1, there are no modules including JBoss BRMS/BPM Suite libraries, hence the application developer is responsible to ensure all dependencies will be resolvable during runtime. For more information, see the relevant section in the Red Hat JBoss BPM Suite Development Guide.

Remove Old API

As noted in section Section 2.2.3, “API and Backwards Compatibility”, 6.1 is not backwards compatible with the 5.x API, while 6.0.x was. Therefore, when migrating from 6.0.x to 6.1 version, you will need to remove all references to the old API.

Modify Your (Custom) persistence.xml

There have been several changes in the classes present in the persistence.xml file. If you have been using a custom file for persistence, then you need to be aware of these changes and implement them:

The Task Audit classes have changed from:

<class>org.jbpm.services.task.audit.impl.model.GroupAuditTaskImpl</class>
<class>org.jbpm.services.task.audit.impl.model.HistoryAuditTaskImpl</class>
<class>org.jbpm.services.task.audit.impl.model.UserAuditTaskImpl</class>

to:

<class>org.jbpm.services.task.audit.impl.model.AuditTaskImpl</class>

The Event class has changed from:

<class>org.jbpm.services.task.audit.TaskEventImpl</class>

to:

<class>org.jbpm.services.task.audit.impl.model.TaskEventImpl</class>

There is a new entry for the deployment store:

<class>org.jbpm.kie.services.impl.store.DeploymentStoreEntry</class>

There are some new mapping files that need adding:

<mapping-file>META-INF/Taskorm.xml</mapping-file>
<mapping-file>META-INF/Servicesorm.xml</mapping-file>
<mapping-file>META-INF/TaskAuditorm.xml</mapping-file>

Migrate Classes

6.1 has migrated some API classes to the Services API (and access to those classes has been removed). If you were using these API's because no alternative was available earlier, migrate to these new classes:

old --> new
org.kie.internal.deployment.DeployedUnit; --> org.jbpm.services.api.model.DeployedUnit;
org.kie.internal.deployment.DeploymentService; -->  org.jbpm.services.api.DeploymentService;
org.kie.internal.deployment.DeploymentUnit; --> org.jbpm.services.api.model.DeploymentUnit;
org.jbpm.kie.services.api.IdentityProvider; --> org.kie.internal.identity.IdentityProvider;

Make Changes to Module Ids in Your POMs

The following ids have changed.

old --> new 
kie-services-jaxb --> kie-remote-jaxb
kie-services-client --> kie-remote-client
kie-services-remote --> kie-remote-services

Review JMS Port Changes

In 6.1 4447 is the JNDI port to discover JMS ConnectionFactory connection and to get queues. Port 5445 is used by default for unsecured JMS communication. Port 5446 is used by default for SSL secured JMS communication.

In 6.0.x only port 4447 was necessary to get the JMS ConnectionFactory. This factory provided JMS queues and no other port setting was necessary.

Verify Location of Deployment Units

In 6.1, deployment units are located inside the database. In 6.0, these were stored in the GIT repository. If you want to continue storing your deployment units within the GIT repo, you must use the system property org.kie.git.deployments.enabled and set it to true.

This change is backward compatible. The first time a deployment is run on a new setup it will read up from system.git and deploy into runtime (in database storage). At the same time it will remove it from system GIT to clean it up.

Modify Remote Class API Code

Between 6.0.x and 6.1, the Remote Class API has changed considerably. For example, in 6.0.x, you would use the following code for creating a JMS based runtime engine:

import org.kie.services.client.api.command.RemoteRuntimeEngine;
...
RemoteJmsRuntimeEngineBuilder rjmsreBuilder = RemoteJmsRuntimeEngineFactory.newBuilder().addJbossServerHostName(host).addHostName(host).addUserName(username).addPassword(password).addTimeout(timeout).addDeploymentId(deploymentId).addExtraJaxbClasses(classes);

if( useSsl ) {
  rjmsreBuilder.addKeystoreLocation("client0.keystore.jks").addKeystorePassword(storePassword).addTruststorePassword(storePassword).useKeystoreAsTruststore().addJmsConnectorPort(sslPort);
  } else {
    rjmsreBuilder.useSsl(false).addJmsConnectorPort(port);
  }
  
RemoteRuntimeEngine remoteRuntimeEngine = rjmsreBuilder.build();

or the following code for creating a REST based runtime engine:

remoteRuntimeEngine = RemoteRestRuntimeEngineFactory.newBuilder().addUrl(url).addUserName(username).addPassword(password).addDeploymentId(deploymentId).addExtraJaxbClasses(classes).build();

This code should be modified as the Remote Class API defines new generalized interface for remote runtime engine: org.kie.api.runtime.manager.RuntimeEngine. To create the runtime engines in 6.1, use the following code (JMS):

// for JMS
import org.kie.api.runtime.manager.RuntimeEngine;
...

RemoteJmsRuntimeEngineBuilder rjmsreBuilder = RemoteRuntimeEngineFactory.newJmsBuilder().addJbossServerHostName(host).addHostName(host).addUserName(username).addPassword(password).addTimeout(timeout).addDeploymentId(deploymentId).addExtraJaxbClasses(classes);

// 5446 is the default secured jms port, 5445 the default unsecured jms port
if ( port == 5446 ) {
  rjmsreBuilder.addKeystoreLocation("client0.keystore.jks").addKeystorePassword(storePassword).addTruststorePassword(storePassword).useKeystoreAsTruststore().addJmsConnectorPort(port);
  
  sslStatus = "enabled";
} else if (port == 5445) {
  rjmsreBuilder
    .useSsl(false)
    .disableTaskSecurity()
    .addJmsConnectorPort(port);
  sslStatus = "disabled";
  } else {
    throw new IllegalArgumentException("Unsupported jms port, valid ones are secured 5446 and unsecured 5445.");
  }
  
  RuntimeEngine remoteRuntimeEngine = rjmsreBuilder.build();

and the following code for REST:

remoteRuntimeEngine = remoteRuntimeEngineFactory.newRestBuilder().addUrl(url).addUserName(username).addPassword(password).addDeploymentId(deploymentId).addExtraJaxbClasses(classes).build();

Rename the AuditLogService Class

If you were using the AuditLogService in 6.0.x branch, migrate that to the renamed class: AuditService. Method names have changed accordingly: remoteRuntimeEngine.getAuditLogService() should be changed to remoteRuntimeEngine.getAuditService().

3.2.2. Migrating Business Central Project, Repository and Artifacts from 6.0.x to 6.1

Use the following procedure to move your existing Red Hat JBoss BPM Suite 6.0.x git projects (.niogit folder) and maven local dependencies (bin/repositories) to a new JBoss BPM Suite 6.1 installation.

Note, the example commands used in the following procedures are based on migrating from JBoss BPM Suite 6.0.3 to 6.1.

Procedure 3.3. Migrate a Single Project

Turn off JBoss BPM Suite 6.0.x and JBoss BPM Suite 6.1 instances.
Navigate to .niogit folder of JBoss BPM Suite 6.0.x installation.
Clone the repository where desired project is located.
```
$ git clone repository603.git
```
Navigate to the JBoss BPM Suite 6.1.0 niogit folder.
Clone the repository where you want to migrate the 6.0.x project.
```
$ git clone repository610.git
```
Copy the project from 6.0.x cloned repository to 6.1.x cloned repository.
```
$ cp -R /path/to/6.0.3/project /path/to/6.1.0/repository
```
Navigate to the 6.1.0 cloned repository.
```
$ cd /path/to/6.1.0/repository
```

Commit the newly added 6.0.x project to your new 6.1.0 repository.

$ git add ./copied-6.0.3-project/*
$ git commit -m "migrating 6.0.3 project to 6.1.0 repository"
$ git push

Start JBoss BPM Suite 6.1.0. The 6.0.3 project should be successfully migrated and visible under the specified repository.

Note

The outcome of the above procedure may also be achieved by using the eGit plugin for Red Hat JBoss Developer Studio. See the relevant section in the Red Hat JBoss BPM Suite Development Guide.

Migrating a Repository

The following procedure demonstrates how to migrate a selected JBoss BPM Suite 6.0.x repository to JBoss BPM Suite 6.1.0 installation.

Procedure 3.4. Clone and Migrate a Repository

Turn on JBoss BPM Suite 6.1.0.
Log in to Business Central and navigate to Authoring → Administration → Repositories → Clone Repository.

Fill in the form. For example:

Repository Name - MyOld603Repo
Organizational Unit - example
Git URL - file:///path/to/old/603/.niogit/repository.git

and press Confirm.

The repository should be now available for Authoring.

For more information about cloning repositories, see the Red Hat JBoss BPM Suite Administration and Configuration Guide.

Migrating a Maven Artifact

The Artifact Repository is an internal maven repository for JBoss BPM Suite. The default internal maven repository is created in a working directory of JBoss BPM Suite 6.1.0 installation, with the folder name repositories/kie.

Maven artifacts can be migrated using the GUI.

Procedure 3.5. Migrating Maven Artifacts using the GUI

Turn on JBoss BPM Suite 6.1.
Navigate to Authoring → Artifact Repository.
Upload the Artifact from your old 6.0.3 installation.

Alternatively, following procedure demonstrates how to migrate selected maven artifact from JBoss BPM Suite 6.0.x Artifact Repository to a JBoss BPM Suite 6.1.0 Artifact Repository, and assumes that the two Artifact Repositories are located on the same physical system.

Procedure 3.6. Migrating a Particular Artifact

Consider following KJAR, which was installed into JBoss BPM Suite 6.0.x Artifact Repository by Business Central.
Figure 3.1. Installed KJAR
Copy this artifact to the JBoss BPM Suite 6.1.0 Artifact Repository. For example:
```
$ cp -R --parents /path/to/603/kjar/kie/org/redhat/gss/TimerProject/
/path/to/bpms-610-psql/bin/repositories/
```
The --parents argument will ensure that all the necessary folders (if missing) will be created in 6.1.0 too. In this case, it will honor the /org/redhat/gss/TimerProject path.
After copying, the 6.1.0 maven repository should look appear as follows:
Figure 3.2. Copied Artifact
Start the JBoss BPM Suite 6.1.0 installation and navigate to Artifact Repository. The copied artifact should be present as shown.
Figure 3.3. Artifact Repository

Migrating the .niogit Folder

In order to migrate the whole .niogit from 6.0.x to 6.1.0, set the org.uberfire.nio.git.dir property in 6.1.0 as follows.

$ ./standalone.sh -Dorg.uberfire.nio.git.dir=/path/to/6.0.3/.niogit

3.2.3. Upgrading the Database from 6.0.x to 6.1

Ensure that the database has been upgraded as documented in Section 3.4, “Database Migration for 6.x Instances”.

Where did the comment section go?

Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.

Log in to Your Red Hat Account

Red Hat Account

Customer Portal

Select Your Language

Infrastructure and Management

Cloud Computing

Storage

JBoss Development and Management

JBoss Integration and Automation

Mobile

Services

Tools

Red Hat Product Security Center

Security Updates

Resources

Customer Portal Community

Customer Events

Stories

3.2. Migrating from 6.0.x to 6.1

3.2.1. Migrating Client Application APIs from 6.0.x to 6.1

Remove Old API

Modify Your (Custom) persistence.xml

Migrate Classes

Make Changes to Module Ids in Your POMs

Review JMS Port Changes

Verify Location of Deployment Units

Modify Remote Class API Code

Rename the AuditLogService Class

3.2.2. Migrating Business Central Project, Repository and Artifacts from 6.0.x to 6.1

3.2.3. Upgrading the Database from 6.0.x to 6.1

Where did the comment section go?