Chapter 5. Migration Examples

Let us start with the simplest migration example, a simple Hello World kind of process. This is just to get you started and make you comfortable with the migration process.

Data Migration

Start Red Hat JBoss RMS 5 with a clean repository and install the built-in samples. To make it more interesting, add one BPMN process with following structure:

START->SCRIPT_Task->Human_Task->End

Save the process and build the package. This is what it looks like in Red Hat JBoss RMS 5:

As discussed earlier, in order to automatically migrate assets from Red Hat JBoss RMS 5 to Red Hat JBoss BPM Suite 6, you need to convert the JCR repository, storage for business assets in 5, to a GIT repository—​storage for business assets in 6. Run the migration tool:

$ ./runMigration.sh -i /home/osiris/jboss-playground/jboss-eap-6.0-brms/bin/repository -o /home/osiris/Downloads/myGitRepo -r MyMigratedRepo

This example assumes that the Red Hat JBoss RMS 5 instance was started from the bin directory, using ./standalone.sh, so by default, the repository directory and repository.xml will be created in this directory.

The destination (specified by the -o option) can be whatever directory you want it to be. The GIT repository is created under myGitRepo folder once the migration tool finishes its work.

Once done, clone this repository into Red Hat JBoss BPM Suite 6.x via Administration Repositories Clone Repository. Point it to file:///home/osiris/Downloads/myGitRepo/MyMigratedRepo.git to start the import.

It is now possible to build and deploy project in Red Hat JBoss BPM Suite 6 and easily instantiate the process. This is what it should look like once successfully imported.

The 'Hello World' scenario is a useful migration demo to get your hands dirty. Let us make it more interesting by trying on a real-life project, such as the Cool Store Demo by Eric Schabell which is a reasonably complex project mimicking an online web shopping cart example.

This project provides both Red Hat JBoss BRMS 5 and Red Hat JBoss BPM Suite 6 repositories.

The Red Hat JBoss RMS 5 repository with included business-assets can be downloaded from the following location: https://github.com/jbossdemocentral/brms-coolstore-demo/tree/v1.0.

Let us migrate this repository to Red Hat JBoss BPM Suite 6 step by step:

// get the repo
$ git clone https://github.com/jbossdemocentral/brms-coolstore-demo.git
$ cd brms-coolstore-demo
// switch to the version 5 quickstart
$ git checkout jdf-quickstart
$ cd support
// this unzips the 5.x repo in an XML format which we will now import
$ unzip repository_export.zip

You now have the 5.x repository of the CoolStore demo in the file repository_export.xml which you can import in Red Hat JBoss RMS 5 via the Administration section of the Guvnor (Business Central in 5.x branch of BRMS). Do this now, and once finished, there will be numerous assets present in the repository. You can view them at http://localhost:8080/jboss-brms/rest/packages/com.redhat.coolstore/. Your Guvnor should look similar to the following figure:

Build the package and the repository using the Guvnor interface and then migrate it using the migration tool.

Run the migration tool like this, from the bin folder of the Red Hat JBoss RMS 5 EAP install:

$ ./runMigration.sh -i /home/osiris/jboss-playground/jboss-eap-6.0-brms/bin/repository -o /home/osiris/Downloads/MigrateRepository -r "MyMigratedRepo"

After running the previous command successfully, your file structure should resemble:

$ pwd
/home/osiris/jboss-playground/jboss-eap-6.0-brms/bin
$ tree | grep repository
|-- repository
|   |-- repository
|   |-- repository.xml
|-- repository.xml

The /bin/repository/repository.xml file has been placed there manually—​it is a copy of /bin/repository.xml file.

The output of this migration command will be the Git repository located here: /home/osiris/Downloads/MigrateRepository/MyMigratedRepo.git This Git repository is fully compatible with Red Hat JBoss BPM Suite 6 and you will import it to Business Central later.

Migrating POJOs

Although the migration tool migrates most assets, it does not migrate POJO model JARs. These have to be migrated manually and your project will not build till this is done due to unresolved dependencies.

Open up your Red Hat JBoss BPM Suite 6 instance, and import the Git repository into it. Once imported, your Business Central window should look like the following:

As you can see, there are unresolved dependencies errors which will prevent this project from being built. We have not imported the JAR with POJO model classes yet. We need to do this manually.

Log back into Red Hat JBoss RMS 5 Guvnor and locate the Fact Model JAR and download it to your local filesystem. You will import this JAR in Red Hat JBoss BPM Suite 6 Business Central.

In Business Central, log into Authoring Artifact Repository. Press Upload and locate the JAR that you downloaded from Red Hat JBoss RMS 5.

Include JAR as a dependency

You now need to place this JAR on the project’s classpath so it will be available for every business asset located within the project. From Tools Project Editor Dependencies, select Add from repository, and then select the freshly downloaded JAR. Press Save and then Build & Deploy.

The unresolved dependencies errors will now go away, but you will have another issue:

Fixing syntax issues

If you look in the Problems section of Business Central, you will notice that the build has not been successful due to an issue with Declare Events DRL. Looks like this rule has a syntax issue that needs fixing.

Although the BPMN2 and the DRL syntax did not change between Red Hat JBoss RMS 5 and Red Hat JBoss BPM Suite 6, what did change was stricter enforcing of syntax rules in version 6 than in version 5. This should normally not be an issue, and the system will always tell you where there is a mistake.

In version 6, you always need to include the basic keywords when defining a rule. Therefore, in the error you saw earlier, the missing keywords are: WHEN, THEN and END. It is easy to fix this!

Make these changes in the rule file and then press the Validate button. Your project should validate successfully, without any errors.

Now let us get back to Tools Project Editor. Press Build & Deploy; the project will build successfully. The migration is successful and all assets are validated and transferred in this process.

Migrating Selected Assets Manually

In some projects, you might not need to migrate the complete repository. The manual approach to transferring assets is fairly simple: