accelerator

English | Français | Deutche | Néerlandaise | Español

Status: Pre-release
Created and maintained by: Peter Warde
E-mail: peterwarde@rulearchitect.com
Other: LinkedIn

Last Updated: 12th May 2021

INDEX

SECTION 1 : INTRODUCTION

• About
• Audience
• Goals
• Summaries
  • Features Summary
  • Examples Summary

SECTION 2 : FEATURES

• Business Rule Book and Rule Reports

  • Overview
  • Rule Book and Rule Report APIs
  • Business Rule Book (BRUB)
  • Business Rule Reports (BRUR)
  • Example : Default Governance

• DEV-OPS Tools and Maven Plugins

  • Command Line Tool Kit (CLTK)
    • Tool Kit Overview
    • Tool Kit APIs
    • Tool Kit List
    • Example : Mavenize ODM Tool
  • ODM Maven Plugins (OMVP)
    • Maven Plugins Overview
    • Maven Plugins APIs
    • Maven Plugins List
    • Example : Repackage Decision Center Archive Plugin

• Reference Data Starter Kit (RDSK)

  • Reference Data Overview
  • ODM Features for Handling Reference Data
  • The Starter Kit
  • Example : Dynamic Domains from External Sources and Value Editors
  • Reference Data Server

• Modified Core Types (MCRT)

  • Modified Core Types Overview
  • Example : Euro and Percentage Types
  • MCRT Library

• Business Rules Decision Service (BRDS)

  • Decision Service Overview
  • Decision Service Framework
  • Example : Decision Service Example

SECTION 3 : EXAMPLES

• Example : EU-Rent (EURT)

  • EU-Rent Overview
  • EU-Rent Features
    • Analysis Artifacts
    • Software / Development Artifacts
  • EU-Rent Features
    • EU-Rent Business Rule Book
    • EU-Rent Modified Core Types
      • Financial Types
      • Time Unit Types
    • EU-Rent Command Line Tools and Maven Plugins
    • EU-Rent Reference Data
      • Dynamic Domains from External Sources
      • Value Editors
    • EU-Rent Business Rule Decision Service

• Other Examples

SECTION 4 : GETTING THE ACCELERATOR

• Source Code Repository
• Software Requirements
• Further Information

SECTION 1 : INTRODUCTION

About

Many types of technology can implement a decision, but IBM Operational Decision Manager is one of the best products on the market for business rules because it allows you to express rules in the everyday business language of your organization and create rules that are "under business jurisdiction".

ODM Accelerator is a collection of reusable resources (source code, frameworks, APIs, kits, building-blocks, solutions, documents and working examples) that you can use in the design and development of ODM. With it you can build and create richer, better, more maintainable, and higher quality ODM rule applications. You can also do it more easily and rapidly than starting from scratch and gain strong early technical wins and deeper insights into ODM.

It does not replace anything in IBM ODM; it elegantly extends what is already there and fills in the gaps. It is designed to unleash the power of ODM as a Business Rules Management System (BRMS), facilitating rule authoring, rule management and decision versioning. It is the result of over twelve years of first-hand experience of providing ODM solutions to some of the largest companies and organizations. It makes ODM more complete and fully fit for purpose for your organization.

Your analysts, business users, developers and architects will still have to put the legwork in but using ODM Accelerator everything you do around ODM will be easier, cleaner, richer and more guided.

[top]

Audience

This wiki is intended for architects and developers, and other technical people who have an understanding of IBM Operational Decision Manager.

It may also be of interest to those who want to learn about ODM, business rule and BRMS concepts.

[top]

Goals

Business Users and Analysts

For business users and analysts, the primary goal of ODM Accelerator is to facilitate business rules "under business jurisdiction" by:

• promoting the use of business rules concepts and methodologies in ODM;
• improving the quality of rule authoring and business rule management in ODM Decision Center; and
• extending and improving the capabilities of out-of-the-box (OOTB) ODM.

The true value of ODM is its capability to empower the business to have full control of its business logic expressed as business rules in a BRMS, and not as code in an IT system. It is only when business rules are "under business jurisdiction" that an ODM application is truly successful.

IT Architects and Development Teams

For architects and development teams ODM Accelerator aims to enable:

• the building of better quality ODM rule applications;
• provide easier development of complex ODM features;
• provide tools for modern development and operations teams to use with ODM.

Many teams only scratch the surface of what is needed to deliver a fully working successful ODM project to business users. ODM Accelerator aims to make it easier for them to do so.

[top]

Summaries

ODM Accelerator consists of the following features and examples:

[top]

Features Summary

• Business Rule Book and Rule Reports - create a Business Rule Book at the start of an ODM project with a defined governance and then integrate and replace it with on-line reports of the rules in Decision Center.

• Business Rule Book (BRUB) – Build business vocabularies, discover, capture and organize business rules with a customizable Rule Book with a built-in methodology and governance. Use the default template, or adapt it, to get your rules off to a good start with a consistent approach across your organization.

• Business Rules Reports (BRPT) – Use these on-line reports to promote rule visibility and allow business users, project managers and architects to view, control quality, monitor progress and validate Decision Center rules in real-time.

• DEV-OPS Tools and Maven Plugins - Make your teams more productive with these frameworks for developing and managing ODM. Use starter-kits for tools and Maven plugins to enable agile DEV-OPS teams to efficiently perform ODM Continuous Integration/Continuous Deployment (CI/CD) tasks:

