Migrating and upgrading your applications

  1. Migrating from WebSphere Operational Decision Management
  2. How to migrate from WebSphere Decision Server and WebSphere Decision Center
  3. How to migrate from WebSphere Decision Server for z/OS and WebSphere Decision Center for z/OS
  4. Migrating from JRules
  5. Migrating from JRules V7
  6. How to migrate from JRules V7
  7. Migrating the Decision Warehouse database
  8. Migrating the Rule Team Server database
  9. Context for Rule Team Server database migration
  10. Resolving conflicts in the name attribute
  11. Renaming custom priority attributes in the Rule Team Server extension model
  12. Ant tasks for migration
  13. Running the Ant tasks for migration
  14. Databases that require specific privileges to access another schema
  15. Migrating rules using event IRL keywords
  16. Migrating rule projects to include the resource folder
  17. Migrating rules in Russian that use the isBetween operators
  18. Locale inconsistencies between JRules V7.x and V8
  19. Rules containing an invalid grammatical form
  20. Removed platform support
  21. Changes between JRules V7.0 and JRules V7.1
  22. Decision service IDs
  23. DVS launch configurations
  24. API incompatibilities
  25. Migrating from Rules for COBOL V7
  26. Overview of migration
  27. Preparing to migrate a Rules for COBOL project
  28. Migrating a Rules for COBOL project
  29. Migration changes
  30. Migrating from Rules for .NET
  31. Overview: Rule project migration from Rules for .NET 7.1
  32. Installation prerequisites
  33. Running the migration tool
  34. Understanding the migration reports
  35. Importing projects into Rule Designer
  36. Adding the Execution Object Model (XOM)
  37. Fixing remaining issues
  38. Migrating from WebSphere Business Events
  39. Migrating
  40. Terminology changes


Migrating and upgrading your applications

After you have installed V8.0.1 of Operational Decision Manager, you can then migrate your applications from previous versions. These applications can be developed in WebSphere Operational Decision Management, JRules, Rules for .NET, or WebSphere Business Events.

Migrating from WebSphere Operational Decision Management

How to migrate applications developed in Operational Decision Manager V7.5 and V8.0 to the current version.

Migrating from JRules

How to migrate applications developed in JRules V7 and Rules for COBOL V7 to the current version.

Migrating from Rules for .NET

How to migrate rule projects and business object models developed in Rules for .NET V7.1.

Migrating from WebSphere Business Events

How to migrate from WebSphere Business Events V7.0.


Migrating from WebSphere Operational Decision Management

How to migrate applications developed in WebSphere Operational Decision Management to the current version.


How to migrate from WebSphere Decision Server and WebSphere Decision Center

After you have assessed the impact of the new version on your V7.5 or V8.0 applications, you can then refer to the procedure to migrate and upgrade your applications.

The new version introduces one or two significant changes, therefore before you migrate your projects it is important that you assess the impact of these changes on your applications. For more information, see What.s new in Operational Decision Manager V8.0.1.

When you migrate from one release to another, it is important to be aware that each release is a complete installation with new shortcuts and a new distribution structure. Although you can have coexisting versions of Rule Designer and Event Designer on the same machine, having several applications accessing a shared file system cache is error prone. However, keeping an installation of a previous version during your migration can help to ensure that you migrate the most up-to-date version of your projects. You must install the new product files to a new location, and you must configure the new components with a different database from the previous version.

Migration of your applications can be split into the following phases:


Design time migration

Design time refers to your development environment and the time prior to compiling your application. If you have customized your development environment in any way in a previous version, you must reapply them to the new version. Customization of Decision Center for example includes: model extensions, customization using extension mechanisms for permissions, lifecycle management, and any modification to the editors.

About this task

To migrate your development environment, complete the following steps after you have installed V8.0.1:

Procedure

  1. In the version you want to migrate, synchronize Rule Designer and Event Designer with Decision Center to verify the rule projects are the most current in your enterprise. Synchronize between the repositories and all the users.
  2. Import your existing projects into a new workspace created by the new version.
  3. Perform a Clean > Build All operation after you import the project.
  4. Review the warnings in the projects and fix them.
  5. Archive the previous Decision Center database if you do not require history data to be preserved and want to configure the new installation by only deploying projects.
  6. Redeploy the provided archive files for the application server you use for Decision Center.
  7. To preserve the history of your previous repository configure the new Decision Center console to connect to the repository used by V7.5. If you do not want to preserve the history, publish the migrated projects in Rule Designer and Event Designer to a new Decision Center repository.


QA time migration

Quality assurance (QA) refers to the systematic activities implemented in your system so that quality requirements for your product are fulfilled.

About this task

To migrate your QA environment, complete this task after you have installed V8.0.1 and migrated your development environment. See also Migrating artifacts and assets (QA time and run time).

Procedure

  1. Redeploy the provided archive files to the application servers you use for testing purposes. This should include a repackaging step for the Scenario Service Provider (SSP) archive if you use Decision Validation Services in Decision Center.
  2. Configure the components on your application server. For more information, see the Configuring topics in each component.
  3. Reapply any customization that you made to the Decision Warehouse. To migrate the Decision Warehouse database, run the <InstallDir>/executionserver/databases/migrate_trace_<database_name>_from_<version>.sql script.

    Where <database_name> is replaced by the target database:

    • db2

    • dbs_os390

    • derby

    • h2

    • hsqldb

    • mysql

    • oracle

    • postgresql

    • sqlserver

    • sybase

    <version> is replaced by the version you are migrating from. The effect of the migration scripts is to make columns TIME_STAMP, LOCATION, RULESET_PROPERTIES and ELAPSED_TIME nullable.


Runtime migration

Run time refers to the time during which your application is running in production, in contrast to other phases of the application lifecycle.

About this task

When you migrate your run time, you have two possible solutions:

Transition with outage

In this case you switch off the previous version, prepare V8.0.1, and then switch on V8.0.1. This case is only possible when you can accept an outage, during which no request or event is processed.

Transition with no outage

For stateless and remote workloads: Start your V8.0.1 run times, load them with your migrated assets and artifacts and then change your infrastructure so that all new queries are directed to the V8.0.1 servers. The queries that are already started keep using the previous version until the operations are complete.

For stateless local workloads: The calling applications must be repackaged with the V8.0.1 code. In this case, both versions of the same application must coexist for a short period of time, and the load balancer must be able to route workloads to both versions. You can progressively shut down all previous instances of the application, until only V8.0.1 applications take over the load.

For stateful workloads: Client applications and event senders cannot be subjected to a process or period of transition inside a given context. Every interaction started with a previous version has to finish with this version. Every new interaction should start with V8.0.1, so that, after a while, all interactions started with previous versions end, and you can shut down these servers.

Note:

The current RuleApp format is fully compatible with previous versions of WebSphere Operational Decision Management. This means that you can perform design time and production runtime migration in parallel. In the run time, you do not have to wait for project migration and redeployment. You can export the content of the Rule Execution Server persistence and upload this to the V8.0.1 persistence. In the meantime, you can build your migrated projects, test them, and then redeploy them. Due to a change in the default value of ruleset.bom.enabled you may see a difference in the runtime behavior between V8.0.0 and V8.0.1. For more information, see What.s new for developers > Ruleset archive property changes.

To migrate your runtime artifacts and assets, complete this task after you have installed V8.0.1 and migrated your development environment. See also Migrating artifacts and assets (QA time and run time).

Procedure

  1. Redeploy the provided archive files for the application server you use in production for Rule Execution Server.
  2. Deploy your rules (RuleApps) and Execution Object Models (XOM)s to the new Rule Execution Server persistence layer.
  3. To migrate your events runtime assets follow the WebSphere Business Events migration steps. For more information, see Migrating from WebSphere Business Events.

Migrating artifacts and assets (QA time and run time)

About this task

To migrate your Operational Decision Manager V8.0.0 artifacts and assets to Operational Decision Manager V8.0.1, complete this task. This task is applicable to both QA time migration and runtime migration.

Procedure

  1. Install Operational Decision Manager V8.0.1.
  2. Migrate your development environment.
  3. Complete the following steps that are relevant to your configuration:

    1. Make copies of your Operational Decision Manager V8.0.0 databases. All data, including application state and history data, is compatible with V8.0.1, and as a result you can copy your databases and all appropriate data to the new release.
    2. Deploy the new Rule Execution Server archive files for your application server.
    3. Deploy your rules (RuleApps) and Execution Object Models (XOMs) to the Operational Decision Manager V8.0.1 Rule Execution Server persistence layer.
    4. Deploy the Operational Decision Manager V8.0.1 event runtime assets to WebSphere Application Server.
    5. Update the appropriate system tables, using the supplied SQL scripts contained in installation_directory/config/scripts/db/upgrade_801. If the database credentials supplied during the installation of Operational Decision Manager V8.0.1 have privileges to modify the database schema, the SQL scripts run automatically when the applications are started. If these credentials are not provided during the installation, ask a database administrator with the required credentials to make the appropriate updates.


