4.2. Cool Store Project Migration

The 'Hello World' scenario is a useful migration demo to get your hands dirty. Let's 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 JBoss BRMS 5 repository with included business-assets can be downloaded from the following location: https://github.com/jbossdemocentral/brms-coolstore-demo/tree/v1.0
Let's migrate this repository to JBoss BPM Suite 6 step by step.
  1. Navigate to bin folder of your BRMS 5 installation - make sure there is no repository folder and no repository.xml file in this folder as we want to start with a clean repository for this example.
  2. Start the server using ./standalone.sh command. On JBoss EAP 5, start the server by executing the run.sh script.
  3. In your browser, navigate to and login to http://localhost:8080/jboss-brms. If this is the first time you are running this, you will be prompted to install the default examples. Select No Thanks to installing these.
  4. To start the migration of the business assets, let's first import the CoolStore repo into BRMS 5. Open a terminal window and execute the following commands: // 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 JBoss BRMS 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 JBoss BRMS 5 EAP install. $ ./runMigration.sh -i /home/osiris/jboss-playground/jboss-eap-6.0-brms/bin/repository -o /home/osiris/Downloads/MigrateRepository -r "MyMigratedRepo"

Note

  1. JBoss BRMS 5 uses the JackRabbit repository for storage of its business assets. Its location is specified via the -i parameter.
  2. JBoss BRMS 6/JBoss BPM Suite 6 uses the GIT repository for the storage of business assets. Its location is specified via the -o parameter
  3. Name of the git repository is specified via the -r parameter.
  4. Make sure that the destination folder MigrateRepository doesn't already exist.
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 JBoss BPM Suite 6 and you will import it to Business Central later.

Migrating POJOs

Although the migration tool migrates most assets, it doesn't migrate POJO model jars. These have to be migrated manually and your project won't build till this is done due to unresolved dependencies.
Open up your 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 haven't imported the JAR with POJO model classes yet. We need to do this manually.
Log back into JBoss BRMS 5 Guvnor and locate the Fact Model JAR and download it to your local filesystem. You will import this JAR in JBoss BPM Suite 6 Business Central.
In Business Central, log into Authoring -> Artifact Repository. Press Upload button and locate the jar that you downloaded from JBoss BRMS 5.

Note

This JAR is not a Maven project, and it is a requirement that all JARs used by Business Central are Maven based. If they are not, you need to provide at least some Maven info in the form of Group, Artifact and Version (GAV). Fill in these values for the uploaded Fact Model JAR (these can be anything you want).

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 download 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 hasn't 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 didn't change between JBoss BRMS 5 and 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.

Note

The Validate button is a great tool when migrating content. With it, you are able to see if an asset can be built, before you actually try to build or deploy a whole project. The interface should tell you the root cause of any issue. More detailed information is also usually displayed in the server.log.
Now let's get back to Tools->Project Editor. Press the 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:
  1. Create a new GIT repository in Business Central.
  2. For DRL, create an empty rule and copy paste the content of the rule from JBoss BRMS 5.
    For BPMN processes, create a new process and use Import from BPMN2 to import process definition from JBoss BRMS 5.