• Command Line Tool Kit (CLTK) – A starter kit and set of command-line tools to script and automate common CI/CD ODM activities. The kit provides a set of core APIs for building command-line tools, together with high-quality examples. Build your own, or compile and use the examples straight out-of-the-box (OOTB).

• ODM Maven Plugins (OMVP) – A starter kit and set of Maven plugins for developers performing ODM development tasks. Automate your rule deployments to Decision Server using Maven; re-package ODM Decision Center using a Maven Plugin that is 6 times faster than the corresponding ODM ANT task. Build your own, or compile and use the examples straight out-of-the-box (OOTB).

• Modified Core Types (MCRT) – Add business phrases for currencies, math functions such as calculating percentages of currencies, units of measurements, etc. as modified core ODM types.

• Reference Data Starter Kit (RDSK) Use this important kit to get your rule authoring up and running quickly, and ODM correctly integrated with third-party applications. Business rules can use a lot of reference data. Using value editors and dynamic domains from external sources will help you improve rule authoring and rule execution.

• Business Rules Decision Service (BRDS) – Build fully transparent and versioned decision services where changes do not impact service consumers and versioning of rules is not hard-coded into components. The BRDS resolves the challenge of handling these and other integration issues.

[top]

Examples Summary

In addition to the features, the following examples below help you understand how to use the features:

• EU-Rent Example (EURT) - An implementation of the Object Management Group's SBVR EU-Rent Example shows you how to design and build a high-quality ODM rule application using all the accelerator features integrated with IBM BPM 8.6.

• Other Examples - Each feature comes with one or more examples showing how to use the feature. Some of the examples can be used out-of-the-box (OOTB) or adapted for your own ODM applications.

[top]

SECTION 2 : FEATURES

[top]

Business Rule Book and Rule Reports

Discovering and capturing your decisions, and the business rules they contain, is the starting point of any ODM project and a critical step. Getting it right from the outset is fundamental. These are the rules and decisions you will create in ODM. An ODM project will therefore need to discover and define the rules, and report on their creation in Decision Center.

[top]

Overview

Typically, at a high-level an ODM project falls into 3 stages:

• Project Inception - in parallel

  • analysts carry out requirements activities such as defining the vocabulary that will be used in rules, writing and organizing the rules and validating them with policy managers;
  • ODM architects and developers design and implement ODM setup in Rule Designer, including project organization, creation of the data model (XOM) and rule vocabulary (BOM), decision service integration with external applications;

• Rule Authoring - after project inception and the publication of the ODM setup to Decision Center, the initial rules from the Rule Book are authored, reviewed and tested in Decision Center prior to deployment; and

• Application Deployment - rules are deployed from Decision Center as decision services to Rule Execution Server, and tracking and monitoring is carried out.

To facilitate work needed to be carried out in the project inception and rule authoring stages, ODM Accelerator provides the following two artefacts:

• Rule Book - a Word document to define your governance, and capture your initial rules at the start of your ODM project; and

• Rule Reports - an on-line application to promote your governance, and report on the rules being authored in Decision Center.

[top]

Rule Book and Rule Report APIs

Using the Rule Book and Rule Reports APIs, you can move from one to the other by defining the following as Word documents:

• the rule governance
• the organization and layout
• supporting resources and guidance

and include them in both the Rule Book and the Rule Reports.

When you start authoring rules in Decision Center you can easily migrate from the Rule Book to the on-line Rule Reports where:

• the report business vocabulary is the Decision Center vocabulary; and
• the report rules are the Decision Center rules.

In addition, using the API's you can add metrics to the Rule Reports, which allows managers to monitor rule authoring progress.

Finally Rules Reports are external to Decision Center, and read only. Managers, analysts and business people can safely access them.

[top]

Business Rule Book (BRUB)

The Business Rule Book is generated using a command line tool.

The Rule Book is organized into 4 sections:

• Section 1: Rule Book Governance
• Section 2: Business Vocabulary
• Section 3: Business Rules
• Section 4: Additional Resources

In the governance section you can define your organization's standards and principles, approach and methodology; in the vocabulary section you create fact models and define the vocabulary; in the rules section you capture the initial rules of your ODM project, and in the resources section you can add links for learning about rules.

You can customize the rule book. For example, you can use the default governance, modify it for your organization, or substitute it with a new one. You can brand the Rule Book with your organization's details, and a color theme. The rule book can also be localized.

Note

The Rule Book is an important aid to an initial ODM design and implementation by developers whereby:

• the organization of rules can be used for the ODM repository design;

• the vocabulary can be used to design and create the ODM BOM

• the types of information you gather about rules define ODM rule properties; and

• rule owners can be used to configure Decision Center access and permissions.

The Rule Book is a good place to sort out such details before you start authoring in Decision Center. It is a valuable resource for developers and architects in the ODM Rule Designer and Decision Center setup.

[top]

Business Rule Reports (BRUR)

Rule Reports are created using the same API's that created the Rule Book, and whilst containing the same structure layout and content of the rule book, they replace the rules of the rule book with those of Decision Center and are enriched with additional features.

The framework can also include the governance from the Business Rule Book (BRUB). If you have adopted the organization of the rules, their names and properties etc. of the Rule Book in your rule authoring, then reports will have the same format and layout, making the transition from one to the other seamless.