How to migrate from WebSphere Decision Server for z/OS and WebSphere Decision Center for z/OS

After assessing the impact of the current version on your legacy applications, create your new working data sets and database tables.

The current version introduces one or two significant changes. Therefore, before you migrate your projects it is important that you assess the impact of these changes on your application.

When you upgrade from one release to another, it is important to be aware that each release is a complete installation with a new distribution structure. Keeping an installation of a previous version during your migration can help to ensure that you migrate the most up-to-date version of your rule projects.

It is likely that you created one or more of the following in Decision Server for z/OS:

Back up these artifacts before you migrate. Migrate your test environments first, then your production environment.

To migrate your applications, complete the following steps for all installations:


Procedure

  1. Back up the <PREVIOUS_VERSION HBRWORKDS>.SHBRPARM(HBRINST) member, work data sets, and work path.
  2. Populate the <8.0.1 HBRWORKDS>.SHBRPARM(HBRINST) member, or a copied version of it, with the values from your previous version configuration.

    Note:

    The HBRINST member from V7.5 for example, is incompatible with V8.0.1. There are many new variables to consider in the new HBRINST member, but copying your previous variable values from your previous version can help.

  3. Run <8.0.1 HBRHLQ>.SHBRJCL(HBRUUPTI) to create the WORKDS data sets.
  4. Back up all of the databases used for the previous configuration. These databases are dependent on your environment, and the configuration of your setup.
  5. Back up any files that you are using in FILE persistence. These files are found in the directory indicated in HBRFILEPATH.


Migrating your Rule Designer environment

About this task

You must update your projects with any updated .jar files. If you are upgrading other products at the same time, such asWebSphere Application Server, you must upgrade the files that you include from these products as well.

Procedure

  1. Follow the steps in Design time migration.
  2. Update the COBOL Execution Object Model or the COBOL Enabled BOM on all COBOL rule projects.


Migrating your zRule Execution Server for z/OS (Decision Server for z/OS)

About this task

If you plan to use the same subsystem ID name for zRule Execution Server for z/OS in the new release, the same PROCLIB member is required. As a result, you can start only one instance at any one time. You must consider your setup when completing the following steps.

Procedure

  1. Create the working data sets and work paths for V8.0.1. The structure of these data sets is different to V7.5 for example, so you must transfer the work path to the new structure (logs, deployment history). The steps are defined in Performing the initial configuration.
  2. Create the databases with the new schemas. The steps are defined in Configuring a DB2 database for your rules runtime persistence layer.
  3. Deploy your rules (RuleApps) and Execution Object Models (XOMs) to the new persistence layer.


Migrating your Rule Execution Server on WebSphere Application Server for z/OS (Decision Server for z/OS)

About this task

To migrate Rule Execution Server artifacts that are running on WebSphere Application Server for z/OS, you must remove any previous version before you install V8.0.1. The following steps guide you through the removal and describes the V8.0.1 configuration process.

Procedure

  1. Create the working data sets and work paths for V8.0.1. The structure of these data sets is different to V7.5 for example, so you must transfer the work path to the new structure (logs, deployment history). The steps are defined in Performing the initial configuration.
  2. Create the databases with the new schemas. The steps are defined in Configuring a DB2 persistence layer.
  3. Uninstall the following archives from WebSphere Application Server for z/OS:

    1. jrules-res-management-WAS8.ear
    2. jrules-res-htds-WAS8.ear
    3. jrules-res-xu-WAS8.rar

  4. In the WebSphere Application Server console, click Resources > JDBC > Data sources > [DataSource name] > Additional Properties > Custom properties to point the data source for Rule Execution Server at the new schema.
  5. Restart WebSphere Application Server.
  6. Set up a new version of Rule Execution Server by completing steps 6 - 10 in Configuring Rule Execution Server on WebSphere Application Server for z/OS with DB2. At step 8, locate the V8.0.1 of jrules-mbean-descriptors.jar.
  7. Verify the configuration as described in Verifying the configuration.
  8. Deploy your rules (RuleApps) and Execution Object Models (XOM)s to the new persistence layer for your business rule projects.


Migrating your CICS configurations

About this task

After you migrate the Rule Execution Server for z/OS instances, you can migrate the CICS configurations using the following instructions:

Procedure

  1. In the CICS system initialization table, change the START parameter to INITIAL and take note of its original value.
  2. Stop your CICS region.
  3. Submit the V8.0.1 version of ++HBRWORKDS++.<HBRSSID_NAME>.SHBRJCL(HBRCSD) job to redefine the resources required by CICS.
  4. Edit the CICS JCL to update the zRule Execution Server for z/OS data sets to the V8.0.1 data sets:

    1. Modify the ++HBRHLQ++.SHBRAUTH library in the STEPLIB concatenation to point to the 8.0.1 version.
    2. Modify the ++HBRHLQ++.SHBRCICS library in the DFHRPL concatenation to point to the 8.0.1 version.
    3. Modify the ++HBRWORKDS++.<HBRSSID_NAME>.SHBRPARM(HBRCICSD) and ++HBRWORKDS++.<HBRSSID_NAME>.SHBRPARM(HBRCMMN) libraries in the HBRENVPR concatenation to point to the 8.0.1 version.
    4. If you are running CICS JVMServer, also modify the ++HBRWORKDS++.<HBRSSID_NAME>.SHBRPARM(HBRCICSJ) library in the HBRENVPR concatenation to point to the 8.0.1 version.
    5. If you are running a single CICS server, modify the ++HBRWORKDS++.<HBRSSID_NAME>.SHBRPARM(HBRCICSZ) library in the HBRENVPR concatenation to point to the 8.0.1version.
    6. You can run the Miniloan sample application to verify your configuration. To do this, modify the ++HBRWORKDS++.<HBRSSID_NAME>.SHBRPARM(HBRSCEN) library in the SCENARIO concatenation to point to the 8.0.1new version.

  5. If you are running a single CICS server, start the zRule Execution Server for z/OS instance and the Rule Execution Server console.
  6. Start the CICS region.
  7. Test the configuration by running the HBRC transaction to connect CICS to zRule Execution Server for z/OS. If CICS succeeds in connecting to the server, message GBRZC9001I is issued. If CICS fails to connect to the server, a GBRZC9000E message is issued with a return code that contains diagnostic information.
  8. In the CICS system initialization table, set the START parameter back to the original value. It is likely that it was set to AUTO.


Migrating your Decision Center for z/OS

About this task

Decision Center for z/OS must be removed from WebSphere Application Server for z/OS and the 8.0.1 version installed in its place. New working data sets, paths, and the database must be created. The following steps guide you through the configuration.

Procedure

  1. Create the working data sets and work paths for V8.0.1. The structure of these data sets is different to V7.5 for example, so the work path must be transferred to the new structure (logs, deployment history). The steps are defined in Performing the initial configuration.
  2. Create the databases with the new schemas. Use the steps defined in Creating the Decision Center DB2 database.
  3. Archive the previous Decision Center for z/OS database if you do not require history data to be preserved and want to configure the new application by only deploying projects.
  4. Uninstall the following archives from WebSphere Application Server for z/OS:

    1. jrules-teamserver-WAS8.ear
    2. jrules-ssp-WAS8.ear if you used Decision Validation Services

  5. In the WebSphere Application Server console, click Resources > JDBC > Data sources > [DataSource name] > Additional Properties > Custom properties to point the data source for Decision Center for z/OS at the new schema.
  6. Restart WebSphere Application Server.
  7. Install the V8.0.1 of Decision Center for z/OS by completing steps 8 and 9 in Configuring the Decision Center consoles on WebSphere Application Server for z/OS with DB2.
  8. If Decision Validation Services is required, install the V8.0.1 by completing step 1 in Configuring Decision Validation Services on WebSphere Application Server for z/OS.
  9. To preserve the history of your previous repository, configure the new Decision Center Enterprise console to connect to the repository used by your previous version. If you do not want to preserve the history, publish the migrated projects in Rule Designer and Event Designer to a new Decision Center repository.


Migrating your event runtime (Decision Server for z/OS)

About this task

To configure the new event runtime on the same WebSphere Application Server for z/OS profile as a previous version, remove the old version first. The following steps guide you through the removal, and points you to the configuration for V8.0.1.

Procedure

  1. In your original configuration directory (<Component Directory>/config), run the following commands:

    1. <Component Directory>/config/was/configure_messaging.sh -undo
      Removes the messaging configuration.
    2. <Component Directory>/config/was/configure_bus.sh -undo
      Removes the bus configuration.
    3. <Component Directory>/config/was/install_app.sh -undo
      Removes the application.
    4. <Component Directory>/config/wbe/update_wbeprops.sh -undo
      Removes the modified events properties.
    5. <Component Directory>/config/was/configure_wbe_datasource.sh -undo
      Removes the data source.
    6. <Component Directory>/config/was/delete_wbe_links.sh
      Deletes the links to the previous events configuration.

  2. Restart WebSphere Application Server for z/OS.
  3. Configure the event runtime as described in Configuring the event runtime on z/OS.


Migrating from JRules

