IBM Operational Decision Manager 8.5 Upgrade Series Part 1 – Decision Center

In this series of articles we’ll follow along with an upgrade from a relatively complex customized 7.1 installation of IBM WebSphere Operational Decision Manager to IBM Operational Decision Manager (ODM) 8.5.

ODM 7.5, 8 and 8.5 bring us a number of valuable features and capabilities:

Highlights:

• Enhanced business user experience with new change management, governance capabilities & business console
• Branching and merging of branches
• Business focused simplified collaborative environment o Governance framework for managing releases and multiple referenced rules sets (services)
• The ability to execute business rules from mobile applications
• Events capabilities, the addition of Complex Event Processing CEP capabilities to ODM
• Business ability to test rules with complex results using excel scenarios
• XXX Mainframe
• Operational enhancements
• Ability to decouple the management console from the execution environment and manage embedded rules remotely.
• Enhanced automatic generation of decision point web services HTDS

For reference on features:
What’s new in version IBM ODM 8
What’s new in version IBM ODM 8.5

The above new capabilities and potential end of life for 7.1 are usually drivers to upgrade to a later version.

In this article we’ll look specifically at migrating Decision Center formally known as rule team server, in later articles in this series we’ll look at the rules migration, testing, migration of customized decision validation services, decision server and more.

Migration of Decision Center Data (fka RTS)
Decision Center stores its information in a database, from version to version there will be changes made to the database structure and IBM provides scripts to assist with migrating information to the latest versions. The first issue we ran into was that the ANT migration documentation provided was confusing. Initially we thought that the script needs a running 7.1 decision center server and to be pointed to an 8.5 database. We edited the properties file in the bin folder called teamserveer-anttaks.properties and add the OldDatabaseSchemaName which is the 7.1. schema and an output file location where you would like the SQL to be generated. Datasource name for 7.1 and server URL and login credentials. The migration script gives a number of options to migrate various aspects, for the schema we’ll use gen-migration71-script option to the ant command.

DC Database migration Issue 1: Documentation
The following exception is thrown when we try to run the conversion:
[gen-migration71-script] ilog.rules.teamserver.model.IlrConnectException: Could not deserialize result from HTTP invoker remote service [http://localhost:8080/teamserver/
remoting/session]; nested exception is java.io.InvalidClassException: ilog.rules.teamserver.model.IlrSessionContext; local class incompatible: stream classdesc serialVers
ionUID = 4729857957054555657, local class serialVersionUID = 8906827035412667122

Solution:
After some experimentation and chatting to IBM, we figured that the old schema has to be on the same database server as what the 8.5 DB server is using and that the ant script should be pointed at the 8.5 decision center server and not the 7.1 RTS.

DC Database migration Issue 2: Inconsistent Data
There were two issues missing data and duplicate names that now need to be unique in the 8.5. version. We are not sure of the reasons why data was missing, but the script filed on missing data in the artifact tables where information existed in version tables for some rules version as part of a baseline. The report names for DVS simulations where the same and needed to be made unique because of a new table constraint.

Solution:
The solution was to delete the versions of the rules that were missing from the artifact table because the baseline was in recycle bin.
delete from baselinecontent where version=item.ID;
delete from version where id=item.ID;
and
Update SCENARIOSUITEREPORT set NAME=item.NAME

Issue 2: Secure Team Server (HTTPS) 

If you are attempting to connect to a secure SSL enabled server then you may get an exception. SSLHandshakeException

Solution:

In order to get around this exception you’ll need to download and then import the certificates. To download the certificates brows the home page of decision center and click view certificates in the browser and download a .cer file. The next step is to import the certificate to your local JRE trust sore

e.g. 

keytool -import -keystore "C:\Program Files\Java\jre7\lib\security\cacerts" -file C:\Users\abcd\Desktop\ RTS_Certficate.cer

Customized Branding 

The first port to 8.5 was the branding customization. This is generally used in a Multi-tenants scenario. A custom skin was added in the skin-faces-config.xml under the web-inf folder with the CSS and properties copied to the skin and customized. Additional tabs where also added as part of the customization where a file tabs.jsp was added to the custom folder.

