2.2. How-To Migrate

Migrating your projects from Red Hat JBoss BPM Suite 5 to Red Hat JBoss BPM Suite 6 requires careful planning and step by step evaluation of the various issues. You can plan for migration either manually, or by using automatic processes. Most real world migration will require a combination of these two processes.
Because JBoss BPM Suite 6 uses GIT for storing assets, artifacts and code repositories including processes and rules, you should start by creating an empty project in JBoss BPM Suite 6 as the basis for your migration with dummy files as placeholders for the various assets and artifacts. Running a GIT clone of this empty project into your favorite IDE will initiate the migration process.
Based on the placeholder files in your cloned project, you can start adding assets at the correct locations. The JBoss BPM Suite 6 system is smart enough to pick these changes and apply them correctly. Ensure that when you are importing old rule files that they are imported with the right package name structure.
Since Maven is used for building projects, the projects assets like the rules, processes and models are accessible as a simple jar file.
This section lists the generally accepted step by step ways to migrate your project. These are just guidelines though, and actual migration may vary a lot from this.
In general, you should...
  1. Migrate the data first: These are your business assets.
  2. Next, migrate your runtime processes.
  3. Finally, convert old API calls to new ones one by one.
Let's look at these steps in more detail in the next few sections.

2.2.1. Data Migration

To migrate data from Red Hat JBoss BPM Suite 5, do the following:
  1. Download the migration tool by logging in at the Red Hat Customer Portal and then navigating to Red Hat JBoss BPM Suite Software Downloads section. Click on Red Hat JBoss BPM Suite Migration Tool to download the zip archive.
  2. Unzip the downloaded zip archive in a directory of your choice and navigate to this directory in a command prompt. This directory contains four folders:
    • bin - contains the launch scripts.
    • jcr-exporter-libs - contains the libs specific to the export-from-JCR part of the migration.
    • vfs-importer-libs - contains the libs specific to the import-into-Git part of the migration.
    • conf - contains global migration tool configuration.
  3. For production databases, copy the JDBC driver for the database that is used by the JCR repository into the jcr-exporter-libs directory of the migration tool.
  4. Execute the following command: 
    ./bin/runMigration.sh -i <source-path> -o <destination-path> -r <repository-name>
Where:
  • <source-path> is a path to a source JCR repository.
  • <desintation-path> is a path to a destination GIT VFS. This folder must not exist already.
  • <repository-name> an arbitrary name for the new repository.
The repository is migrated at the specified destination.
Besides the -i command, you can also use -h to print out a help message and -f which forces an overwrite of the output directory, thus eliminating the need for manual deletion of this directory.

Importing the repository in Business Central

The repository can be imported in business central by cloning it. In the Administration perspective, click on the Repositories menu and then click on Clone Repository menu to start the process.

Note

Assets can also be migrated manually. After all, they are all just text files. The BPMN2 specification and the DRL syntax did not change between the different versions.

Importing the repository in JBDS

To import the repository in JBoss Developer Studio, do the following
  1. Start JBoss Developer Studio.
  2. Start the Red Hat JBoss BPM Suite server (if not already running) by selecting the server from the server tab and click the start icon.
  3. Select File → Import... and navigate to the Git folder. Open the Git folder to select Projects from Git and click next.
  4. Select the repository source as Existing local repository and click next.
  5. Select the repository that is to be configured from the list of available repositories.
  6. Import the project as a general project in the next window and click next. Name this project and click Finish.

2.2.2. Runtime Migration

To run Red Hat JBoss BPM Suite 5 processes in Red Hat JBoss BPM Suite 6, do the following:
  1. Set the system property jbpm.v5.id.strategy to true in the JBoss BPM Suite standalone.xml file: 
    <property name="jbpm.v5.id.strategy" value="true"/>
  2. Load the KieSession as shown here: 
    KieSession ksession = JPAKnowledgeService.loadStatefulKnowledgeSession(sessionID, kbase, sessionConf, env);
  3. Continue the normal execution of the process using KieSession methods: 
    ksession.signalEvent("SomeEvent", null);

2.2.3. API and Backwards Compatibility

Migrating to Version 6.1 and later

In version 6.1, 5.x APIs are no longer officially supported.
Red Hat JBoss BPM Suite no longer provides backward compatibility with the rule, event, and process application programming interface (API) from JBoss BRMS 5. The content of the knowledge-api JAR file is no longer supported in version 6.1 and onward, and is replaced by APIs contained in the kie-api JAR file that were introduced in JBoss BPM Suite 6.0.
If you used the legacy 5.x API (located in knowledge-api.jar), please migrate (rewrite) the API calls to the new KIE API. Please be aware that several other APIs have changed between JBoss BRMS 5.x and JBoss BPM Suite 6.x, namely the task service API and the REST API.

Migrating to Version 6.0

The JBoss BPM Suite 6 system provides backward compatibility with the rule, event and process interactions from JBoss BRMS 5. You should eventually migrate (rewrite) these interactions to the all new revamped core API because this backward compatibility is likely to be deprecated.
If you cannot migrate your code to use the new API, then you can use the API provided by the purpose built knowledge-api jar for backwards compatible code. This API is the public interface for working with JBoss BPM Suite and JBoss BRMS and is backwards compatible.
If you are instead using the REST API in JBoss BPM Suite 5, note that this has changed as well and there is no mechanism in it for backwards compatibility.