How to migrate applications developed in JRules V7 to the current version. If you plan to migrate from JRules V5.1 and JRules V6 you need to migrate your code and data to JRules V7 before you can migrate to the current version.

Note: Make sure that you use the latest fix pack for the version you are using.


Migrating from JRules V7

Changes from one release to the next can impact business rule application development in a number of ways. These guidelines contain information on how to migrate your applications developed in JRules V7.


How to migrate from JRules V7

After you have assessed the impact of the current version on your JRules V7 business rule applications, you can then refer to the most appropriate use case scenario to migrate your rule projects.

The current version introduces significant changes from JRules V7, so before you migrate your projects it is important that you assess the impact of these changes on your business rule application.

When you migrate from one release to another, it is important to be aware that each release is a complete installation with new shortcuts and a new distribution structure. You do not install a minor release on top of a previously installed version. Although you can have co-existing versions of Rule Designer on the same machine, this could result in class name clashes, and having several applications accessing a shared file system cache is error prone. However, keeping an installation of a previous version of JRules during your migration could help to ensure that you migrate the most up-to-date version of your rule projects.

The simple objective of migration is to take a rule project that runs without errors in JRules V7 and do the following in Rule Designer:

  1. Open the migrated project

  2. Build the migrated project

  3. Run the migrated project, with satisfactory results

Note: If you extended the rule model, to add custom properties for example, you must add the same model extensions to the extension model/data files of the new version. To obtain the new extension files, click File > New > Other > Rule Designer > Rule Model Extension > Extension [Model/Data]. You can then apply the extensions to Decision Center and Rule Solutions for Office if applicable, before you migrate the data.

If you created extensions to Rule Designer then add these plug-ins to the new version, rebuild them, and fix any deprecated warnings or errors. Apply any Decision Center extensions by repackaging the web application and redeploying it.

To migrate from JRules V7, complete the following steps:

  1. In JRules V7, synchronize Rule Designer and Decision Center to verify the rule projects are the most current in your enterprise.

  2. Uninstall the products of the previous version in the reverse order you installed them in.

  3. Install the products of your current version in the order described in the readme file.

  4. Determine which of the following scenarios apply to your enterprise integration and follow the recommendations to migrate.

  5. Use the documentation in the following subsections to find more information, if necessary.

  6. Redeploy the provided enterprise archive (EAR) files and web archive (WAR) files for the application server you use for Decision Center and Rule Execution Server.

You can then open any JRules V7 project in the current version and migrate artifacts in place automatically.

To open your projects and migrate your artifacts do the following:

  1. Import your projects into a new workspace created by the current version.

  2. Perform a Clean > Build All operation after you import the project.


Use case scenarios for migrating rule projects for rule authors

You can run through a number of scenarios to help you position the case that is closest to your own.

Note: The IRL generated for BOM domains was changed in 7.5 to take into account the type of the collection in the BOM. In V7.5, the BOM Integer domain is cast to an Integer in IRL. In V7.1, BOM members with an Integer domain generated a Double type in IRL.

Also additional roles can be added to Decision Center in order to manage permissions. If they still apply, you can add the same roles you had in the previous version to the new EAR application descriptor before deploying it to your application server.

Scenario 1

Rule projects are stored exclusively in Rule Designer. The workspace can be under source code control. These files are controlled and used only by developers.

To migrate rule projects:

  1. Open your V7 rule projects one by one in Rule Designer.

  2. Review the warnings in the rule projects and fix them.

Scenario 2

Rule projects are stored in Rule Designer. The workspace can be under source code control or not. This source of truth is controlled by developers, but Decision Center users regularly take copies of the projects using synchronization.

To migrate rule projects:

  1. Perform a synchronization between the repositories and all the users.

    Synchronizing makes sure that the rule projects are the most current in your enterprise.

  2. Open your JRules V7 rule projects one by one in Rule Designer.

  3. Review the warnings in the rule projects and fix them.

    You can turn off gap and overlap checking in the editors in both Rule Designer and Decision Center.

  4. Delete the Decision Center database.

    You must now migrate the Decision Center repository. Rather than migrate the Decision Center repository, it is cleaner to re-create the schema and republish from Rule Designer.

  5. Publish the migrated rule projects in Rule Designer to a new Decision Center repository.

Scenario 3

The Decision Center repository is the source of truth for the rules.

To migrate rule projects:

  1. Use the Decision Center migration scripts (see Migrating the Rule Team Server database) to migrate the repository to the new format.

  2. Perform a synchronization between the repositories and all the users.

    Synchronization makes sure that the rule projects are the most current in your enterprise.

  3. Open your JRules V7 rule projects one by one in Rule Designer and perform an update.

  4. Review the warnings in the rule projects and fix them.

  5. Publish to Decision Center.

Scenario 4

You use events in your rule projects. The event management feature is deprecated in the current version. This includes IRL keywords related to event management after, before, event, occursin, and timeof, as well as event management related API IlrEvent, IlrContext.nextTime, IlrContext.insertEvent, IlrContext.retractEvent, and so on.

To migrate rule projects that use event management:

  1. Replace the use of events in IRL with the Decision Server Events.

  2. Open your V7.1 rule projects one by one in Rule Designer.

  3. Review the warnings in the rule projects and fix them.


Use case scenarios for migrating execution code

You can run through a number of scenarios to help you position the case that is closest to your own.

Scenario 1

Execution code calling Rule Execution Server in JRules V7. Running this code in the current version generates warning messages about the use of deprecated API.

To migrate your execution code:

  1. Change your execution code that uses any deprecated API to the appropriate replacement.

  2. Repackage and deploy your BRMS-powered applications. This includes building your client code with the new client libraries, and repackaging the application with the up-to-date classes and the new Rule Execution Server libraries.

  3. If you plan to add the managed XOM from a rule project to the database, you need to extend the database to include the XOM repository by running the xomrepository_<DatabaseName>.sql script. The script is located in the <InstallDir>/executionserver/databases directory.

Scenario 2

To use EJB3, you must migrate your code to use the new rule sessions.

To migrate your EJB code from EJB2 to EJB3:

  1. Change your code to use ilog.rules.res.session.IlrStatefulSessionEJB instead of ilog.rules.bres.session.IlrStatefulSession.

  2. Repackage and deploy your BRMS-powered applications.

Scenario 3

If you migrate from JRules V7.0 and you deployed RuleApps directly from Rule Team Server to Rule Execution Server.

To redeploy these RuleApps from Decision Center:

  1. Clean the cache in the console.
  2. Redeploy your rule projects to generate a new compatible package declaration in the RuleApps.


Migrating the Decision Warehouse database

To migrate the Decision Warehouse database, you must create the required database schema and then run an additional SQL script.

To upgrade the database for Decision Warehouse:

  1. Run the <InstallDir>/executionserver/databases/migrate_trace_<database_name>_from_700.sql script.

    Where <database_name> is replaced by the target database:

    • db2

    • dbs_os390

    • derby

    • h2

    • hsqldb

    • mysql

    • oracle

    • postgresql

    • sqlserver

    • sybase

The EXECUTION_ID column of the DECISION_TRACES table now has a UNIQUE constraint, which is a change from the previous database schema.

After running this script, you have a schema that is compliant with V7.1 to V7.5. To complete the migration to the current version, you have to execute the Decision Warehouse database migration script described in How to migrate from Decision Server and Decision Center V7.5.


Migrating the Rule Team Server database

Learn how to migrate the Rule Team Server database.


Context for Rule Team Server database migration

The database schema changed between JRules V7.1 and Decision Center V8.0.1. You must migrate rule projects created before V8.0.1. All versions use the same default data source.

Before you migrate the database, you must:

All versions use the same default data source: jdbc/ilogDataSource. To migrate the database schema, complete the following tasks:

  1. Modify the data source to specify the new database access.

  2. Run the migration Ant task or tasks (see Ant tasks for migration).


Resolving conflicts in the name attribute

Decision Server V7.5 introduced a new unique name constraint that can cause conflicts during the migration.

In the current version, the name attribute must be unique in the vocabulary, and for BOM, and BOM to XOM mapping. This was not the case in versions prior to V7.5.

To avoid errors when running the migration tasks, check the migrated repository to see whether records share names.

You can do this with queries that order records by name, project, and original ID:

Each record should have a unique name. If records share a name, they should be updated.

When records have the same name, Decision Center uses the record with the biggest ORIGINALID.

For example, this BOM table shows records using the name BOMName:

NAME PROJECT ORIGINALID
BOMName 15 125
BOMName 15 148
BOMName 15 213

Decision Center uses ORIGINALID 213, and the other two records must be updated with different names.

You can do this with the following queries:


Renaming custom priority attributes in the Rule Team Server extension model

In the current version, the priority attribute is the IlrRule super class. This hides custom priority attributes from subclasses such as IlrBusinessRule and its subclasses when you migrate your model.

For JRules V7.0, if you defined a custom priority property in IlrBusinessRule or a subclass, using one of the default extensions, for example, you must rename this extended attribute in your custom class before you run the migration tool. For instance, if your default extension model includes: 