Issue 1: CSS & Properties Merge

The custom Message.properties can’t be ported directly as some new keys are added to the 8.5 version like with CSS changes a file diff and edit will need to be done.

Solution:

The best resolution was to compare the properties & CSS file from 7.1. to the custom properties and pull the differences out which can be applied to version 8.5 new skin files directly.

We have to do a file diff on the differences between the CSS files.

Issue 2: JSF version changes

The have changed the underlying JSF 1.1 to myfaces 1.1.5

Solution:

Add the following liens of code to your faces-config.xml in the web-inf folder of teamserver war.

<renderer>

    <component-family>javax.faces.Command</component-family>

    <renderer-type>javax.faces.Button</renderer-type>

    <renderer-class>org.apache.myfaces.renderkit.html.jsf.ExtendedHtmlButtonRenderer</renderer-class>

</renderer>

<renderer>

    <component-family>javax.faces.Command</component-family>

    <renderer-type>javax.faces.Link</renderer-type>

    <renderer-class>org.apache.myfaces.renderkit.html.jsf.ExtendedHtmlLinkRenderer</renderer-class>

</renderer>

Extension Models

If you have any custom extensions model, make sure that you upload the .brdx and .brdm files on the Decision Center Installation Wizard screen.

API Changes
We encountered a number of changes in the API’s, this is not an exhaustive list but the ones that we ran into as part of an upgrade/migration.

Migration of Decision Center from 7.1 versions to 8.5 requires updating the APIs as well as any customized skin/branding being used.

API and Method Changes

1. API changed from ilog.rules.teamserver.web.servlets.IlrDownloadServlet to ilog.rules.teamserver.web.servlets.IlrTestingDownloadServlet.
2. IlrApplicationException needs to be handled if you are calling IlrDefaultSessionController.onCommitElement.
3. IlrApplicationException needs to be handled if you are calling IlrDefaultSessionController.elementCommitted.
4. API changed from ilog.rules.teamserver.web.servlets.IlrDownloadUtil to ilog.rules.teamserver.web.servlets.IlrDownloalUtil.
5. IlrWUtils.getTimeZone() now returns an object of com.ibm.icu.timezone.

The next parts of this article will cover decision server, decision validation services customizations and other migration items.

To learn more about Prolifics, visit www.prolifics.com.


Ryan Trollip is Prolifics’ Decision Management Practice Director. Ryan is an experienced solutions architect and implementation lead with a strong background in business driven and improvement focused solutions with an emphasis on Decision Management. Ryan has a proven track record of delivering successful projects, with over 15 years of experience covering project management, enterprise architecture, account management, and design/programming in a decision management context. Prior to joining Prolifics, Ryan was an Architect and Technical Account Manager, independently and for IBM/ILOG, focused on leading the delivering complex decision management projects.

Amrinder Singh Brar is a Technical Lead for Decision Management at Prolifics. Amrinder has 8 years of experience in software development with 4+ years of extensive experience in ILOG/BRMS world. His key expertise lies in implementing Decision Management solutions in Banking, Telecom, HealthCare and Travel domains. Prior to joining Prolifics, Amrinder worked as a Solution Consultant for various ILOG migration and implementation projects with Telecom and IT majors.

Avoiding Future Interface Changes in IBM ODM Rule Services

When building and deploying an IBM ODM[i] business rule based service, one aspect to carefully consider is the structure and composition of the rule service interface; what will become the WSDL in a SOAP/WS HTDS[ii] implementation. Because all service consumers are dependent on this structure, frequent changes to this interface can result in significant rework for all consumers as well as code changes in the rule service itself. Additionally, supporting each interface change introduces change dependency between all consumers and the service. There are ways to avoid this complexity by introducing more flexibility in the service interface. However each technique comes with its own set of tradeoffs that must be carefully considered.

