Migration Guide
Migrating from earlier versions to Red Hat JBoss BPM Suite 6.2
Abstract
Chapter 1. Why Migrate?
- A higher performance rule engine based on the Drools 6 community project.
- Improved rule authoring tools and an enhanced, integrated user interface.
- A common defined methodology for building and deployment using Maven as the basis for repository management.
- A heuristic planning engine based on the OptaPlanner community project.
- Use of the PHREAK algorithm to handle a larger number of rules and facts.
- New Data Modeler that replaces the declarative Fact Model Editor
- And many more stability, usability and functional improvements.
Chapter 2. Migrating from JBoss Enterprise BRMS Platform 5.3.1 to Red Hat JBoss BPM Suite 6.x
2.1. What has changed?
Naming Changes
Component Name Migration
API Name Changes
Table 2.1.
| 5.x API (deprecated in 6.x) | Replaced in 6.x by |
|---|---|
| org.drools.KnowledgeBase | org.kie.api.KieBase |
| org.drools.runtime.StatefulKnowledgeSession | org.kie.api.runtime.KieSession |
| org.drools.runtime.StatelessKnowledgeSession | org.kie.api.runtime.KieSession |
| org.drools.builder.KnowledgeBuilderFactory | org.kie.internal.builder.KnowledgeBuilderFactory |
| org.drools.io.ResourceFactory | org.kie.internal.io.ResourceFactory |
| org.drools.io.ResourceType | org.kie.internal.io.ResourceType |
| org.drools.runtime.Environment | org.kie.api.runtime.Environment |
| org.drools.runtime.EnvironmentName | org.kie.api.runtime.EnvironmentName |
| org.drools.runtime.KnowledgeSessionConfiguration | org.kie.api.runtime.KieSessionConfiguration |
| org.drools.event.AgendaEventListener | org.kie.api.event.rule.AgendaEventListener |
| org.drools.event.rule.AgendaEventListener | org.kie.api.event.rule.AgendaEventListener |
| org.drools.event.DefaultAgendaEventListener | org.kie.drools.core.event.DefaultAgendaEventListener |
| org.drools.event.rule.DefaultAgendaEventListener | org.kie.api.event.rule.DefaultAgendaEventListener |
| org.drools.event.process.ProcessEventListener | org.kie.api.event.process.ProcessEventListener |
| org.drools.event.process.DefaultProcessEventListener | org.kie.api.event.process.DefaultProcessEventListener |
| org.drools.logger.KnowledgeRuntimeLogger | org.kie.api.logger.KieRuntimeLogger |
| org.drools.logger.KnowledgeRuntimeLoggerFactory | org.kie.api.logger.KieLoggers |
Repository Change
Changes to the REST API
http://SERVER_ADDRESS:PORT/jboss-brms/rest/ to http://SERVER_ADDRESS:PORT/business-central/rest/
Migrating Task Service
LocalHTWorkItemHandler located in org.jbpm.services.task.wih.
Logging factory
KieLoggers that can be used to create instances of the KieRuntimeLogger.
2.2. How-To Migrate
- Migrate the data first: These are your business assets.
- Next, migrate your runtime processes.
- Finally, convert old API calls to new ones one by one.
2.2.1. Data Migration
- 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.
- 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 theexport-from-JCRpart of the migration.vfs-importer-libs- contains the libs specific to theimport-into-Gitpart of the migration.conf- contains global migration tool configuration.
- For production databases, copy the JDBC driver for the database that is used by the JCR repository into the
jcr-exporter-libsdirectory of the migration tool. - Execute the following command:
./bin/runMigration.sh -i <source-path> -o <destination-path> -r <repository-name>
- <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.
-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
Note
Importing the repository in JBDS
- Start JBoss Developer Studio.
- 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.
- Select → and navigate to the Git folder. Open the Git folder to select and click next.
- Select the repository source as and click next.
- Select the repository that is to be configured from the list of available repositories.
- 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
- Set the system property
jbpm.v5.id.strategyto true in the JBoss BPM Suitestandalone.xmlfile:<property name="jbpm.v5.id.strategy" value="true"/>
- Load the KieSession as shown here:
KieSession ksession = JPAKnowledgeService.loadStatefulKnowledgeSession(sessionID, kbase, sessionConf, env);
- 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
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.
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
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.
2.3. Advanced Migration
2.3.1. REST API Migration
REST API Example
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpMethod;
import org.apache.commons.httpclient.NameValuePair;
import org.apache.commons.httpclient.methods.GetMethod;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;
import org.jboss.bpm.console.client.model.ProcessDefinitionRef;
import org.jboss.bpm.console.client.model.ProcessDefinitionRefWrapper;
import org.jboss.bpm.console.client.model.ProcessInstanceRef;
public class RestClientStartWithParam {
private static final String BASE_URL = "http://localhost:8080/business-central-server/rs/";
private static final String AUTH_URL = BASE_URL + "identity/secure/j_security_check";
private final String username;
private final String password;
private static final String PROCESS_ID = "defaultPackage.hello";
public RestClientStartWithParam(final String u, final String p) {
this.username = u;
this.password = p;
}
public static void main(String[] args) throws Exception {
RestClientStartWithParam client = new RestClientStartWithParam("admin", "admin");
// get process definitions
ProcessDefinitionRefWrapper processDefinitionWrapper = client.getProcessDefinitions(client);
// pick up "com.sample.bpmn.hello"
ProcessDefinitionRef definitionRef = null;
for (ProcessDefinitionRef processDefinitionRef : processDefinitionWrapper.getDefinitions()) {
if (processDefinitionRef.getId().equals(PROCESS_ID)) {
definitionRef = processDefinitionRef;
break;
}
}
if (definitionRef == null) {
System.out.println(PROCESS_ID + " doesn't exist");
return;
}
// start a process instance with parameters
Map<String, String> params = new HashMap<String, String>();
params.put("employee", "thomas");
params.put("reason", "theReason");
client.startProcessWithParameters(client, definitionRef, params);
}
private void startProcessWithParameters(RestClientStartWithParam client, ProcessDefinitionRef def,
Map<String, String> params) throws Exception {
String newInstanceUrl = BASE_URL + "form/process/" + def.getId() + "/complete";
String dataFromService = client.getDataFromService(newInstanceUrl, "POST", params, true);
System.out.println(dataFromService);
}
// get DataFromService method can be implemented like this
private String getDataFromService(String urlpath, String method, Map<String, String> params, boolean multipart)
throws Exception {
HttpClient httpclient = new HttpClient();
HttpMethod theMethod = null;
StringBuffer sb = new StringBuffer();
if ("GET".equalsIgnoreCase(method)) {
theMethod = new GetMethod(urlpath);
} else if ("POST".equalsIgnoreCase(method)) {
theMethod = new PostMethod(urlpath);
if (params != null) {
if (multipart) {
List<Part> parts = new ArrayList<Part>();
for (String key : params.keySet()) {
StringPart stringPart = new StringPart(key, params.get(key));
stringPart.setCharSet("UTF-8");
parts.add(stringPart);
}
((PostMethod) theMethod).setRequestEntity(new MultipartRequestEntity(parts.toArray(new Part[0]),
theMethod.getParams()));
} else {
List<NameValuePair> NameValuePairList = new ArrayList<NameValuePair>();
for (String key : params.keySet()) {
NameValuePairList.add(new NameValuePair(key, params.get(key)));
}
((PostMethod) theMethod).setRequestBody(NameValuePairList.toArray(new NameValuePair[0]));
}
}
}
if (username != null && password != null) {
try {
int result = httpclient.executeMethod(theMethod);
System.out.println("result = " + result);
// System.out.println(theMethod.getResponseBodyAsString());
} catch (IOException e) {
e.printStackTrace();
} finally {
theMethod.releaseConnection();
}
PostMethod authMethod = new PostMethod(AUTH_URL);
NameValuePair[] data = { new NameValuePair("j_username", username),
new NameValuePair("j_password", password) };
authMethod.setRequestBody(data);
try {
int result = httpclient.executeMethod(authMethod);
System.out.println("result = " + result);
// System.out.println(theMethod.getResponseBodyAsString());
} catch (IOException e) {
e.printStackTrace();
} finally {
authMethod.releaseConnection();
}
}
try {
int result = httpclient.executeMethod(theMethod);
System.out.println("result = " + result);
sb.append(theMethod.getResponseBodyAsString());
String rawResult = sb.toString();
return rawResult;
} catch (Exception e) {
throw e;
} finally {
theMethod.releaseConnection();
}
}
Migrate to JBoss BRMS/JBoss BPM Suite 6
import java.net.MalformedURLException;
import java.net.URL;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import org.kie.api.runtime.KieSession;
import org.kie.api.task.TaskService;
import org.kie.api.task.model.TaskSummary;
import org.kie.services.client.api.RemoteRestRuntimeEngineFactory;
import org.kie.services.client.api.command.RemoteRuntimeEngine;
public class Main {
public static void main(String[] args) throws MalformedURLException {
/*
* Set the parameters according to your installation
*/
String APP_URL = "http://localhost:8080/business-central/";
URL url = new URL(APP_URL);
String USER = "anton";
String PASSWORD = "password1!";
RemoteRestRuntimeEngineFactory factory = RemoteRestRuntimeEngineFactory.newBuilder()
.addDeploymentId("org.redhat.gss:remote-test-project:3.0").addUrl(url).addUserName(USER)
.addPassword(PASSWORD).build();
RemoteRuntimeEngine engine = factory.newRuntimeEngine();
KieSession kSession = engine.getKieSession();
TaskService taskService = engine.getTaskService();
// start a process instance with parameters
Map<String, Object> params = new HashMap<String, Object>();
params.put("employee", "thomas");
params.put("reason", "theReason");
kSession.startProcess("com.sample", params);
taskService.claim(taskSummaryList.get(0).getId(), "anton");
taskService.start(taskSummaryList.get(0).getId(), "anton");
taskService.complete(taskSummaryList.get(0).getId(), "anton", null); // not passing any data = null
}
}RemoteRuntimeEngine gives us direct access to the TaskService / KieSession and AuditLogService API.
Note
2.3.2. KnowledgeAgent to KieScanner Migration
KnowledgeAgent and then you try to obtain the KnowledgeBase from the agent, you will be able to receive the latest version of the KnowledgeBase including updated resources - whether it is a freshly built package (*.PKG) in Business Central or BPMN process definition updated via the Eclipse designer tool.
KieBase (instead of KnowledgeBase) dynamically as it gets updated. However, the migration is not so straightforward, because of a few things:
- In JBoss BRMS 5, the native storage for packages was Guvnor - which used JackRabbit repository underneath. You could also point to a single resource (drl, bpmn..) with any valid URL (i.e. file://, http://, ...).
- The API is completely different as there is no direct mapping between KnowledgeAgent API in JBoss BRMS/JBoss BPM Suite 6.
KnowledgeAgent in BRMS 6 is called KieScanner and therefore you need to include kie-ci library on classspath if you want to use it.
*.PKG files or specific business resources such as drl, bpmn. Instead you configure your KieScanner with a specific KJAR, which is a Maven artifact including your resources, identified by GAV. KieScanner uses the Maven Repository to figure out where to look for these built KJARs. If not specified otherwise, it will look into your local Maven repository (by default stored under ~/.m2/ directory on your filesystem).
KieScanner is now bound to this project, and once you make changes to this project in Business Central and build the project, it's latest build will be stored into the local Maven repository (this is the default). KieScanner scans the local Maven repository and picks up the changes. If you want to configure KieScanner in a way that it scans other repositories besides your local one you can do so by setting a system property: kie.maven.settings.custom which can point to the custom settings.xml (a standard Maven configuration file where you include all repositories which should be taken into consideration).
KieScanner invokes Maven under the hood for artifact lookup by following known Maven conventions and rules. For example:
- If the remote repository requires authentication, you need to configure this authentication in a Maven way by updating
settings.xml. - If you point your
KieScannerto a KJar with GAVorg.my:project:1.0your KieBase will never get updated even if you build the project with the same GAV again. This is because Maven will resolve the artifact to a fixed version. - If you point your
KieScannerto a KJar with GAVorg.my:project:1.0-SNAPSHOTyour KieBase will get updated for any new build of the project with that GAV - it will be resolved to the LATEST build of that GAV, identified by the timestamp.
2.3.3. Database Migration
Include hbm.xml for PostgreSQL
If the underlying database on which the migration is being performed is PostgreSQL, you will need to include an additional configuration file, calledhbm.xmlinside theMETA-INFdirectory, next topersistence.xml, with the following contents:<?xml version="1.0"?> <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD 3.0//EN" "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> <hibernate-mapping> <typedef name="materialized_clob" class="org.hibernate.type.TextType" /> </hibernate-mapping>This file instructs Hibernate to useTextTypefor materialized CLOBS and solves an issue where Hibernate incorrectly tries to interpret the type of a parameter as Long when it should be String based.Avoid ID constraint violations in PostgresSQL and Oracle
NodeInstanceLogin BRMS 5.2.x doesn't have a sequence generator associated with it and was added to have more consistent behavior with multiple databases. Since not all databases initialize the id sequence correctly on migration it is necessary to update the NODE_INST_LOG_ID_SEQ id manually. The two databases that are affected are: PostgreSQL and Oracle.- PostgreSQL: In PostgreSQL two actions are required:
- Find the
idwith the biggest value in theNodeInstanceLogtable:SELECT MAX(id) FROM nodeinstancelog;
- Restart sequence NODE_INST_LOG_ID_SEQ using the result from the previous step, increased by 1. So if the command in the previous step returned the number
10you will use11in the following command.ALTER SEQUENCE node_inst_log_id_seq RESTART WITH 11;
The reason to increase the result from the first step by1is that restarting the sequence sets the is_called flag tofalse, which tells the system that the sequence was not yet used.
- Oracle: In Oracle, the following steps are required:
- Find the
idwith the biggest value in theNodeInstanceLogtable:SELECT MAX(id) FROM nodeinstancelog;
- Execute the following commands in SQL:
-- Re-create the sequence by first dropping it and then creating a new one. DROP SEQUENCE NODE_INST_LOG_ID_SEQ; CREATE SEQUENCE NODE_INST_LOG_ID_SEQ START WITH 11 INCREMENT BY 1 NOCYCLE; -- Increase the sequence (the result must be greater then the result obtained in step 1) ALTER SEQUENCE NODE_INST_LOG_ID_SEQ INCREMENT BY 100;
Chapter 3. Migrating from Red Hat JBoss BPM Suite 6.x to a later version
3.1. Migrating from 6.1.x to 6.2
3.1.1. Migrating Client Application APIs from 6.1.x to 6.2
jBPM Executor (embedded mode)
jbpm-executor service was in use previously, with embedded environments, it is recommended to now create the jBPM Executor using the API.
Deprecated methods
TaskSummary.getPotentialOwners() is now deprecated and slated for removal.
Update IDs from primitive types
long to the Object Long. While Java can perform auto-casting of these primitive types it is recommended to update any uses of the following methods to avoid potential issues:
org.kie.api.task.model.Content.getId(); org.kie.api.task.model.TaskData.getOutputContentId(); org.kie.api.task.TaskService.addComment();
3.1.2. Migrating Business Central Project, Repository, and Artifacts from 6.1.x to 6.2
.niogit folder) and maven local dependencies (bin/repositories is to copy over these directories to the new installation. This process will copy over all projects and artifacts.
Procedure 3.1. Migrate the Git Repository
- Turn off JBoss BPM Suite 6.1.x and 6.2 instances.
- Navigate to the
.niogitdirectory, found in the home directory of the JBoss BPM Suite 6.1 installation. - Copy this directory, and any subdirectories, to the
.niogitdirectory of the JBoss BPM Suite 6.2 installation:cp -R ./ $BPM_6.2_INSTALLATION/.niogit/
Procedure 3.2. Migrate the Maven Repository
- Turn off JBoss BPM Suite 6.1.x and 6.2 instances.
- Navigate to the
repositoriesdirectory, found in the home directory of the JBoss BPM Suite 6.1 installation. - Copy this directory, and any subdirectories, to the
repositoriesdirectory of the JBoss BPM Suite 6.2 installation:cp -R ./ $BPM_6.2_INSTALLATION/repositories/
3.1.3. Upgrading the Database from 6.1.x to 6.2
3.2. Migrating from 6.0.x to 6.1
3.2.1. Migrating Client Application APIs from 6.0.x to 6.1
Important
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
Modify Your (Custom) persistence.xml
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
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
old --> new kie-services-jaxb --> kie-remote-jaxb kie-services-client --> kie-remote-client kie-services-remote --> kie-remote-services
Review JMS Port Changes
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.
ConnectionFactory. This factory provided JMS queues and no other port setting was necessary.
Verify Location of Deployment Units
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
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();
remoteRuntimeEngine = RemoteRestRuntimeEngineFactory.newBuilder().addUrl(url).addUserName(username).addPassword(password).addDeploymentId(deploymentId).addExtraJaxbClasses(classes).build();
// 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();
remoteRuntimeEngine = remoteRuntimeEngineFactory.newRestBuilder().addUrl(url).addUserName(username).addPassword(password).addDeploymentId(deploymentId).addExtraJaxbClasses(classes).build();
Rename the AuditLogService Class
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
.niogit folder) and maven local dependencies (bin/repositories) to a new JBoss BPM Suite 6.1 installation.
Procedure 3.3. Migrate a Single Project
- Turn off JBoss BPM Suite 6.0.x and JBoss BPM Suite 6.1 instances.
- Navigate to
.niogitfolder 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
niogitfolder. - 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 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 → → → .
- Fill in the form. For example:
Repository Name - MyOld603Repo Organizational Unit - example Git URL - file:///path/to/old/603/.niogit/repository.git
and press . - The repository should be now available for Authoring.
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.
Procedure 3.5. Migrating Maven Artifacts using the GUI
- Turn on JBoss BPM Suite 6.1.
- Navigate to → .
- Upload the Artifact from your old 6.0.3 installation.
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--parentsargument 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/TimerProjectpath.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
.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
3.3. Migrating from 6.0.x to 6.2
3.3.1. Migrating Client Application APIs from 6.0.x to 6.2
3.3.2. Migrating Business Central Project, Repository, and Artifacts from 6.0.x to 6.2
.niogit folder) and maven local dependencies (bin/repositories) to a new JBoss BPM Suite 6.2 installation.
Procedure 3.7. Migrate a Single Project
- Turn off JBoss BPM Suite 6.0.x and JBoss BPM Suite 6.2 instances.
- Navigate to
.niogitfolder 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.2.0
niogitfolder. - Clone the repository where you want to migrate the 6.0.x project.
$ git clone repository620.git
- Copy the project from 6.0.x cloned repository to 6.2.x cloned repository.
$ cp -R /path/to/6.0.3/project /path/to/6.2.0/repository
- Navigate to the 6.2.0 cloned repository.
$ cd /path/to/6.2.0/repository
- Commit the newly added 6.0.x project to your new 6.2.0 repository.
$ git add ./copied-6.0.3-project/* $ git commit -m "migrating 6.0.3 project to 6.2.0 repository" $ git push
- Start JBoss BPM Suite 6.2.0. The 6.0.3 project should be successfully migrated and visible under the specified repository.
Note
The following procedure demonstrates how to migrate a selected JBoss BPM Suite 6.0.x repository to JBoss BPM Suite 6.2.0 installation.
Procedure 3.8. Clone and Migrate a Repository
- Turn on JBoss BPM Suite 6.2.0.
- Log in to Business Central and navigate to → → → .
- Fill in the form. For example:
Repository Name - MyOld603Repo Organizational Unit - example Git URL - file:///path/to/old/603/.niogit/repository.git
and press . - The repository should be now available for Authoring.
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.2.0 installation, with the folder name repositories/kie.
Procedure 3.9. Migrating Maven Artifacts using the GUI
- Turn on JBoss BPM Suite 6.2.
- Navigate to → .
- Upload the Artifact from your old 6.0.3 installation.
Procedure 3.10. Migrating a Particular Artifact
- Consider following KJAR, which was installed into JBoss BPM Suite 6.0.x Artifact Repository by Business Central.

Figure 3.4. Installed KJAR
- Copy this artifact to the JBoss BPM Suite 6.2.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--parentsargument will ensure that all the necessary folders (if missing) will be created in 6.2.0 too. In this case, it will honor the/org/redhat/gss/TimerProjectpath. - Start the JBoss BPM Suite 6.2.0 installation and navigate to Artifact Repository. The copied artifact should be present as shown.

Figure 3.5. Artifact Repository
.niogit Folder
In order to migrate the whole .niogit from 6.0.x to 6.2.0, set the org.uberfire.nio.git.dir property in 6.2.0 as follows.
$ ./standalone.sh -Dorg.uberfire.nio.git.dir=/path/to/6.0.3/.niogit
3.3.3. Upgrading the Database from 6.0.x to 6.2
3.4. Database Migration for 6.x Instances
Important
- Download the
Red Hat JBoss BPM Suite Supplementary Toolsfrom the Customer Portal. - Shutdown any Red Hat JBoss BPM Suite servers communicating with the database.
- Navigate to the subdirectory corresponding to the type of database used. For instance, if a h2 database is in use (the default), then the scripts in the
h2directory will be used in the subsequent steps. - Examine the contents of each script to be executed. While many of the scripts contain only database changes, there are others that require commands to be executed from a client with an open connection to the database.
- Execute the scripts, in order, corresponding to the following table.
Table 3.1. Database Scripts by Version
Original JBoss BPM Suite Version New JBoss BPM Suite Version Script(s) to execute 6.0 6.2 bpmsuite-6.0-to-6.1.sql,
bpmsuite-6.1-to-6.2.sql6.1 6.2 bpmsuite-6.1-to-6.2.sql6.0 6.1 bpmsuite-6.0-to-6.1.sql - Start the new JBoss BPM Suite server.
3.5. Migrating Running Processes
- Shutdown any active BPM Suite servers using the older version.
Important
When the server is shutdown all processes will be terminated, and only the processes that have been persisted to the database will migrate smoothly. Before shutting down the BPM Suite server ensure that all rules are either waiting on a human task, so that they will be persisted, or not actively executing. - Ensure the instructions in Section 3.4, “Database Migration for 6.x Instances” have been followed to upgrade the database to the new version.
- Start the new BPM Suite server, pointing to the same database that was previously in use.
- Before executing any processes on the new server follow the instructions for copying the maven and git repositories that pertain to the migration. These are discussed in Section 3.1.2, “Migrating Business Central Project, Repository, and Artifacts from 6.1.x to 6.2” and Section 3.2.2, “Migrating Business Central Project, Repository and Artifacts from 6.0.x to 6.1”.
- At this point the processes will be retrieved from the backing database and may be used as normal.
Note
Chapter 4. Migration Examples
4.1. Hello World Project Migration
Data Migration
START->SCRIPT_Task->Human_Task->End.

$ ./runMigration.sh -i /home/osiris/jboss-playground/jboss-eap-6.0-brms/bin/repository -o /home/osiris/Downloads/myGitRepo -r MyMigratedRepo
bin directory, using ./standalone.sh, so by default, the repository directory and repository.xml will be created in this directory.
-o option) can be whatever dir you want it to be. The GIT repository is created under myGitRepo folder once the migration tool finishes its work.
Note
file:///home/osiris/Downloads/myGitRepo/MyMigratedRepo.git to start the import.

4.2. Cool Store Project Migration
- Navigate to
binfolder 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. - Start the server using
./standalone.shcommand. On JBoss EAP 5, start the server by executing therun.shscript. - 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.
- 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
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:

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
- JBoss BRMS 5 uses the JackRabbit repository for storage of its business assets. Its location is specified via the -i parameter.
- 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
- Name of the git repository is specified via the -r parameter.
- Make sure that the destination folder
MigrateRepositorydoesn't already exist.
$ pwd /home/osiris/jboss-playground/jboss-eap-6.0-brms/bin $ tree | grep repository |-- repository | |-- repository | |-- repository.xml |-- repository.xml
/bin/repository/repository.xml file has been placed there manually - it is a copy of /bin/repository.xml file.
/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


Note
Include JAR as a dependency
Fixing syntax issues
Declare Events DRL. Looks like this rule has a syntax issue that needs fixing.

Note
Migrating Selected Assets Manually
- Create a new GIT repository in Business Central.
- 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 to import process definition from JBoss BRMS 5.
Appendix A. Revision History
| Revision History | |||
|---|---|---|---|
| Revision 6.2.0-4 | Thu Apr 28 2016 | ||
| |||
| Revision 6.2.0-3 | Tue Mar 29 2016 | ||
| |||
| Revision 6.2.0-2 | Mon Nov 30 2015 | ||
| |||
| Revision 6.2.0-1 | Mon Nov 20 2015 | ||
| |||