<add-property className="BusinessRule">     
	<property extractable="true" name="priority" type="String">         
		<annotation  value="priority_ext"/>     
	</property> 
</add-property>

Change the model before migration to: 

<add-property className="BusinessRule">     
	<property extractable="true" name="myPriority" type="String">         
		<annotation  value="priority_ext"/>     
	</property> 
</add-property>

  1. In JRules V7.0, upload the modified model using Upload Only in the Rule Team Server Installation Manager.

  2. In the current version, use the same model to create the new Decision Center schema.

    The custom priority property on your business rules is stored in a new myPriority custom property. You can copy this property to the current priority property, which is now part of the base rule model.

Note:

Use this task to migrate customized models in V7.0. This task is not pertinent to the migration of V7.1 to 8.0.1.


Ant tasks for migration

Your installation provides Ant tasks to copy the content of the old Rule Team Server database into the new schema, and to grant the required privileges to the database user referenced in the data source.

The following table describes the Ant tasks for migrating the Rule Team Server database.

Table 1. Ant tasks for migration
Ant Task Purpose
gen-migrationXX-script Creates the SQL script used to copy the old database content into the new schema (see Completing the configuration using Ant tasks).
gen-migrationXX-role Creates an SQL script that grants required privileges to the database user referenced in the data source. The role has select permission on all required tables of the old database. You can execute this role task against any database, not just those requiring specific privileges. However, you do not have to use the generated script with all databases.

The XX in the script name represents the version of JRules from which you are migrating. For example, use:

Note:

You do not need to migrate the Rule Team Server database incrementally. Each JRules version provides one Ant task, which migrates your version to the current version. For example, the Ant task gen-migration71-script migrates a Rule Team Server database from V7.1 to V8.0.1.

To verify which Ant task to use, go to the Rule Team Server About page to confirm the version number.

The Ant tasks for migration take the following parameters:

-Dserver.url=<server url>

-DdatasourceName=<new data source name>

-DoldDatabaseSchemaName=<database user used in previous data source>

The Ant tasks produce SQL scripts that you can execute normally using the execute-schema Ant task (see Completing the configuration using the Decision Center console) .

However, the script to create the migration role must have specific privileges. Therefore, it must be run outside of the Rule Team Server Ant tasks by an administrator.

Note:

MySQL does not support database schemas. However, you can achieve the same behavior using a different database for the new Decision Center release. Therefore, with MySQL, you must call Ant tasks using the old database name instead of the old schema name.


Running the Ant tasks for migration

To migrate the database, you must run the migration Ant tasks in a specific order.

To migrate the database, you copy the old Rule Team Server database into the new one.

Depending on the database you use, the new data source user might need specific privileges to access the old Rule Team Server data, see Databases that require specific privileges to access another schema.


Procedure

To migrate the database:

  1. If you are using a database that requires specific privileges to access another schema, run the role Ant task: gen-migrationXX-role, see Ant tasks for migration.

    This task creates an SQL script that grants the required privileges to the database user referenced in the data source. The role has select permission on all required tables of the old database.

  2. Run the migration script: gen-migrationXX-script, see Ant tasks for migration.


Databases that require specific privileges to access another schema

Some databases require special access privileges for migration.

SQL Server and Oracle must have specific privileges to access data in another schema. You must have these privileges for the migration because the process reads the data from the old schema to copy it to the current schema.

For these databases, an administrator must execute the script that creates the required role.

With Oracle, after the role is created and granted to a user, it is automatically available, which means that this user retains the role privileges for any new connection. Consequently, you must restart Rule Team Server after the administrator grants the role to the data source user. If you do not restart, Rule Team Server might use a connection from the application server cache. This old connection does not get the new role privileges, and so the migration script cannot be executed through Rule Team Server.


Migrating rules using event IRL keywords

You can refer to the list of deprecated IRL keywords and API in the current version, and use the suggested replacement.

The following table lists the deprecated IRL keywords as of version 8.0.1. Use Decision Server Events instead.

Deprecated IRL keywords
after
before
event (in rule conditions)
event (in rule actions)
occursin
timeof
timeout
wait
until

The deprecated event-related API is listed on the Deprecated page of the Rule Designer API documentation.

You should refactor the business rules that use the event IRL keywords and integrate this functionality of your application using event rules in Event Designer.


Migrating rule projects to include the resource folder

Rule projects created before the Version 7.5 do not have the resources folder.

When you import a rule project created before Version 7.5, you do not have the resource folder available in the Rule Explorer. To be able to add files to the resource folder and have these files belong to your rule projects, you must add the resource folder manually.

To add the resource folder

  1. Right-click your rule project and select Properties.

  2. Select Rule Project Folders in the Rule Project Properties panel.

  3. Select the Resources folder and create a folder location under your rule project.


Migrating rules in Russian that use the isBetween operators

Some methods in the Russian boot vocabulary have changed since the previous release. The new verbalization is not compatible with rules written in Russian that use these methods. You must change the rules to use the new verbalization.

The verbalization of the following methods has changed between V7.1 and V7.5:

The Russian verbalization has been modified in the boot_ru.voc file. From V7.5 the verbalization is:

After opening your rule project in Rule Designer, change the rules to use one of the new verbalizations.


Locale inconsistencies between JRules V7.x and V8

The locale designation for your rules must be consistent with the locale for existing rules. It must also be consistent with the Decision Center locale, if you publish rules to Decision Center.

In previous versions of JRules, all locales except English are defined by two letters that correspond to the language of the locale, such as fr for French, de for German. English is set to four letters, en_US, which denotes the language and country. In Operational Decision Manager, locales have a four-letter designation. For example, fr_FR sets the language to French and the country to France.

Previous versions of JRules used zh to represent Simplified Chinese. From version 7.1, localized versions of the product provide two designations:

In version 7.1, the Windows Start menu shortcut uses the four-letter designation for the locale.

When you migrate your rule projects into V8.0, verify the locale used to launch Rule Designer is set to the same locale as your rule artifacts. When you write rules in Rule Designer, the locale property of the rule artifact is automatically set to that of the locale in which you are running Eclipse. This means that, if you open an existing 7.0 rule project in Rule Designer and add rules to it in version 8.0, the rule project contains some rules with the two-letter designation, and others with the new, four-letter designation.

Having a combination of short and long locale designations can cause the following issues:

Action Issue
Parsing rules When you write rules in Rule Designer, the rule parser can, in most cases, detect which locale to use. For example, if your locale is fr_FR, the Rule Designer parser interprets both fr and fr_FR as French. Rule Designer does not report an error, but your rule projects nonetheless contain inconsistencies. Inconsistencies can also occur if you create new rule projects that reference rule projects created in earlier versions.
Use languages that have more than one designation When you import a rule project with a locale set to zh, Rule Designer defaults to Simplified Chinese (zh_CN). To use the newly supported locale of Traditional Chinese (zh_TW) launch Rule Designer using that locale, and create a new project.
Publishing to Decision Center When you publish rules to Decision Center, you get an error stating that you cannot publish the rule project because the locales are different. If the locale in any rule artifact is different from the locale of the Decision Center persistence locale, you cannot publish it.

To enable synchronization between Rule Designer and Decision Center, you must verify the locale property in Rule Designer, the locale of your rule artifacts, and the Decision Center persistence locale all match.

How you match locales between Rule Designer and Decision Center depends on your current setup:

If you do not want to change locale each time you migrate, use the four-letter locale for all your new projects and verify the Decision Center persistence locale for this database uses the same four-letter locale.


Rules containing an invalid grammatical form

A fix in V7.5 introduced an incompatibility between V7 and V7.5. Rules containing an invalid grammatical form in some articles can no longer parse. You must therefore change the rules so that they use the correct grammatical form of these articles.

The Italian verbalizer does not compute the following articles properly, causing the rules containing these articles to fail to parse:

In V7.5, the correct grammatical form is used. Rules from V7.0 or V7.1 that contain the incorrect form of the article need to be fixed manually so that they can be parsed.

Note: This incompatibility is very rare, because the articles in question only appear in uncommon constructs.


Removed platform support

The list of supported platforms in this version has changed from previous versions. You must upgrade your application server if you previously deployed modules on one of the removed platforms.

The following platform support has been removed in V8.0.1.


2.1.10. Changes between JRules V7.0 and JRules V7.1

Changes from one release to the next can impact business rule application development in a number of different ways. The following topics contain information on the changes between V7.0 and V7.1, and should be used to help you to migrate your applications.


2.1.10.1. Decision service IDs

A hosted transparent decision service now includes a DecisionID. This change introduces an incompatibility between JRules V7.0 and JRules V7.1. To call a decision service created in V7.1, you must update your client application.

A new element named DecisionID has been added to the decision services WSDL so that you can now identify and retrieve the results of a given ruleset execution. As a consequence of this change, the WSDL format of JRules V7.0 is incompatible with the WSDL response of a decision service created in JRules V7.1. The result and request types of the client created in V7.0 are not the same as the server code created in V7.1.