There are three basic approaches. To illustrate, imagine a rule service that determines if a company will accept a transaction from a US customer. In the initial and most simple version, the company policy is to refuse a transaction from any customer under the age of 21. Age is the only decision criteria. In a future version of the same service, the decision criteria becomes more complex when it is determined that the threshold age should vary based on the customer’s US state of residence.

Small, fast, and simple

In this approach the rules service interface contains only the data required by the service to perform the implemented decision point. The structure of the data in the interface is flattened with respect to the decision point implementation and attribute names represent the business decision criteria. The objects in the interface can be used directly in the rule BOM and the default verbalizations will likely be sufficient. No additional mapping of data is required. Marshaling/de-marshaling and transport overhead is kept to a minimum allowing very rapid service response. In later versions of ODM[iii], a REST implementation becomes a viable option with a small number of specific input attributes related to the decision and low transportation overhead. This approach is fast to implement, execute, and easy to change in initial development, but is the least flexible to future change once deployed. Any future additional data requirement in the decision point will require an interface update to accommodate the change. This technique is best used to quickly develop a rule service with rapid changes to the decision criteria while still in development.

In our example to identify customers below the age of 21, the interface initially may only consist of a customer identifier and the customer’s birthday. However our future implementation that observes the customer’s US State of residence will require a service interface change to add this attribute. Concurrent execution of old and new versions of the rule service requires strict versioning of the WDSL and therefore the rule app / rule set.

Enterprise Data Model

In this approach, the rule service interface consists of the entire enterprise data set that may be used to perform the implemented decision point, even if most of the data is unobserved in the initial rule implementation. In other words, the caller passes everything it currently knows about the subject of the decision in the event future rules might need additional information. This approach provides a more comprehensive data interchange, but is limited by the quality of the data model. This approach is most commonly used with vertical industries that have a well defined and widely accepted object model such as those defined by standards bodies such as ACORD, MISMO, EDI Standard formats, HL7, et al. The objects in the interface typically contain several levels of hierarchical data and maps poorly to a flatter, business-oriented BOM desirable in business rule implementations. This commonly necessitates at a minimum custom BOM verbalizations, and frequently mapping of the interface object to a flatter and less normalized form; all adding to the time and effort in rule implementation. However, the advantage is that future rules are less likely to require an interface change IF the enterprise data model is complete, stable, and universally accepted. Because the interface is typically large, in the case of most SOAP web services and message-based architectures, marshaling/de-marshaling, transportation overhead, and remapping become the overriding performance constraints rather than rule execution times.

Using our example rule service implementing a decision point to identify customers below the age of 21, the initial interface would consist of everything about a Customer tracked in the enterprise data model. This will likely include the customer’s birthday allowing age to be derived. When the service needs to expand in the future, allowing the age threshold to vary by customer location, no interface changes will be required if the enterprise model already includes the US state of the customer’s residence. A ‘rules-only’ change can be made to add BOM mappings for the newly required attributes and the rules written using these new attributes. This approach should be avoided if the enterprise data model changes frequently or is unlikely to include future required data elements. Frequent changes in the enterprise model result in changes to the rule service interface even when the model changes do not affect the current rule implementation in order to remain consistent with all rule service consumers. And using this technique requires all consumers and rule services to implement the same version of the enterprise model. If the data model is unstable, managing this dependency alone can negate any flexibility gained with the more comprehensive initial interface.

Generic Key/Value Pairs

In this approach, the rule service consists of a generic list of key/values pairs commonly implemented as a Map or map-like structure. The ‘key’ is a string describing a business attribute name and the ‘value’ is the value of that attribute. This allows any data to be passed to through the rule interface without structural changes in the rule service interface itself and represents the most flexible interface style. Using the previous example of a rule service determining transaction acceptability based on customer age, the interface could initially have a list of keys ‘customerID’ and ‘customerBirthDate’ with their corresponding values. If in a future version, customer location becomes required, the caller would simply add a key ‘customerLocation’ to the list in the interface and provide a value for this information to the rule service in the granularity required. However, the rule service needs to be aware of all the possible key values. These are typically maintained manually as a static or dynamic enumeration in the rule source so business attributes may be properly mapped to BOM vocabulary. This has a distinct advantage over the enterprise data model scenario in that only the data required in any given version of the service is actually passed through the interface to the rules.  This keeps marshaling and transportation overhead low, but still allows for new data to be added without changes to the structure of the rule service interface.