Rule reports in the end replace the rule book - they can handle a large number of rules and as they are on-line are more visible to business community.

As the rules in Decision Center grow, you can handle the increasing number and leverage tools such as queries and consistency checking. With Business Rule Reports you can create custom reports as well as add metrics to monitor rule authoring progress.

Note

The Rule Report provides the following features:

• structured business information with strong navigation and clear layout as opposed to the ad hoc information of the Decision Center reports with no navigation and poor layout;

• includes the Governance from the Business Rule Book;

• has the same layout and navigation features as the Business Rule Book to ensure a smooth and traceable path from the Rule Book to ODM implemented rules;

• has dashboard layout features summarizing the number and different types of rules in ODM Decision Center, the number of rules that have been recently created or changed etc.

The rules can be tagged for review and used as center points for group discussions.

Business Rule Reports does not replace Decision Center reports but supplements them. You can still use Decision Center reports, but they will not have the features of Business Rule Reports.

[top]

Example : Default Governance

The default governance is based on, and references, the following on-line resources:

• Business Rules Manifesto;

• Semantics of Business Vocabularies and Rules (SBVR) from the Object Management Group; and

• Business Rule Concepts- Getting to the Point of Knowledge by Ron Ross.

Using the governance and its resources, you will learn:

• what is a business rule;

• how decisions can be decomposed into policies and rules using decision point analysis (top-down approach);

• how rules and policies can be aggregated into decisions (bottom-up approach);

• how to transform raw business rules to formally defined business rules ready for authoring in ODM;

• build fact models containing business terms and the facts between them;

• understand how to identify a decision's primary and secondary business nouns;

• build structured business vocabulary that can be used as business phrases in your rules;

• learn how to classify, name, and organize a large quantity of business rules; and

• create high-quality business rules that are consistent, unambiguous, and can be understood by business people.

One of the benefits of using the default governance is that it is an excellent step for achieving the goal of "business rules under business jurisdiction".

[top]

DEV-OPS Tools and Maven Plugins

DEV-OPS tools and Maven plugins provide a common Java framework for teams performing Continuous Integration and Continuous Deployment across different environments.

Tools and plugins consist of 2 parts:

• Command Line Tool Kit – on the OPS side a starter kit and command line tools that can be used to automate common CI/CD ODM tasks; and

• ODM Maven Plugins – on the DEV side a starter kit and set of Maven plugins for developers performing ODM development.

Both have a common API for interacting with ODM Rule Designer, Decision Center, Decision Server, and third-party software such as Maven repositories. However, both have separate build artifacts that work independently of each other and in a way end-users expect.

Finally, they modernize and supplement the Ant tasks provided with the ODM installation. For developers Ant is replaced with Maven and administrators get tools they are used to working with.

Command Line Tool Kit (CLTK)

Tool Kit Overview

The Command Line Tool Kit provides a framework for building tools for administrating common ODM tasks, such as building and deploying decision services. It consists of a starter kit for developers, as well as a number of example tools that can be used OOTB.

[top]

Tool Kit APIs

Using the APIs developers can rapidly build high-quality tools with the following features:

• each tool is self-contained in a single .jar archive with all necessary classes and dependencies - an ODM installation is not required;

• each tool uses an annotations framework which can create a rich menu of command line options:

#!java

@ToolDetails(banner = "ODM Accelerator Tool", name = "Example Rule Designer RuleApp Build and Maven Install and Deploy Tool (CLTK)", desc = "An example tool to build a RuleApp from ODM Rule Designer and install to a local, or deploy to a remote, Maven repository.", license = "Apache License, Version 2.0", version = "8.10.3", supportEmail = "peterwarde@rulearchitect.com", examples = {
        @ToolExample(name = "build-install-local", example = "java -jar orcb-cltk-rd-extract-mvn-deploy-tool-0.0.1-SNAPSHOT.jar -rpd \"C:/odm-rules-cookbook/cmd-line-toolkit-cltk/orcb-cltk-test/ORCB RULES CLTK Test\" -dcn \"ORCB RULES CLTK Test Deployment\" -xclp C:/odm-rules-cookbook/cmd-line-toolkit-cltk/orcb-cltk-test/orcb-cltk-test-xom-1/target/orcb-cltk-test-xom-1-0.0.1-SNAPSHOT.jar C:/odm-rules-cookbook/cmd-line-toolkit-cltk/orcb-cltk-test/orcb-cltk-test-xom-2/target/orcb-cltk-test-xom-2-0.0.1-SNAPSHOT.jar -exmd install-local -gid rules.group -aid ORCB_RULES_CLTK_Test_Decision -avr 0.0.1-SNAPSHOT -gpom -lrp C:/test/.m2/repository"),
        @ToolExample(name = "build-deploy-remote", example = "java -jar orcb-cltk-rd-extract-mvn-deploy-tool-0.0.1-SNAPSHOT.jar -rpd \"C:/odm-rules-cookbook/cmd-line-toolkit-cltk/orcb-cltk-test/ORCB RULES CLTK Test\" -dcn \"ORCB RULES CLTK Test Deployment\" -xclp C:/odm-rules-cookbook/cmd-line-toolkit-cltk/orcb-cltk-test/orcb-cltk-test-xom-1/target/orcb-cltk-test-xom-1-0.0.1-SNAPSHOT.jar C:/odm-rules-cookbook/cmd-line-toolkit-cltk/orcb-cltk-test/orcb-cltk-test-xom-2/target/orcb-cltk-test-xom-2-0.0.1-SNAPSHOT.jar -exmd deploy-remote -gid rules.group -aid ORCB_RULES_CLTK_Test_Decision -avr 0.0.1-SNAPSHOT -gpom -mvpr http -mvh localhost -mvpo 8081 -mvu admin -mvpw admin123 -rrp test-release-only") })