To ensure a client application that worked with a decision service from JRules V7.0 continues to work with a decision service created from V7.1:

  1. Set the new Compatibility parameter in the web.xml file of the HTDS artifact to 7.0. 
    <context-param>
   <param-name>Compatibility</param-name>
   <param-value>7.0</param-value>
</context-param>

To use the decision service of JRules V7.1:

  1. Set the new Compatibility parameter in the web.xml file of the HTDS artifact to Latest. 
    <context-param>
   <param-name>Compatibility</param-name>
   <param-value>Latest</param-value>
</context-param>

To be able to execute a decision service from V7.1 using an application from a previous release you must regenerate the WSDL and the client proxy associated with this WSDL.

To update the client:

  1. Use the x-client/build/src classes generated by the V7.1 wizard (Client Project for RuleApps > Web Service) instead of the classes generated by the V7.0 wizard.


2.1.10.2. DVS launch configurations

The path to the runner.jar in DVS launch configurations has changed since JRules V7.0.0.

To migrate DVS Archive and DVS Excel File launch configurations from JRules V7.0.0 to JRules V7.1, you must update the class path to the runner.jar file.

To update the path to the runner.jar file:

  1. In Rule Designer, import the DVS Archive or DVS Excel File launch configuration that you created in JRules V7.0.0.

  2. Click Run > Run Configurations.

  3. In the side pane, select the DVS Archive or DVS Excel File launch configuration, and click the Classpath tab on the other side pane.

  4. Select ILOG_BR_STUDIO_HOME/eclipse/plugins/ilog.rules.studio.dvs_7.0.0/lib/runner.jar in the list and then click Remove.

  5. Click User Entries and then click the Advanced button.

  6. Select Add Classpath Variables and then click OK.

  7. Select ILOG_DVS_HOME and then click Extend.

  8. Expand the lib directory, select runner.jar, and then click OK.

    ILOG_DVS_HOME/lib/runner.jar is added to the class path user entries.

To run the updated DVS Archive or DVS Excel File launch configuration:

  1. Click Applyand then click Run.


2.1.10.3. API incompatibilities

Certain changes to the API in JRules V7.1 have introduced compatibility considerations.

The following table lists the JRules BRMS API that has changed between V7.0 and V7.1, and introduces an incompatibility:

Changed API Required action
Removed deprecated constants and constructor for ilog.rules.teamserver.client.IlrRemoteSessionFactory. Use the default constructor of IlrRemoteSessionFactory.
Removed ilog.rules.teamserver.web.beans.ManagerBean.getRuleAppSession. Use ManagerBean.getSession instead.
Changes to the IlrSession object if several sessions are used in the same thread, or if the session is used by several threads. Use beginUsage and endUsage to call the IlrSession object.


Migrating from Rules for COBOL V7

Changes from one release to the next can impact business rule application development in a number of ways. The following information explains how to migrate applications developed in Rules for COBOL V7.


Overview of migration

To use existing Rules for COBOL V 7.1 projects with Decision Server for z/OS, you must first migrate them.

Rule Designer provides a wizard to migrate your Rules for COBOL projects to Decision Server. The migration wizard works with a single project at a time, enabling you to migrate individual projects as needed.

When you migrate a project, the wizard takes the following actions:

  1. Updates attributes, methods, and implementations as required for Decision Server.

  2. In the Follow-up actions pane, identifies any changes that you must make to complete the migration.

For detailed information about changes the migration wizard makes to your Rules for COBOL project, see Migration changes.


Preparing to migrate a Rules for COBOL project

Before you migrate a Rules for COBOL project in Rule Designer, gather information about project hierarchies and dependencies.

You can migrate a project with dependencies only after you migrate the projects on which it depends. For example, suppose you want to migrate a project that accesses a business object module (BOM) in another project. You must migrate the project containing the BOM before you migrate the project that depends on the BOM. In some cases, you might have multiple dependencies, as shown in the following diagram:

To migrate the projects correctly, the migration order must be Project A, Project B, Project C.


Migrating a Rules for COBOL project

Use the migration wizard in Rule Designer to migrate Rules for COBOL projects to Decision Server.


Before you begin

If the project you are about to migrate depends on another Rules for COBOL project that has not yet been migrated, you must migrate that project first. See Preparing to migrate a Rules for COBOL project for more information.


Procedure

To migrate a Rules for COBOL project:

  1. In the Rule Explorer pane in Rule Designer, right-click the Rules for COBOL project you want to migrate.
  2. Select COBOL Generation Project Migration > Migrate Rules for COBOL Project.
  3. In the Rule Project Migration window, choose one of the following options:

    • To continue migrating the project you selected, click Next.

    • To select a different project:

      1. Click Browse

      2. Select a new project from the New project window.

      3. Click OK to close the window.

      4. Click Next.

  4. In the COBOL XOM field of the Configure Migration Settings window:

    1. Enter a name for the COBOL Execution Object Model (XOM).

    2. Press Enter.

    3. Edit any names you want to change.

    4. If your project uses Rules for COBOL domains, specify the following information to generate the domain Java. XOM project:

      • In the Domain model field, enter the name of the BOM model that contains the domain class.

      • In the Domain package field, enter the package name that contains the domain class.

      • In the Domain project field, enter a name for the Java project.

  5. If the COBOL copybook contains a REDEFINES statement, select the data item to be imported as an attribute into the generated XOM. The default data item to be imported is the data item that is redefined.

    • To accept the default data item, click Finish.

    • To select an alternative data item:

      1. Click Next.

      2. In the Configure Redefines window, select the data item to import.

      3. Click Finish.


Results

If the migration is successful, the Rule Explorer pane displays the XOM project.

If any errors occurred in the migration, the Problems pane displays diagnostic messages. If you must take additional actions to complete the migration, the Follow-up actions pane identifies the necessary actions. The follow-up actions are also saved as a Microsoft Excel spreadsheet in the Resources folder.

For more information about the migration changes and follow-up actions, see Migration changes. Also refer to this topic for information about optional migration actions you can take.


Migration changes

The migration wizard completes most migration changes without any action on your part. However, in some cases, attributes or methods have changed or are no longer supported and you must take action to complete the migration.

The following sections describe migration changes for a Rules for COBOL project:


Changes that require no additional action

The following changes are made by the migration wizard, and require no additional action.

numeric types

The following table details the changes to numeric types:

Table 1. Changes to numeric types
Usage in COBOL COBOL Example Java. type mapping in Rules for COBOL Java type mapping in Decision Server
S9(1) through S9(4) pic s9 binary int short
S9(10) through S9(18) PIC 9(10) COMP-3. int long
9(10) through 9(18) usage binary PIC 9999999999 BINARY. int BigInteger
S9(n)v9(n) usage binary PIC S999V9 BINARY. double BigDecimal
usage comp-1 Comp-1 double float

Note:

The business action language (BAL) is unaffected.

For more information, see Designing a BOM for a COBOL model.

Domains

The following table details the changes to domains:

Table 2. Changes to domains
Rules for COBOL implementation Decision Server implementation

  • Provides a dedicated UI for domain creation using Microsoft Excel.

  • Uses a translation property.

  • You must map the copybook item as a Java domain class type.

  • You must predefine the domain class as a Java Execution Object Model (XOM).

  • A new configurable domain feature is supported.

  • The translation property is deprecated.

For more information, see Working with domains and COBOL.

Variable sets

The following table details changes to variable sets:

Table 3. Changes to variable sets
Rules for COBOL implementation Decision Server implementation

For a variable set, uses the initial value column to define both the type mapping and the initial value. For example: 

DataItem.intitem(.pic 9(5)., 12345)
DataItem.shortitem(.pic 9(3)., 12)
DataItem.longitem(.pic 9(11)., 123456)
DataItem.stringitem(.pic x(5)., .C0.)
DataItem.doubleitem(.9v9., 123.456)

Applies the COBOL type setting configuration for the Java to COBOL type mapping.

The initial value column contains only values.

Note:

The migration wizard extracts the initial values during the migration.

For more information, see Variable mapping for COBOL.

COBOL code generation

The following table details the change to the location of configuration data for COBOL code generation:

Table 4. Changes to COBOL code generation
Rules for COBOL implementation Decision Server implementation
Stores configuration data for COBOL code generation in a cobol_extension Business Object Model (BOM). Stores configuration data for COBOL code generation in CobolGenConfig.xml under <RuleProject_Dir>/resources/cobol.

Note:

The cobol_extension BOM is replaced with CobolGenConfig.xml during the migration.

For more information, see Generating a COBOL XOM.

Encoding and code pages

The following table details the change to encoding:

Table 5. Changes to encoding and code pages
Copybook sample Decision Server implementation
Uses the BOM properties. Uses a compile option at the project level.

For more information, see Setting the copybook importer options.


Changes that require you to take additional action

The following sections describe changes that require you to take additional action after running the migration wizard.

Variable length tables

The following changes are made to tables that use Occurs Depending On:

  • odoTable is changed from type Array to type List.

  • odoObject is deleted.