However using this approach means it is more likely that the callers of the rule service will need to make corresponding coding changes to support future data requirements in the rule service. This will often invalidate the advantage that the rule service may be changed without java code alteration. An additional concern with this approach is the loose typing and late binding of the interface elements. While this provides flexibility in the data passed, it effectively places additional run-time validation requirements on the rule service to ensure that the interface data expected is actually provided and typed correctly. Finding the rule service implementation out of sync with the implementation and expectation of multiple consumers is a common problem with this approach.
--------------------------------------------------------------------------------
[i] Operational Decision Management, formerly known as IBM ILOG JRules or WODM, WebSphere Operational Decision Management
[ii] Hosted Transparent Decision Service, a feature of IBM ODM that exposes a ruleset as a SOAP Web service
[iii] REST API supported in ODM V8.5 and later
Written by Lawrence Terrill, Technical Lead, Prolifics Business Decision Management Practice

Using HTDS with Java XOM in IBM Operational Decision Manager 8

Until version 7.1, IBM ILOG-JRules had Hosted Transparent Decision Service (HTDS) working only when you had dynamic Execution Object Model (XML XOM). However, in IBM Operational Decision Manager (ODM) 8, IBM enables you to still use the HTDS when have static XOM (java XOM).

Though this is good for the projects where XOM was defined in Java and Rules needs to be exposed as Web-Service, in ODM 8 we don’t have to write custom web-service code for exposing Rules as Web-Service if you have Java XOM. This saves a significant amount of time, however, there are still some changes you can make if you have Java XOM to make it work with HTDS in ODM 8 seamlessly.

When you deploy your Rules and Java XOM in RES internally, your Java XOM gets converted to XML format and then it gets exposed through the WSDL to call your Rules as Web-Service.

The caveat here is when the conversion from Java XOM to XML format happens inside RES for HTDS you need to tell the engine how XML will get generated. For example if you have List and Date in your XOM you need to generate XML elements accordingly and change the date format from Java util date to XML date.

As we know there isn't a unique correct mapping between Java Object structures and XML documents. We will need to use Java XML binding implementations to provide ways to fine tune the mapping.

For converting your Java XOM seamlessly into HTDS and working with Web-Service (Request/Response) you will have to use JAXB annotations to tell the engine the specific format you want your XML to be generated.

Below is the code how you should be annotating your List in Java XOM.

Let’s say you have your Java code for List defined below:

List yourObjectList = new ArrayList();

In the getter method you need to have your annotations defined like below.

Note: You can give any string for your name (name = "YourObjects") in the annotation but whatever you define here will be part of your generated XML element in your Request/Response, so choose name as per your requirement. Some like it with List at the end while others prefer something Plural, like YourObjects.

When you are dealing with the Date in Java XOM in HTDS you need to have XmlAdapter class extended and then write your own class like below:

Then, wherever you get methods for your date, you should annotate that as indicated below:

This will make sure the conversion from Java-XOM to XML format happening seamlessly.

Alok Keshri, a Technology Manager for Prolifics focusing mainly on ILOG-JRules and ODM space, has over twelve years experience in IT industry spanning across various industry, He is experienced and resourceful enterprise software Tech Lead/Architect and has worked with J2EE/ SOA/BRMS/ BPM technology. He is specialized in Object Oriented Analysis, Design, Development, and Estimation of project with heterogeneous Web technologies in complex business systems based on variety of platforms, he has extensive experience in IBM middleware products such as WebSphere Application Server, WebSphere ILog-JRules, WebSphere Message Broker and other products in the IBM BPM stack. He is certified in WebSphere ILog-JRules and Filenet, Alok received his BE in Electrical Engineering in year 2000.