第7章 Migration

Migrating your projects from Red Hat JBoss BRMS 5 to Red Hat JBoss BRMS 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 Red Hat JBoss BRMS 6 uses Git for storing assets, artifacts and code repositories including processes and rules, you should start by creating an empty project in Red Hat JBoss BRMS 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 Red Hat JBoss BRMS 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 us look at these steps in more detail in the next few sections:

7.1. Data Migration

To migrate data from Red Hat JBoss BRMS 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 BRMS Software Downloads section. Click on Red Hat JBoss BRMS 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 → Clone Repository menu to start the process.

注記

Assets can also be migrated manually as 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 BRMS 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.

7.2. API and Backwards Compatibility

Migrating to Version 6.1

In version 6.1, 5.X APIs are no longer officially supported.

Red Hat JBoss BRMS no longer provides backward compatibility with the rule, event, and process application programming interface (API) from Red Hat JBoss BRMS 5. The content of the knowledge-api JAR file is no longer supported in version 6.1 and is replaced by APIs contained in the kie-api JAR file that were introduced in Red Hat JBoss BRMS 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 Red Hat JBoss BRMS 5.x and Red Hat JBoss BRMS 6.x, namely the task service API and the REST API.

Migrating to Version 6.0

The Red Hat JBoss BRMS 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 Red Hat JBoss BRMS 5, note that this has changed as well and there is no mechanism in it for backwards compatibility.