Table 6. Changes to variable length tables
Copybook implementation Rules for COBOL implementation Decision Server implementation 
01 Root.
  05 odoObject pic 9.
  05 odoTable pic x(20) occurs 0 to 10 times depending on odoObject.
 
Root {
   int odoObject;
   String[] odoTable;}
 
Root{
   List<String> odoTable;}

Note:

The business action language (BAL) is unaffected.

Required action: Take either of the following actions to replace the deleted ODO object:

  • Use the size of the Root.odoTable List to represent the Root.odoObject usage in rules.

  • Add a read-only attribute to the BOM to replace the deleted Root.odoObject attribute and implement a B2X mapping for the added attribute using the size of Root.odoTable list.

Note:

  • If you add a read-only attribute to the BOM, you cannot generate COBOL code from the migrated rule project.

  • If you have rules that assign a value to Root.odoObject, you must rewrite these rules to handle the read-only restriction.

For more information, see Table mapping between COBOL and Java.

Redefines

The following table details the change to redefines statements. BOM attributes that you do not select in the migration wizard configuration are deleted.

Table 7. Changes to redefines statements
Copybook implementation Rules for COBOL implementation Decision Server implementation 
01 Root.
  05 redefined-item pic 9.
  05 redefining-item redefines redefined-item pic x.
 
Root{
   int redefined_item;
   String redefining_item;}

You choose one item to import. For example, if you choose redefined-item, the BOM contains: 

Root{
    int redefined_item;}

Required action: Update any rules that use the deleted BOM attributes.

For more information, see REDEFINES statements in the copybook

Level 88 data items

Methods for unsupported Level 88 data items are deleted. Two types of Level 88 data items are not supported:

  • Level 88 literals:

    • ALL ZERO

    • HIGH-VALUE, HIGH-VALUES

    • LOW-VALUE, LOW-VALUES

  • Level 88 group data items. For example: 
    05 Age.
   88 CHILD value 0 thru 17.
   10 Year-Date pic 9(4).
   10 Month-Date pic 9(2).
   10 Day-Date pic 9(2).

Required action: Regenerate the BOM attributes and Level 88 methods for the unsupported Level 88 data items that were deleted:

To regenerate the BOM attributes and the Level 88 methods:

  1. Update the copybook to ensure that it contains only supported uses of Level 88 data items.

  2. Update the COBOL XOM to reflect changes to the copybook.

  3. Update the BOM to reflect the updated Java XOM.

For more information about the implementation of Level 88 data items, see Level 88 data items

Data types

The following table details changes to data types. Data types are not supported. The BOM items that correspond to these data types are deleted during migration.

Table 8. Changes to data types
Copybook sample Rules for COBOL implementation zRule Execution Server for z/OS implementation 
01 Root.
    05 Alphabetic pic A(20).
    05 AlphaNumericEdited pic XBX
    05 NumericEdit pic 9B9.
    05 ExternalFloat pic +99V9E99
Mapped to string. Not supported.

Required action: Regenerate the deleted BOM attributes for the unsupported COBOL data types.

To regenerate the BOM attributes:

  1. Update the copybook to ensure that it uses only supported COBOL data types.

  2. Update the COBOL XOM to reflect the copybook changes.

  3. Update the BOM to reflect the updated Java XOM.

For more information, see COBOL data item mapping to Java structures and Handling data type differences between Java and COBOL.


Optional migration changes you can make manually

The following migration changes are optional because Decision Server for z/OS is compatible with their existing implementations.

COBOL mapped methods

The following table details a change to COBOL mapped methods. You no longer need to use an index value to reference the current element in an array. Instead, you use the {} placeholder.

Copybook implementation Rules for COBOL implementation Decision Server implementation 
01 Root.
    05 CreditCard occurs 5 times.
       10 name pic x(20)
       10 name pic x(20)
       10 ids pic 9(10)
 
CreditCard{
public boolean 
validateCardbyID(int Ids);  }
Mapped method body:
move 'F' to <return> 
IF {ids} = ids of CreditCard of Root(Index1 of <this>)
set BoolValue of <return> to true
END-IF
 
Mapped method body:
move 'F' to <return>
IF {ids}=ids of {this}
set BoolValue of <return> to true
END-IF

If your rule project includes an index placeholder in a COBOL mapped method, choose one of the following options for the rule project:

  • Continue using index placeholders to refer to array elements in the project. This is the default option. It requires no manual action.

  • Enable the use of the new placeholders and update existing placeholders to use {} placeholders. Note that once you enable the use of the new placeholders, you cannot revert to using index placeholders.

To use the new {} placeholders in the rule project, change the default configuration for the migrated project by adding the following statements to its <rule project>/resources/cobol/CobolGenConfig.xml file: 

<CobolGenConfig>
<CompatibleMode compatible="false" />
</CobolGenConfig>

For more information, see Implementing BOM methods for COBOL code generation.


Migrating from Rules for .NET

How to migrate rule projects and business object models developed in Rules for .NET V7.1. Migration from Rules for .NET versions prior to 7.1 require that you migrate to Rules for .NET V7.1 before you can migrate to the current version.


Overview: Rule project migration from Rules for .NET 7.1

To import the rule projects that you created using Rules for .NET V7.1.X into Rule Designer, you must first migrate your rule projects using the Rules for .NET project migration tool.

The Rules for .NET project migration tool converts the core elements of the rule project created in Rules for .NET, such as rule artifacts and BOM definitions. The tool also generates a Java rule project with the correct structure that can be imported into Rule Designer. However, some elements such as the XOM and the value converters cannot be migrated through the tool and must be re-created manually.

Note:

The Rules for .NET project migration tool does not migrate rule projects stored in Rule Team Server for .NET.

The table below lists the elements that can be converted through the migration tool, and those that you must manually convert, update or re-create in Rule Designer after you have imported the migrated project..

Table 1. Rule project migration
Rule projects elements Migrated Not migrated Comments
Project and dependencies

   
BOM (Business Object Model)

   
XOM (Execution Object Model)  

 
Ruleset parameters

  The name of the ruleset parameter is used as the default verbalization.
Rules

  Check the migration of the properties defined.
Decision Tables

  Check the migration of the properties defined.
Ruleflows

  Check the migration of the properties defined.
Basic properties

   
Basic incompatible properties

  Basic incompatible properties are converted into tags.

An extension model file is provided. You must integrate the extension model in Rule Designer.

Custom properties

  Custom properties are converted into tags.

You must create manually the model extensions and then integrate them.

Categories

   
Value converters, value descriptors, and value editors  

If a value converter, value descriptor or value editor was set on a BOM member, the report shows an error message.
Queries  

Queries are not included in the project structure.

To help you identify the elements that must be migrated manually, the tool generates a report that lists all the elements that have not been migrated automatically.

After migrating the rule project and converting all the remaining elements in Rule Designer, you can execute the migrated rule project using the Java rule engine.


Migration workflow

The following figure illustrates the workflow for migrating Rules for .NET rule projects and importing them into Rule Designer.

To migrate your .NET rule projects, perform the following steps:

  1. Run the project migration tool from the command line, and indicate the solution containing the rule projects to migrate. The project migration tool generates the following elements:

    • One or several rule projects containing the migrated artifacts.
    • A HTML report for each migrated rule project, which describes the remaining artifacts to migrate manually and a log of the migration process.

  2. Check the reports to identify the artifacts to convert manually and verify no errors were reported.

  3. Import the migrated rule projects into Rule Designer.

  4. Create a XOM that maps to the classes of the migrated BOM.

  5. Attach the XOM to the rule project.

  6. Optional: Define BOM to XOM mapping.

  7. Create or convert manually the remaining artifacts.

    After migrating all the elements in the rule project, you can execute the rules using the Java rule engine.

  8. Execute the rules using the Java rule engine or Rule Execution Server.

Note:

You can also execute your rules using the Rule engine for .NET.


Installation prerequisites

The project migration tool runs with .NET Framework 4.0.

To run the Rules for .NET project migration tool, you must have the Microsoft .NET Framework 4.0 Redistributable Package installed on your computer.

The migration tool is installed in the following directory: <InstallDir>\dotnet\ruleprojectmigration\. Make sure that it is installed on your local disk drive.

Important:

Before migrating your rule project, you must verify all the rule artifacts in the project are in the same locale.


Running the migration tool

To migrate your .NET rule projects and import them into Rule Designer, you must first use the Rules for .NET project migration tool.

You execute the Rules for .NET project migration tool from the command prompt.

When you run the migration tool, you must enter the path to the Visual Studio solution that contains the rule projects to migrate. The tool converts all the projects with a BOM or rule artifacts contained in the solution. In your output directory, the migration tool creates a Java rule project for the rule artifacts and another one for the Business Object Model (BOM) . The .NET project containing the BOM (<model>.bmx file) is also converted to a Java rule project but it only consists of the BOM entry.

The locale of the tool itself depends on the regional settings of your computer, however when running the tool you must indicate the culture (or locale) of the rules to migrate.

Important:

Before running the migration tool, verify all the rules contained in the rule projects to migrate are in the same locale.