public class RdExtractMavenDeployTool extends
        AbstractHttpTool<MavenRepositoryClient, MvnBuildUploadParams> {

and example commands;

• each tool can generate its own tool-config.properties file containing property keys for the tool options and help instructions. You can populate the values for the keys and execute the tool using -cfg <CONFIG FILE> option, which are great for ease-of-use, repeat usage and standardization across teams;

• tools work across different environments (Linux, Unix, Windows etc.) and can be used by build agents such as Jenkins or TeamCity as part of your continuous build, test, and deployment pipelines;

[top]

Command Line Tool Kit List

Below is a list of the current example command line tools in the GIT repository which you can compile and use OOTB.

[top]

Example : Mavenize ODM Tool

If you use only one tool from the command line tool kit, then use this #1 tool for productivity - you can rapidly kick-start your ODM development by mavenizing the ODM installation in minutes.

The tool combines two execution modes:

• install-local - installs to a local Maven repository;

• deploy-remote - deploys to a remote Maven repository such as Sonatype's Nexus or Apache Archivia.

Either mode places all the ODM installation binary archives (.jar, .war, .ear, .rar files) in a Maven repository, after which your development team is ready to go.

This tool will get you up and running with ODM and Maven in no time at all.

Note

If you do not have a remote repository available, use the install-local option, which will install the binaries locally on a developer's computer, and migrate to a remote repository later.

[top]

ODM Maven Plugins (OMVP)

Maven Plugins Overview

ODM Maven Plugins provides a Java framework for building plugins for ODM developer tasks, such as building and deploying ruleApps or repackaging Decision Center. It consists of a set of APIs for developers, as well as a number of example plugins you can use OOTB.

Modern development environments use Apache Maven with centralized dependency management and builds. By contrast, development activities are supported in the ODM installation by ODM Ant tasks with limited support for Maven.

Using ODM Maven plugins, will allow you to integrate ODM with your own Maven development environments, modernize ODM development, and remove cumbersome legacy tools such as Ant.

[top]

Maven Plugins APIs

For plugin developers there is a single core API which provides a standardized and consistent way of developing plugins for ODM.

Using the APIs, you can build high-quality plugins with the following features:

• each plugin can combine together common ODM tasks;

• each plugin can install to a local, or deploy to a remote, repository; and

• plugins can interact with Rule Designer, Decision Center, Decision Server, and Maven repositories.

[top]

Maven Plugins List

Below is a list of the current example Maven Plugins in the GIT repository which you can compile and use OOTB.

[top]

Example : Repackage Decision Center Archive Plugin

The odm-rdsk-dc-maven-plugin is a Maven plugin version of the ODM Ant tasks repackage-ear and repackage-war, but with improved performance and better functionality.

The plugin allows developers to repackage the Decision Center .war and .ear archives on, either the file system or to a Maven repository, with additional classes, .jars, resources, and web.xml elements.

It has the following 2 Maven goals:

• repackage-ear - repackages the jrules-teamserver-WAS85.ear enterprise application archive; and

• repackage-war - repackages the decisioncenter.war and teamserver.war web application archives.

For developers, the plugin integrates their Decision Center modifications with a Maven build, and reduces the tedium of the many slow development, deploy, and test cycles needed.

For administrators, the plugin enriches the META-INF/MANIFEST.MF of the Decision Center archive with change and build information, such as the added archives, build date, GIT branch and hash number, etc.

With the plugin they can confidently track, trace, audit and control a repackaged Decision Center archive as it is promoted through SIT and pre-production environments into production.

[top]

Reference Data Starter Kit (RDSK)

Reference Data Overview

Rules authored in ODM Rule Designer and Decision Center often involve reference and master data values.

For example, if you want to create a rule involving a country, you will probably use ISO 3166 Country Codes:

If the country is France, the value will be the code "FR" and the country name "France".

Reference data, such as ISO countries, consists of lists of name-value pairs. It is non-hierarchical and flat, and when these lists are very long, they are only usable in UIs with scrolling and sometimes filtering.

It is also common for rules to require more complex types of data. For example, geographical data, such as countries, cities, localities and streets, consists of multiple parent-child relationships, and can be visualized as a tree.

These hierarchies are common in rules and can be complex and extensive, running into hundreds and thousands of values. You can find them in medicines, commodities, business organization and many other places.

[top]

ODM Features for Handling Reference Data

ODM offers three options for handling reference data in rule authoring:

Option 1. Literals

The first option is to use literals.

For example, a rule author could enter or paste the string "FR" for the country France.

Literals can be used for both hierarchical and flat reference data. For example, you can enter "FR" and "Paris" for a rule where the country is France, and the city is Paris.

Limitations

• When using literals, the rules cannot be understood by business users and are difficult to validate. The value, and not the name of the value, must be used in the rule.

• Entering free text is inherently error prone due to the possibility of typing or copy and paste mistakes, when authoring rules.

• Using literals will result in poor adoption of rule authoring in Decision Center.

• The decision table editor cannot enforce gap and overlap checks.

[top]

Option 2. ODM Enumerated Domains

The second option is to use ODM enumerated domains.

A domain is useful in the case of short lists of flat data, such as a list of ISO3166 Country Codes. When the domain is created by a developer in the BOM, a rule author can to pick an item from a complete ordered list of name-value pairs in a rule.

When a domain is used in a decision table, the editor can enforce gap and overlap checks, which warn when all possible values are not covered, or one overlaps another.

Types of Domains

An enumerated domain can be implemented by a developer in any of the following ways:

• Static Domains - the domain is created directly in the BOM from an enumeration of static references, or indirectly enumerated type in an Java or XSD XOM.

• Dynamic Domains from Excel Spreadsheets - the domain created from data stored in an Excel file and dynamically added to the BOM by the ODM Excel domain provider.

• Dynamic Domains from External Sources - the domain is created from data from an external source, such as a database or web service, and dynamically added to the BOM using code based on the ODM APIs.

Limitations

Enumerated domains are a good solution for short lists of flat reference data. But they do have some drawbacks:

• Static domains are a poor choice as the domain data must be hard coded in the BOM or the XOM by a developer. Changing them always has a maintenance overhead.

• Static domains created indirectly from the XOM result in Hosted Transparent Decision Services (HTDS) result in fragile decision services. Adding an enumerated value in the XOM has a very real possibility of breaking service contracts with decision service consumers.

• Static and dynamic domains from Excel always duplicate reference data. Where the same reference data is used in multiple ODM projects, the data is duplicated across the projects. When consumers invoke the Decision Service, the consumer must duplicate the service reference data as they do not share the same data sources.

• Dynamic domains from external sources are difficult to implement and involve a developer writing and integrating custom code into Decision Center and Rule Designer.

• Domains cannot handle long lists of data or hierarchical data. They only provide half the solution.

Note : Duplication of reference data when using dynamic domains from Excel spreadsheets can be a problem in two ways: firstly, the data is duplicated in both the Decision Service consumer and provider; secondly, where the same reference data is used in multiple ODM projects, developers often copy and share Excel spreadsheets.

[top]

Option 3. Create ODM Value Editors

The third option is to use the ODM value editor feature.

A value editor is a custom UI Rule Designer and Decision Center graphical component, which a developer creates using code and ODM APIs. It is a good choice for long flat lists and hierarchical reference data. It allows a rule author to navigate complex data using UI features such as scrollable panels and filtering.

A value editor uses data from external sources. Like domains from external sources, the values are available in the completion menu of the rule editor. You can now use them when editing your rules.

Limitations

• Value editors are hard to implement.

• Values created in rules are literals, so gap and overlap checks cannot be enforced in decision tables.

[top]

Choosing the Right Solution

Implementing reference data in ODM can be challenging and the choices confusing.

Using literals is quick and dirty. Using static or Excel domains duplicates data and provides only half the solution. All can result in unreliable execution.

The only sure route to a successful implementation is to use dynamic domains from external sources and value editors.

Benefits

• External data provides a single source of truth which, when used by both Decision Service consumers and providers, will ensure correct rule execution and decision outcomes.

• Duplication of data can be avoided across ODM projects.

• Only value editors can handle long lists of flat or hierarchical data.

• Both value editors and domains are maintenance free. Changes to data sources are handled by database administrators, with domains being updated after changes using synchronization. Value editors retrieve changes to data at runtime.

[top]

The Starter Kit

Building value editors, and domains from external sources, is challenging. A steep learning curve is required as well as expertise in Eclipse Plugin development, JEE web application, javax.Swing, and Dojo Toolkit. Designing an overall solution presents additional challenges, while a poorly designed solution is difficult to maintain.

The Reference Data Starter Kit offers a one-stop solution for both ODM Rule Designer and Decision Center. It provides a simpler and more straight-forward way of integrating reference data into rule authoring.

The kit provides a new set of APIs built on top of the ODM APIs, a single configuration file and a Maven build.

The APIs allow you to:

• create single solutions for Decision Center and Rule Designer;

• have a centralized point of configuration for your domains and value editors;

• configure data source and web service connections, using a property file for Rule Designer and JNDI for Decision Center;

• control how domain and value editor data is displayed in ODM rules,

• control how values are translated into the ARL rule programming language; and

• minimize the development effort and reduce maintenance overheads.

RDSK domains support all the following data types: java.lang.String; java.lang.Character, java.lang.Integer, java.lang.Long, java.lang.Double, and all other primitive wrappers.

Both domains and value editors support localization.

Warning

It is better to have both dynamic domains and value editors in place at the beginning of your ODM project. You cannot begin rule authoring using free-text strings, and, at a later stage, retrofit domains and value editors without re-writing all the rules that use them.

[top]

Example : Dynamic Domains from External Sources and Value Editors

The example contains a set of domains and value editors that work both in Decision Center and Rule Designer, together with all the Maven projects, the data providers they contain, the RDSK configuration file and SQL data.

Example Dynamic Domains from External Sources

The example provides the following 3 domains:

• CountryTypes using ISO 3166 country codes;
• CurrencyTypes using ISO 4217 currency codes; and
• KnowledgeLevelTypes, a list of levels from one to seven.

CountryTypes and CurrencyTypes are of execution type java.lang.String. KnowledgeLevelTypes are of type java.lang.Integer. Together they illustrate how to handle different primitive wrappers.

[top]

Example Value Editors

The example provides 2 value editors for:

• Sector Industry Codes; and
• Harmonized System Commodity Codes.

The first shows you how to create a RDSK value editor for hierarchical lists of data with parent-child values Business Sector and Business Activity.

The second shows you how to create an RDSK value editor for a very long flat list of 5,300 commodity reference data values, and filter them.

It also shows you the above value editor working in an ODM Decision Table.

[top]

Example Build

The ODM installation provides 2 separate samples for dynamic domains from external sources and value editors. These are duplicated for both Decision Center and Designer.

Each sample has separate ANT builds and little code re-use. To use the samples you need to have an in-depth understanding of the ODM APIs and of a variety of technologies, such as Eclipse Plugin development, JEE web application, javax.Swing, Dojo Toolkit.

If you base your approach using the samples, you will find development challenging when dealing with a large number of domains and value editors, and the results impossible to maintain.

By contrast the Reference Data Starter Kit sample allows you to create all your domains and value editors for both Rule Designer and Decision Center as a single solution, in three projects, and with a Maven build.

The build consists of the following:

• a project containing common shared code for Rule Designer and Decision Center;

• an Eclipse plugin project for Rule Designer; and

• a project for repackaging of the Decision Center .ear or .war archives for either WebSphere Application Server or for Liberty Server respectively using the OMVP odm-rdsk-dc-maven-plugin.

You can adapt these to any of your own projects making your development simpler and easier to maintain.

[top]

Reference Data Server

The Reference Data Server is a WebSphere Liberty web application that can be used to support the rapid development of value editors and dynamic domains from external data.

The server has the following features:

• supports flat and hierarchical parent-child reference data, and their localization in different languages;

• provides a graphical interface that allows you to add, remove and modify data;

• acts as a tactical solution for developers, removing blockages for missing dependencies such as database and web services;

• imports existing dynamic domains from Excel spreadsheets facilitating domain migration from Excel to external data;

• is a useful tool for building POCs, showing dynamic domains from external sources and value editors in action.

The server is not intended for production environments, but as a tactical solution to facilitate rapid development and early rule authoring.

[top]

Modified Core Types (MCRT)

Modified Core Types Overview

Although ODM comes with in-built core types such as BAL numbers and dates, ODM rules applications often have a need for specialized types for authoring rules.

For example, financial institutions need currencies and percentages; companies working in the logistics sector need measurements such as weights and distances; scientific and medical companies need mass, volume, temperature, and pressure types.

The best approach to handling these requirements is to extend the ODM business rule language.

Benefits

• consistency, standardization, and reuse - build once and apply everywhere;

• "prevents users from combining incompatible value units when creating or editing rules" (ODM Documentation) - for example, without defining kilometre and euro core types, you could add 12 km and 5 euros together when authoring a rule!

You can also decorate the type with symbols such as $, £, €, and measurement units km, kg, etc. making them more readable.

Note

Although ODM comes with a range of in-built types (numbers, dates, strings, etc.), it does not provide more specialized types OOTB. For instance, ODM does not have duration, period time, or geospatial types - these are available in Decision Server Insights (see Time operators and Geographic objects and data).

To use these in ODM you must build and test them yourself.

[top]

Example : Euro and Percentage Types

For financial institutions and those working with money, the standard for representing money types is java.math.BigDecimal which can handle calculations with greater precision than doubles.

It is possible in ODM to handle these types and operations on them, in the following 2 ways:

• using BOM methods with arguments and verbalization; or

• directly in the rule using plain numbers and inline calculations.

But there are significant drawbacks to either approach. Using BOM methods is a 'quick and dirty' approach and does not prevent users from combining incompatible value units when editing rules.

Raw numbers and inline calculations make the rule harder to read and is more likely to be rejected by business users.

For example, the following ODM rule uses numbers in an inline calculation to express a percentage of a currency amount.

The same rule is much better expressed using the EuroCurrency and Percentage types, which are modifications of the ODM java.lang.BigDecimal core type:

This rule will be under business jurisdiction because it can be understood by the business. You also cannot perform incorrect operations when combining the two types together. For example, 50€ + 10% will result in 55€, and not 60€ as would be the case using raw numbers!

Modified core types also work in ODM decision tables.

[top]

MCRT Library

ODM Accelerator offers a library of specialized types such as geographic, time, and measurement types that you can reuse in your own projects. They will be useful for different industrial sectors (financial, medical, scientific, etc.), save you the time and effort of building your own, and provide standardized building-blocks for your business rules development.

[top]

Business Rules Decision Service (BRDS)

Decision Service Overview

In real life we make decisions using a case - sometimes called 'the case in question' - to which we apply knowledge in the form of a pre-defined set of rules, and then come to a decision. We do this consciously and intuitively, hundreds of times every day.

A decision service is the computerized automation of decision-making. For a service request a set of business rules - or ruleset - is executed, and response is returned.

ODM's OOTB mechanism for doing this is called Hosted Transparent Decision Services (HTDS). An HTDS is automatically created on ruleset deployment as a web service, with the service signature created from the ruleset XOM.

It is a simple and convenient approach to ruleset integration, but comes with significant limitations.

[top]

HTDS Limitations

A Hosted Transparent Decision Service is limited by the tight coupling between the HTDS web service and ruleset XOMs.

This is not a problem when existing rules are changed, or new rules are added, which do not require additional data. In this scenario the XOM is not modified and new rulesets do not alter the HTDS signature.

But when changes to the rules require new data, the XOM and the HTDS must change. This scenario impacts all HTDS consumers.

IBM Redbooks: Making Better Decisions Using IBM WebSphere Operational Decision Management

"... the definitions of the ruleset parameters evolve as the footprint and the complexity of the decision increases. We must enrich the data that is received by the decision web service to execute the rules. This enrichment cannot be performed from within the ruleset execution, as best practices of rule execution dictate that the rule engine should not perform any outside system call during its execution ... We can initially use the Hosted Transparent Decision Service (HTDS) deployment facility of the Rule Execution Server to quickly make the decision services available to their consumers. The HTDS can then be replaced by a custom web service that is enriching the data provided by the service input before performing the ruleset invocation."

Authors: Duncan Clark, Pierre Berlandier, Page 34.

Using Hosted Transparent Decision Service Interface (HTDS) in IBM Operational Decision Manager

"The beguiling ease of remote invocation of rulesets through web services exposed by HTDS tempts one to promote them as business services that can be used across several enterprise clients. However, very often the reality is that these web services should not be directly consumed by the enterprise client applications, but instead by a reusable decision service (see Related topics) that serves as a gateway. There are several reasons for this:

• The ruleset object model is likely to be different from the enterprise integration model, in keeping with best practices, and the decision service would have to perform model transformation and request enrichment, possibly by accessing external data sources, before invoking the rule engine.

• When invoking HTDS a ruleset path is known from the client, which strictly speaking is a violation of the business interface design in that the client knows that the service is a rule-based implementation.

• The desired granularity of the service operation, which is an important facet of SOA service design, can be different from the service signature exposed by HTDS. In fact, it is not uncommon to have multiple service operations at different granularity levels for the same ruleset.

For these reasons, HTDS typically should not be considered a reusable business decision service to be directly invoked by business rule clients, but instead a rule service to be invoked by service integration components (which we'll call business decision services) or by dedicated one-off clients such as BPM process tasks."

[top]

Decision Service Framework

The Decision Service Java framework is a durable solution, where ODM service consumers and providers are not tightly coupled and interact through a mediation layer.

The decision service controls and co-ordinates all interactions between consumers and providers. They in turn know only about the decision service and can vary independently of each other.

The framework components have the following responsibilities:

• web services provide stable service signatures for service consumers;

• the Rule Executor Manager:

  • handles all web service requests;

  • selects the Rule Executor to execute for the service request transparently;

• each Rule Executor:

  • maps the payload between the service request and the ODM Decision Service input;

  • handles data enrichment, allowing the data for rules to grow over time;

  • performs all data validation and error handling, which is better than handling it in the rules;

  • invokes the requested version of the ODM ruleset; and

  • maps the data between the ODM Decision Service output and the service response.

Each rule executor is specific to one or more versions of an ODM ruleset.

Using the Framework

The Rule Executor Manager is part of the BRDS API's. It automatically accepts registration of all rule executors and contains all the logic for determining the executor to use, and the ruleset version to execute. It needs no modification.

You must create each rule executor yourself, implementing the required interfaces. The implementation must perform all the tasks needed to be performed prior to the ruleset as well as process the outcome. Each executor automatically self-registers with the Rule Executor Manager on deployment.

The process of creating rule executors must follow the BPM diagram below.

The BRDS can be packaged as either an .ear or a .war archive and deployed on either WebSphere Application Server or Liberty Server.

[top]

Benefits Summary

• Facilitates full versioning of ODM Decision execution without impacting service consumers;

• Handles data validation, error handling and data enrichment allowing the data required for ODM rulesets to grow over time;

• Ensures the consistent execution of decisions, as consumers are not responsible for gathering the bulk of data needed to execute a decision;

• Provides clean separation of concerns, resulting in more maintainable code;

• Enables down-the-line refactoring of ODM rule applications; and

• Avoids vendor lock-in.

[top]

Example : Decision Service Example

[TBD]

[top]

SECTION 3 : EXAMPLES

Example : EU-Rent (EURT)

EU-Rent Overview

The EU-Rent Example from the Object Management Group's Semantics of Business Rules and Business Vocabulary has been selected to illustrate the features of ODM Accelerator. The example uses the SBVR specification to describe the following case study for a car rental company.

"EU-Rent is a (fictional) international car rental business with operating companies in several countries. In each country it offers broadly the same kinds of cars, ranging from ‘economy’ to ‘premium’ although the mix of car models varies between countries. Rental prices also vary from country to country. EU-Rent seeks repeat business, and positions itself to attract business customers."

SBVR is an excellent fit for ODM for the following reasons:

• SBVR's "Key words and phrases for logical formulations" (see Annex A - SBVR Structured English) is similar to ODM's in-built Business Action Language (BAL) ; and

• SBVR's structured business vocabulary is supported by the features of ODM Rule Editors;

Using ODM, SBVR and ODM Accelerator enables richer and more durable applications to be built. The resulting rules have greater transparency and accuracy.

[top]

EU-Rent Features

• Analysis Artifacts

[top]

• Software / Development Artifacts

All components can be deployed to IBM WebSphere Application and Liberty Server.

[top]

ODM Accelerator EU-Rent Features

• EU-Rent Business Rule Book

The EU-Rent Rule Book uses the default OOTB governance. It defines the fact models and business vocabulary which will be used in EU-Rent Rules, together with initial rules and their organization.

For example, below is the fact model for the Rental Request decision.

[top]

• EU-Rent Modified Core Types

The implementation of the EU-Rent Example uses the following financial and time unit modified core types in two libraries.

Financial Types

The following currency types are required for the current EU-Rent rules:

• Euro (EUR), US Dollar (USD), Canadian Dollar (CAD), Danish Krone (DKK), Norwegian Krone (NOK), Swedish Krona (SEK), UK Pound Sterling (GBP) and Swiss Franc (CHF).

These modify the ODM core type java.math.BigDecimal and have been decorated with the ISO 4217 currency code as a suffix, in preference to currency symbols, in order to avoid ambiguities.

[top]

Time Unit Types

The following time unit types are required for the current EU-Rent rules:

• RentalDay - a non-standard Rental Time Unit (RTU) defined by EU-Rent as "period that has duration '24 hours' and starts at the pick-up date-time of some rental"; and

• AgeYears - the age of a person calculated in years.

RentalDay is used in the calculation of rental overlaps, rental pricing, and rental duration. AgeInYears to determine if a person is qualified to drive a rental car.

[top]

• EU-Rent Command Line Tools and Maven Plugins

No new command line tools or Maven plugins are needed for EU-Rent. The existing ODM Accelerator example tools and plugins are sufficient.

EU-Rent Command Line Tools

• ODM Archives Deploy Maven Tool
• Rule Designer Build RuleApp Deploy Decision Server Tool
• Decision Center Batch Test Deploy Tool
• Rule Designer Build RuleApp Deploy Maven Tool

EU-Rent ODM Maven Plugins

• RuleApp Builder Maven Plugin
• Decision Runner Maven Plugin
• Repackage Decision Center Archive Plugin
• Rule Designer RuleApp Deploy Decision Server Plugin

[top]

• EU-Rent Reference Data

From analysis the following reference data has been identified for Decision Center rule authoring:

Dynamic Domains from External Sources

Below are the 27 domains for flat short-list reference data necessary for EU-Rent rule authoring:

For speed and consistent development, the domains are implemented using RDSK API's and configuration.

All data is retrieved dynamically from the EU-Rent database via provided services, and synchronized in Decision Center and Rule Designer.

[top]

Value Editors

All hierarchical and long-list reference data is implemented using value editors in both Decision Center and Rule Designer.

Below are 2 examples of the EU-Rent value editors that are necessary for EU-Rent rule authoring:

• EU-Rent Car Model value editor with 2 levels of selection:

• EU-Rent Branch value editor with 3 levels of selection:

For speed and consistent development they are implemented using RDSK API's and configuration. All data is retrieved dynamically in real-time via web services from the EU-Rent Oracle database.

[top]

• EU-Rent Business Rule Decision Service

The EU-Rent Business Rule Decision Service uses the standard Rule Executor Manager to manage service requests for decision service execution as per the Decision Service Framework. For each request a versioned rule executor has been created as per the framework change management process.

For example, a series of versioned RequestForRentalExecutor classes have been created for the Request For Rental Decision Service. Each one delegates all pre-processing and post-processing to a BeforeHandler and AfterHandler class before carrying out ruleset invocation.

The initial Decision Engine is ODM, but this may easily be swopped out at a later stage for another engine, technology, or simply replaced by code.

[top]

Other Examples

Each ODM Accelerator feature comes with one or more examples showing how to use the component. Each example contains the source code and can be built using Maven.

Here is a list of the current examples available:

• RDSK Catalog Reference Data Server
• RDSK Value Editor and Dynamic Domains Example
• RuleApp Builder Maven Plugin
• Decision Runner Plugin
• Repackage Decision Center Archive Plugin
• Rule Designer RuleApp Deploy Decision Server Plugin
• ODM Archives Deploy Maven Tool
• Rule Designer Build RuleApp Deploy Decision Server Tool
• Decision Center Batch Test Deploy Tool
• Rule Designer Build RuleApp Deploy Maven Tool

[top]

SECTION 4 : GETTING THE ACCELERATOR

Source Code Repository

The source code is held within this Altassian BitBucket GIT repository. The code is available to selected end clients and can be cloned from a GIT repository. The source code is modular and can be cloned in its entirety or as individual modules.

All ODM Rules Accelerator projects are easily built from a single Maven command from a root pom.xml:

[top]

Software Requirements

• ODM 8.9.2, 8.10.x
• Application Servers - WebSphere Liberty Server, WebSphere Application Server 855
• Java 8, JEE 6
• Maven 3x
• JUnit 5

More specific requirements and usage are contained in the ReadMe.me in the GIT source code of each component.

[top]

Further Information

In addition to ODM Accelerator, a wide range of consultancy services on IBM ODM and BPM are available. Please contact me for further information.

peterwarde@rulearchitect.com

Linkedin profile

You can read the following articles on IBM Operational Decision Manager by him:

• Building a Better Rule Application Architecture - also recommended on IBM Business Automation Community : Decision Management Best Practices

• Using Reference Data for Rule Authoring in IBM Operational Decision Manager

• 5 Tests for High-Quality Rules in IBM Operational Decision Manager

Third Party Resources

• IBM ODM Dev

• IBM Cloud Pak for Business Automation - Assets for the IBM Cloud Pak for Business Automation offering

[top]