To run the migration tool, you use a command line with specific options such as the path to your Visual Studio solution, and the output directory for the migrated rule projects.

The following table lists the options to use in the command prompt to run the migration tool.

Table 1. Command-line options.
Option Description Status
/? (or /Help) Prints usage information on the available commands. This command does not trigger any execution. Optional
/VSSolution:<filepath> Specifies the path to the Visual Studio solution that contains the rule projects to migrate. Mandatory
/OutputDir:<directoryname> Specifies the path to the output directory where you want the tool to create the new migrated rule projects. Mandatory
/Culture:<xx-XX> Specifies the culture that will be used to generate the vocabulary. The culture (or locale) is composed as follows xx-XX:

  • xx is the language, for example en for English.
  • XX is the country, for example US for United States.

Therefore, en-US is the English language for the United States.

Mandatory
/Aliases:<filepath> Specifies the path to the file that contains the new or overriding class mapping.

To apply a new mapping between the .NET classes and the Java classes, you can create a custom class mapping to override the default mapping. To define a new mapping, you must create a text file in which each line must correspond to a .NET class followed by the Java class that you want to map to. You must separate the .NET and the Java class by a space, as shown in the following example: 

System.Collections.ArrayList java.util.ArrayList

Important:

The new mapping overrides the default one.

Optional
@<MyReponseFile> Indicates the name and path to a response file. The @ parameter precedes the name of the response file on the command line. The command line calls the response file and reads the options specified in the file. Each option is on a separate line.

You can define some options directly in the command line and other options in the response file.

If the @ parameter is directly followed by the name of the response file, the tool searches for the file in the current directory. To search for a response file in another directory, you must also indicate the path of the directory.

Optional
/NoLogo Stops the display of the header in the command prompt. The header contains the name of the tool. Optional


Procedure

To run the migration tool:

  1. Open a command prompt.
  2. cd directory of your Visual Studio solution containing the rule projects to migrate.
  3. Type the path to the rule project migration tool directory, followed by the options to indicate the path to the Visual Studio solution and the output directory: 
    <InstallDir>\dotnet\ruleprojectmigration\RuleProjectMigration /VsSolution:<solution> /OutputDir:<directory> /Culture:<xx-XX>
  4. Press Enter to start the migration process.
  5. Wait until the migration process is complete.


Results

In your output directory, the migration tool creates a new folder for each migrated rule project. Each rule project contains subfolders that reproduce the structure of a Java rule project:

Some folders, such as the queries folder, do not contain any migrated elements. However, after importing your migrated rule project into Rule Designer, you can create queries and store them in this folder.

For each migrated rule project, the migration tool also generates a report of the migration. This HTML report shows a log of the completed migration process as well as a list of the remaining elements that you must convert, or update manually.


Example of command line

In the following example, the Visual Studio solution is RuleApplication.sln and is located in C:\Rules.NET\RuleApplication\. The ouput directory where the migrated project are generated is called C:\Rules.NET\migratedprojects\. The rules to migrate are in American English (en-US). 

C:\IBM\ODM801\dotnet\ruleprojectmigration\RuleProjectMigration /VSSolution:C:\Rules.NET\RuleApplication\RuleApplication.sln /OutputDir:C:\Rules.NET\migratedprojects\ /Culture:en-US

In the next example, you are using a response file containing the options to run the tool: 

C:\IBM\ODM801\dotnet\ruleprojectmigration\RuleProjectMigration /nologo @C:\Rules.NET\MyResponseFile.txt


Understanding the migration reports

The Rules for .NET project migration tool generates reports of the migration process.

After the migration process has completed, a report is generated in the output directory that you specified. This general report lists the projects that were migrated and shows the number of warnings and errors for each project. This report also links to a more specific migration report for each project.

The migration report is a HTML file that is generated in the migrated rule projects along with the converted artifacts. The report is located under the migration report folder of each rule project. You can open it from the file system, or directly in Rule Designer.

The migration report presents the status of the migration process. The report displays the errors and warnings that the migration tool detected.


Summary

The Summary part of the report shows the following elements:


Errors

The Errors section shows the issues that occurred during the migration process. If you see errors in the report, you must fix them in the Rules for .NET rule project, and run the migration tool again.

For example, if you have indicated en-US as the culture (or locale) to use for migration, and the migration tool detects that some artifacts are in the fr-FR locale, then the tool reports an error. You must change the locale of the artifacts that are in fr-FR locale to en-US, and then run the migration tool to check that the errors are fixed.


Warnings

The Warnings section lists potential issues in the migration process, that the tool cannot verify.

For example, some rules in the .NET rule project might not contain the culture or locale information. Therefore, the tool cannot check whether the culture of the rules corresponds to the culture indicated in the migration tool. Use the warnings list to make sure that all the rules have the same culture as the culture indicated in the migration tool.

The report also shows a warning when the Rule Selection property is set on the rule task of a ruleflow, because the tool cannot check if the rule task contains elements that are not compatible with the syntax in Operational Decision Manager V8.0.1.


Rule Artifacts

The Rule Artifacts section shows a list of the migrated rule artifacts. It shows the name of the file that contained the .NET rules, and the corresponding files that the migration tool generated.

For example, in the .NET rule project, a .blx file can contain several rules. In Java, one rule corresponds to one .brl file. If a .blx file contains several rules, the migration tool generates a .brl file for each rule contained in the .blx file.


Business Object Model and Vocabulary

The Business Object Model and Vocabulary section shows the path to the BOM on the file system. It also provides information on the elements of the BOM or the vocabulary that cannot be converted fully. Theses elements are likely to require some manual updates.


Importing projects into Rule Designer

After migrating the rule projects. You can import the migrated projects into Rule Designer.

To explore your migrated rule project and convert the remaining elements, you must import the project into Rule Designer.


Procedure

To import the projects into Rule Designer:

  1. Open Rule Designer.
  2. On the File menu, click Import > General > Existing Projects into Workspace, then click Next.
  3. In the Select root directory field, browse to the folder containing your projects, and select the projects to import.
  4. Optional: Select the Copy projects into workspace check box.
  5. Click Finish. The rule projects are imported into Rule Designer and copied to your workspace. The projects are displayed in the Rule Explorer view. You can expand the rule project to view the project structure and the migrated contents.
  6. Expand the migration report folder, right-click the report.htm file, and click Open With > Web Browser. The migration report opens in Rule Designer.


Results

The Problems view displays a list of errors on the rule project. Some errors indicate a problem with the BOM to XOM mapping, because the Execution Object Model (XOM) has not been defined yet. The Problems view can also display errors related to elements that have not been migrated and that you must manually update or re-create.

You can remove the BOM to XOM checks until you manually write the XOM and reference it in your BOM project. On the Window menu, click Preferences > Rule Designer > Build, and then clear the Perfom BOM to XOM checks during build check box.


What to do next

You can now create your XOM and define a BOM to XOM mapping for the execution of your rules. Check the report to identify what elements need to be converted or created.


Adding the Execution Object Model (XOM)

To execute your rules in Java you need an Execution Object Model (XOM). After creating the XOM, you must attach it the rule project, and associate your BOM entry to the XOM by setting the origin.

During the migration process, the Business Object Model (BOM) is converted. However the .NET class library project on which the initial BOM was based is not converted. Therefore, you must re-write the classes from your .NET class library project, in Java.

The Java project containing the execution classes, is called the Execution Object Model (XOM). The XOM is a model that references implementation objects used in rules. Through the XOM, the rule engine can access application objects and methods. At run time, rules that are written against the BOM are run against the XOM.

The classes in the XOM must map the classes that you have in the migrated BOM. Every BOM element (business element) must have a corresponding XOM element (execution element). The mapping between execution elements and business elements does not need to be one-to-one. When a business element is not attached to an execution element, specify a BOM to XOM mapping.

After creating the Java project for the XOM, you must reference it in the rule project. Then, you link the XOM to the BOM entry.


Procedure

  1. Re-write the classes from your .NET class library project in Java to create an Execution Object Model.
  2. In Rule Designer, import the XOM into your workspace, if it is not already there.
  3. In the Rule Explorer, right-click your rule project and click Properties.
  4. In the Properties dialog, click Java Execution Object Model, select your project, and then click OK.
  5. Click OK.

    Note:

    If you had deactivated the BOM to XOM checks, verify you reactivate the option to perform BOM to XOM checks during build. On the Window menu, click Preferences > Rule Designer > Build, and select the Perform BOM to XOM checks during build check box.


Results

The rule project references your XOM, and the BOM entry origin is now set.


What to do next

You can now define the BOM to XOM mapping for the elements that are not converted or need to be updated.

To synchronize changes between the BOM and the XOM, you can use the BOM update view.


Fixing remaining issues

After creating the XOM and mapping the XOM to the BOM, you must fix the remaining issues.

The migration does not convert all the elements from the .NET rule project. Some elements must be manually converted or created directly in Rule Designer.


Procedure

  1. Open the migration report in Rule Designer.
  2. Look at the errors and warnings displayed in the Problems view.
  3. Fix the remaining problems and create or convert the elements that did not migrate.


Results

The following table shows the elements that are migrated and the issues that remain after the migration process.

Table 1. Result of the migration process.
Artifact Element Context and migration status Solution
Rules and packages Locale (culture) The migration tool converts the rules in the specified locale. If you had rules in different locales in the same rule project, the rule project is not migrated correctly. You must either re-create the rules in the correct locale in Rule Designer, or translate the rules in Rules for .NET and then migrate again the project.
Decision tables Graphical properties Decision tables are migrated, however if you had set graphical properties on your decision tables, these properties are not migrated. You can reset the graphical properties manually in the Decision Table editor in Rule Designer.
Ruleflow Rule Selection You can specify the Rule Selection property in the rule task. This property selects the rules of a ruleset dynamically at runtime.

In a rule task, you can write BAL to select the rules to execute at runtime. The syntax the package of 'the rule' cannot be migrated. Therefore, if you used this syntax in the Rule Selection property of your rule task in .NET, you must correct it in Rule Designer.

To use properties other than the basic compatible properties in the rule selection, you must manually integrate them.

The report generates a warning that indicates the rule task where the Rule Selection property is set. If you have used the syntax the package of 'the rule' in the Rule Selection property, the Problems view shows an error. To fix this error, change the syntax to the package name of 'the rule' in the Rule Selection tab of the Properties view Rule Designer.

To use certain properties in the rule selection, such as basic incompatible properties and custom properties, you must manually integrate them into Rule Designer. For more information, see the section on Properties in this table.

Layout Ruleflows are migrated but layout options are not taken into account. If you had specific layout options on your ruleflows, the ruleflow is restored to the default layout. You can manually reset the layout in the Ruleflow editor in Rule Designer.
Ruleset parameters Verbalization A default verbalization is created for each migrated ruleset parameter. The default verbalization is the name of the ruleset parameter in .NET. You can change the verbalization of the migrated ruleset parameters in the rule project Properties view by selecting the verbalization and clicking Refactor.
Business Object Model (BOM) Mapping A default mapping for the BOM is created, however some custom elements cannot be migrated. Use the BOM to XOM mapping mechanism to map elements that cannot be created in the XOM.
Properties Basic incompatible properties The basic incompatible properties, are migrated as tags in Rule Designer. These properties include:

  • Author
  • Creation Date
  • Last Modification Date
  • Last Modification Author

Integrate the following rule model extension into Rule Designer: <InstallDir>\dotnet\ruleprojectmigration\Data\RulesDotNetSpecificProperties.brmx.

You must define the extension file in Window > Preferences > Rule Designer > Rule Model Extension.

Custom properties These properties are migrated as tags in Rule Designer. You must create an extension model or extension data file to use your custom properties, and then integrate the extension file into Rule Designer.
Value converters, value descriptors, and value editors   The value converters, descriptors, and editors that were defined on a BOM member are not migrated. You must implement them in Rule Designer and then integrate them.


Migrating from WebSphere Business Events

You can migrate from an installed version of WebSphere Business Events V7.0 to Operational Decision Manager.


Migrating from WebSphere Business Events to Operational Decision Manager

Due to the new installer for Operational Decision Manager, you cannot perform an automatic upgrade from previous versions of WebSphere Business Events to the Operational Decision Manager platform. You must perform the upgrade manually. The upgrade steps vary depending on your configuration and the WebSphere Application Server topology.


Before you begin

You must test this procedure in a test environment before migrating to a new installation of Operational Decision Manager. It is important to verify the procedure in your environment before you attempt to migrate production data to a new installation.

WebSphere Business Events projects and all assets related to an Event project are fully compatible with Operational Decision Manager, so you can use assets from an existing WebSphere Business Events asset repository with a Operational Decision Manager design interface or runtime engine. To migrate your assets from an existing WebSphere Business Events repository to a new Operational Decision Manager installation, perform the following steps.


Procedure

  1. Install a new copy of Operational Decision Manager. You can install either on the same machine as the previous installation from which you are migrating, or on a separate machine. You must install the Operational Decision Manager binary product files to a new location.

    Configure the new installation to use a different database from the previous installation. You can make a copy of the existing WebSphere Business Events database to migrate existing history or system state information to Operational Decision Manager. Operational Decision Manager can use an existing WebSphere Business Events repository, but events system tables can only be used by one runtime at a time. Therefore, if you plan to run WebSphere Business Events and Operational Decision Manager events concurrently, you must create a new database for the new installation.

  2. Configure the new runtime and ensure that it works correctly.
  3. Shut down the new installation.
  4. Perform the following tasks during a scheduled maintenance period:

    1. Shut down the previous installation of WebSphere Business Events.
    2. To preserve event contexts and history data, make a copy of the existing WebSphere Business Events database, or configure the new installation to connect to the repository database used by the previous installation. If you do not need to preserve event contexts and history data, you can skip this step and configure the new installation using Event Designer to deploy assets.
    3. Start the new installation of Operational Decision Manager.

      Attention: If you are reusing an existing repository, you can skip the remaining steps, and use the new installation without redeploying existing event assets.

    4. You can redeploy the event project to reconfigure the assets in the existing repository database, or to configure a new installation that does not use an existing repository database. If the event project uses a JDBC data connection, you must reconfigure and deploy the data connection. In addition, you must redeploy the event project if any of the following conditions apply in your environment:

      • The new installation uses a new repository database.
      • The event project includes a JDBC data connection.
      • The configuration of the event project is specific to the environment.

    5. Use Event Designer, import an existing repository, asset store, or project file from the previous installation of WebSphere Business Events.
    6. If the project contains a JDBC data connection, edit the data connection and specify the correct JNDI name.

      Specify the data source JNDI name if the connection is used by the JDBC event or action connector. The data fetcher uses the data source JNDI name if specified, or the explicit JDBC properties specified for the data connection.

    7. Make any additional changes to the event project that are necessary for your new environment.
    8. Deploy the updated project to the new Operational Decision Manager repository.


Results

All assets used by the previous installation of WebSphere Business Events are present and active in the new runtime.


Terminology changes between WebSphere Business Events and Operational Decision Manager

Operational Decision Manager includes new terminology and also changed terminology for some features that you might know from WebSphere Business Events.

Many terms remain unchanged, such as asset, action, action object, clock event, event, event flow, event object, field, field constructor, filter, folder, named constant, synthetic event, template, and technology connector.

The following tables list the terminology changes and the new terminology.

Table 1. Terminology changes.
WebSphere Business Events term Operational Decision Manager term About this terminology change
Business Events Capture widget

Business Events Chart Manager widget

Business Events Chart widget

Business Events Layout widget

Business Events Replay widget

Business Events Tester widget

Event Capture widget

Event Chart Manager widget

Event Chart widget

Event Layout widget

Event Replay widget

Event Tester widget

The term event is used to mean parts of Operational Decision Manager that are used in the context of business event processing.
context-scoped intermediate object (CSIO) context-scoped business object A new name for a summary object or accumulating array object that is used to share data from events across events in a context.
data source data connection A new name for a data repository in an external system containing data that is required for the evaluation of an event or population of any action object fields not provided in the event.
description documentation This term specifically applies to a field containing comments about an asset.
Design Data Event Designer Design Data is no longer used in Operational Decision Manager because you now use Event Designer as your development environment.
interaction block event rule The term rule now applies to a piece of business logic against which events are evaluated by the runtime server, and this term means specifically event rules in event projects.
interaction set event rule group This term now applies to a group of event rules providing complex business logic that operate together and typically include an otherwise clause.
intermediate object business object A new name for an abstract representation of fields that belong to event and action objects.
project event project The term for an organization of all assets that make up an event application has changed to event project to differentiate this type of project from a rule project.
project store Decision Center repository A new name for the repository that stores event assets, and which now also stores rule artifacts.
publish deploy A new name for when you deploy an event project the event runtime.
runtime repository

repository

WebSphere Business Events Runtime

event runtime The new term event runtime groups together a number of WebSphere Business Events terms that applied to the runtime or repository, to simplify the runtime concept.
shared action object action object reused in more than one action A new name for reusing an action object.
shared event object event object reused in more than one event A new name for reusing an event object.
time-delayed event time-delayed rule A new name for the delay before an event rule is evaluated.
touchpoint folder

touchpoint system

These terms are new, differentiated names for the representation of an external system or application that was previously called a touchpoint. A folder in Event Designer can be an organization of assets; but it can also be a representation of an external system, or touchpoint system, which is a system that is connected to and that can generate events or receive actions.
watch event track event A new name for a special type of event used to track data as it passes through the event runtime.

Table 2. New terminology
WebSphere Business Events feature Operational Decision Manager term About this new terminology
Deploying projects EventApp This term means a deployment unit for event projects.
Synchronizing projects Publish This term applies to synchronizing an event project between Event Designer and the Decision Center repository
Writing filter expressions and contents Business Events Language (BEL) This term applies to the structured natural language for events that is used by business users and developers to write rules in event projects.