Best practices for designing and implementing decision services, Part 3

Integrating IBM Business Process Manager and IBM Operational Decision Manager RESTful protocol


Content series:

This content is part # of # in the series: Best practices for designing and implementing decision services, Part 3

Stay tuned for additional content in this series.

This content is part of the series:Best practices for designing and implementing decision services, Part 3

Stay tuned for additional content in this series.

In this Part 3 of the decision service implementation article series, we cover how to expose decision services using RESTful protocol and JSON payload. A potential use case, for this type of integration, could be a data validation ruleset called from a BPM coach using Ajax and dojo/request/xhr, but the RESTful protocol can also be used for integrating mobile applications that calls a decision service. As presented in Part 1, the Java™ implementation of the decision service brings all the needed flexibility to support different decision service operations, payloads, and protocols.

We will review a typical project using both Java and rules projects by applying clear architectural separation of concerns. We will also review the Rule Business Object and Service Exposition Model patterns and how to leverage JAXB to expose JSON easily, and the Java implementation of the decision service. To make a HTTP POST from IBM BPM Standard Edition, we propose a simple Java integration that you can use as part of a service in a toolkit. Finally, a simple technique is presented to support a Java JSON class as an ODM eXecutable Object Model.

RESTful overview

RESTful resource is obviously an interesting approach to expose a decision service. RESTful has its advantages, and we are seeing more and more deployments adopting this protocol instead of using SOAP over HTTP, especially when services have less than strong quality of service requirements. There are articles comparing the value of RESTful versus SOAP so it goes without saying that SOAP decision services are dead, it is easy to expose RESTful decision service using JAX-RS implementation. As explained in previous articles, most of the decision services in an SOA deployment are stateless, are loosely coupled for reusability, cache reference data locally, and need to support different format like JSON, XML, and Java. HTTP is a simple protocol to support on the server side. With Web 2.0 applications, doing Ajax calls from the user interface and using JSON and RESTful are considered a standard programming model.

Often a business rule application includes a graphical user interface with the content controlled by rules: dynamic form and questionnaire service are simple to implement with JSON, Ajax, RESTful, and IBM ODM. Rules control the HTML content by taking into account the business data gathered during the previous interaction with the human. The user interface can be done using the IBM BPM coach technology or any Web 2.0 web application. The Javascript™ within the HTML page is doing HTTPAsynchronousRequest and dojo/request/xhr to call the remote decision service and process the response as a JSON object or JSON array.

As a standard approach, the decision service is not modifying data in the system of record, this is the responsibility of the consumer to commit such changes if needed. The rules in the decision service will most likely modify the data graph it receives: adding decision, setting default value, inferring data values, modifying data attributes, adding list of errors, comments, and so on. This characteristic fits well in a RESTful philosophy.


One of the first challenges is to define the resource, and then map the verb used to define decision service such as validate, check, and assess to something using nouns. For example, a common ODM use case is to validate data entered in a set of screen forms before committing them to a system of record: the validateData operation as part of a main business entity component (for example, claim module, customer ticket request module, loan application, and so on) is now transformed as resource name within a resource, such as POST /claims/{id}/validation or POST /customerRequests/{id}/validation. For product eligibility, the resource URL is /customerRequests/{id}/eligibleProducts.

Transforming to a noun is more of a RESTful best practice. You an avoid using it if it makes more sense to include a verb in the resource URI. For a loan application underwriting system, the Java code to define a resource, using JAX-RS annotation, may look like the one shown in Listing 1.

Listing 1. JAX-RS annotated Java class with one of the decision service operations
publicclass AusServices {

    public LoanResponse assessLoanEligibility(LoanApplication loanApp) {
          // delegate to a rule processing service

The JAX-RS annotations define the main resource path (/services), the specific verb for the decision service operation assessLoanEligibility (/loan/assessment), and the media type to use (JSON) for both the input parameter and the output result.

To expose a decision service as RESTful, the implementation is straightforward. Let's assume we organize the projects by following a clear separation of concern for best practices. You should have (see Figure 1):

  • A Java project for your rule business object model (RBO) and the service exposition model (see Part 1).
  • A Java project for your pure Java decision service implementation. This project is reused for unit testing and within the web service project that defines the different protocols to access decision service.
  • A set of rule projects, one for the shared BOM entries and multiple rule projects to manage the rules and build rulesets.
  • A Java project for unit testing your rulesets. The test cases can be done using the decision service or the rule engine API directly.
  • A Java project (web services) to expose the decision service in the different protocol: SOAP or RESTful and with different decision service operations.
Figure 1. Different projects for different needs
Different projects for different needs
Different projects for different needs

Let's start by reviewing the model project.

Rule Business Object model

As presented in Part 1 of this series, the information model has different views and is adapted according to the semantic of the SOA service. Each service has at least one Service Exposition Model (SEM) and one Service Implementation Model (SIM). When the business service is a decision service, the SIM is also called rule business objects (RBO). This term was used for many years to clearly communicate with the business analysts and rule owner. This model is derived from the business rule statements, adapted for powerful rule processing and readable by business users. The rule business object model is a view of your information model for rule processing. It contains utility and behavioral methods, is Java based, improves rule authoring experience, and improves the rule processing execution time.

To develop such model, ODM developers and analysts use the rule expression as modeled during the rule discovery and analysis tasks (see Figure 2). The RBO is defined top down by the rule analyst by analyzing the rule statements and by developing a fact model and an object oriented model. The RBO is implemented using Java and JAXB annotations.

Figure 2. From Rules to RBO and SEM
From Rules to RBO and SEM
From Rules to RBO and SEM

The application architect defines the decision service contract and interface characteristics, which includes the Service Exposition Model (SEM) definition. He also implements the Java-based decision service, which uses the SEM and the RBO models. It is possible to leverage the service exposition model as is as RBO. Classes that do not have a lot of logic are very stable and simple, and part of the canonical model may be used as-is ("Address" or "Comment" definitions are such classes). Most likely, main business entities, such as LoanApplication, Claim, and PurchaseOrder, have a simple SEM definition, which different consumers can create easily. RBO (LoanApplicationRbo) with more complex data model and behavioral methods are used for rule processing. For example, the credit history records for each loan co-borrowers are used to assess the risk to underwrite the loan, and are not exposed as part of the SEM. The wrapper design pattern can be used. Listing 2 shows an example of the RBO class wrapping the loan application SEM, but adding specific attributes for the rule processing, such as total household income, credit reports, and so on.

Listing 2. RBO wrapping a SEM class
publicclass LoanApplicationRBO {
    // this is a wrapper
	protected LoanApplication loanApplication;
	protected String status;
	protected String documentationType;
	protected Map<String,CreditHistory> creditReports;
	protected Set<BorrowerRBO> borrowers;
	protecteddouble totalHousholdIncome;

In this context, it is also a good practice to make some of the loan application attributes immutable if you know that the rules will not modify them. Getters are delegating to the corresponding getter on the SEM class. This approach makes the rule simpler to read as it reduces the logic to navigate within the complex data graph.

public Property getProperty() {
	return getLoanApplication().getProperty();

The Java classes for the RBO can also be annotated to control the verbalization of the BOM class. Here are some examples of such annotations to avoid exposing attributes in the BOM or to provide translation.

Map <String,MetaData> metadata;

Decision service implementation

The decision service Java implementation is very flexible to integrate data caching and to load complementary data elements to complete the data graph needed for rule processing. It can also be easily integrated within a Junit and Java-based test framework, or integrated in a Java-based web service to expose it in different protocols, such as SOAP, RESTful, EJB, JMS, and so on. Decision services are service operations in bigger components, such as LoanApplicationComponent, as shown in Figure 3.

Figure 3. Business services for the LoanApplicaion with decision service operations
Business services for the LoanApplicaion with decision service operations
Business services for the LoanApplicaion with decision service operations

The assess loan eligibility method first transforms the SEM to the RBO model, enriches the data model with credit history records, passes reference data as rule set parameters, and then delegates to a rule processing class, which uses the ODM RES API. The loan eligibility response returns the EM objects. The code may look like Listing 3.

Listing 3. Internal processing within the decision service
publicclass LoanApplicationComponent implements LoanApplicationService {

	RuleProcessing rp = new RuleProcessingImpl();
   public LoanResponse assessLoanEligibility(LoanApplication loanApplicationSEM ) {
	// 1- transform the SEM to RBO
	LoanApplicationRBO loanApplicationRbo=ModelTransformer.transformLoanApplication(loanApplicationSEM );
	// 2- may be add steps to complete the data graph before rule processing
	// 3- delegate to rule processing
	LoanResponse respRbo= rp.assessLoanEligibility(loanApplicationRbo);
	// 4- transform RBO to SEM
	LoanResponse respSEM = ModelTransformer.transformLoanRespRBOToSEM(respRbo);
	// 5- return SEM
	return respSEM;

The rule processing uses the ODM RES API and the POJO session factory when deployed on WebSphere or any application server, or uses the J2SE session factory when running in standard JVM, like the one used for unit testing. In fact, it is possible to define which factory to use by integrating a properties file. The same code runs on the server and on the unit test or non-regression test environment. The classes shown in Figure 4 present this pattern.

Figure 4. Reusable classes for rule processing
Reusable classes for rule processing
Reusable classes for rule processing

Exposing the service as a RESTful resource

Back to the RESTful resource definition, this one is defined as part of another Java project, the web services project. The code presented is using a WebSphere deployment, leveraging the Apache Wink JAX-RS implementation. First, the resource class is a POJO class using JAX-RS annotation (see the code example in Listing 1). The second element is a implementation class, which lists the REST resource classes exposed within the deployed web application (Listing 4).

Listing 4. REST resource classes in deployed web application
publicclass AusApplication extends {

	public AusApplication() {]

	public Set<Class<?>> getClasses() {
		Set<Class<?>> classes = new HashSet<Class<?>>();
		return classes;

The web.xml file needs to specify which application class to use, so that the IBM WebSphere JAXRS REST servlet can delegate to the appropriate resource when the consumer points to one of the resource URLs (Listing 5).

Listing 5. Delegate to appropriate resource

As illustrated in Listing 1, the consumer and producer payloads are defined as JSON. To support this, the only development task to do is to annotate the SEM classes with a JAXB annotation as shown in Listing 6.

Listing 6. Annotate SEM classes with a JAXB annotation
@XmlRootElement(name="LoanApplication" )
publicclass LoanApplication {
	protected String mortgageType;
	protected String purpose;
	protectedint numberOfMonths;

Figure 5 shows the workspace configuration with a zoom to the web service project.

Figure 5. A real life code organization for decision service implementation
A real life code organization for decision service implementation
A real life code organization for decision service implementation

This web service project can include SOAP and JAX-WS decision services implementation, but it can still use the same rule processing delegation. This is powerful as different operation signatures can be defined and different protocols supported for the same ODM ruleset.

The packaging of this is a simple WAR/EAR, which includes the SEM and RBO model in a JAR, the service in a JAR, the ODM session API, and the web service classes. The ANT target definition shown in Listing 7 illustrates such packaging.

Listing 7. ANT targets to build your EAR and WAR
<target name="war" depends="" description="generate the Web Service WAR">
<war destfile="${dist}/${}.war" webxml="${webinf.dir}/web.xml">
  <lib dir="${executionserver.home}/lib">
	<include name="jrules-res-session-java.jar" />
  <lib dir="${parent.home}/lib">
	<include name="MyLendingModel*.jar"/>
	<include name="MyLendingServices*.jar"/>
   <fileset dir="${web.src.dir}" excludes="**/application.xml" includes="**/*.*">

<target name="ear" depends="" description="generate the Web Service EAR">
	<ear destfile="${dist}/${}.ear" appxml="${web.src.dir}/META-INF/application.xml">	
		<fileset dir="${dist}">
			<include name="${}.war" />

The packaged EAR should be deployed on the Decision Server where the XU deployment resides (Listing 8). This is done using WebSphere Enterprise Application deployment from the IBM Admin Console. The RES API factory needs access to the resource adapter using the JNDI named specified during the RES installation. Those resource references are defined in the web.xml file and then mapped to the existing JNDI name during the EAR installation, as shown in Figure 6.

Listing 8. Resource reference to XU connection
Figure 6. Mapping JNDI names
Mapping JNDI names
Mapping JNDI names

Once deployed, the last step is to get a simple Java client that calls the RESTful service. Using this approach, you can quickly validate the SOAP or RESTful services. The code is done in a Junit class and uses the Apache Wink client API.

Listing 9. Java client calling RESTful service
// prepare the loan application
org.apache.wink.client.RestClient client = new RestClient();
// get the resource from the URL
Resource resource = client.resource("http://"+serverName+":"+portNumber+
// do a HTTP POST with the loan application
LoanResponse response = resource.accept(MediaType.APPLICATION_JSON).post(LoanResponse.class,

This code works fine using the WebSphere jax-rs thin client JAR that you can find in: <was.home>/runtimes/


ODM version 8.5 offers a new capability to expose a ruleset as a RESTful service using the XML payload. To access the Web Application Description Language (WADL), an administrator uses the RES console and goes at the ruleset level to view the HTDS description file. Selecting the REST service type, and then the View button brings the WADL in a Web browser, as shown in Figure 7.

Figure 7. Accessing REST WADL description of a ruleset
Accessing REST WADL description of a ruleset
Accessing REST WADL description of a ruleset

As of version 8.5, JSON is not supported. The resource path includes the rule application and ruleset name. For example, to get the request XML structure to perform a HTTP GET on the following URL, use this: http:<hostname>:<portNumber>/DecisionService/rest/v1/MyLendingRuleApp/1.0/MyLendingValidationRules/1.0/xml.

The HTTP POST to this URL, http:<hostname>:<portNumber>/DecisionService/rest/v1/MyLendingRuleApp/1.0/MyLendingValidationRules/1.0, performs the ruleset execution. The code shown in Listing 10 processes a loan application.

Listing 10. Process loan application
RestClient client = new RestClient();
Resource res = client.resource("http://"+serverName+":"+portNumber+
LoanResponse resp= res.accept(MediaType.APPLICATION_XML).post(LoanResponse.class,loanApp);

It is important to note that HTDS generates a model that exposes all the classes and, in particular, the RBO classes. This is not what we would like to do as we want our ruleset to be reusable. We want to use a model, the SEM, which is easily consumable. Therefore, the RBO with the wrapper, including the SEM loan application, does not work with HTDS because the data elements are not populated well. HTDS assumes that the consumer can send all the data.

BPM server script calling the RESTful decision service

From a BPM integration point of view, the approach is quite simple. We just need to have a BPM "service" doing an HTTP POST operation to the RESTful service at this URL:


Process Designer does not have this capability in the System Data toolkit, it only does an HTTTP GET. The idea is to add one Java integration into a toolkit, so that HTTP POST can be done. The implementation can leverage Apache Wink or Apache HttpClient. The example shown in Listing 11 uses HttpClient, which version 3.1 can be found in <odm.home>/executionserver/lib as commons-httpclient-3.1*.jar. As the API changed a little bit, we will use the HttpClient version 4.3.1 API to implement such a wrapper. The API is easy to use and in the simplest case, you need four classes to perform the work:

  • HttpClient
  • HttpPost
  • HttpEntity
  • HttpResponse

For readability reason, the following code shown in Listing 11 does not address exception management.

Listing 11.Using HttpClient
// post to the URL of your RESTful verb
HttpPost httpPost = new HttpPost(url);
// create an entity to carry on the payload between the client and the server
HttpEntity e =  new StringEntity(jsonAsStr, ContentType.create(ContentType.APPLICATION_JSON.getMimeType(),Consts.UTF_8));
// define the http client
CloseableHttpClient httpclient = HttpClients.createDefault();
// execute the call and process the response.

As you can see, the entity to send is a string representing the JSON object. Therefore, the API we could present to Process Designer is simply to ask for the URL and JSON as a string:

public static String postJSONObject(String url, String jsonAsStr) {

This code is defined in a BpmHttpClient class, packaged in a JAR, and then uploaded as server file in a toolkit. You can upload the HTTPCLIENT JARs too, or place them in a BPM endorsed library where shareable JARS are placed.

The last step is to define an "Integration Service", add a Java integration, and configure the method to call on that integration, as shown in Figure 8.

Figure 8. Defining a Java integration in Process Designer to call the HTTP POST method
Defining a Java integration in Process Designer to call the HTTP POST method
Defining a Java integration in Process Designer to call the HTTP POST method

The first parameter is the URL and the second is the JSON object to be sent to the rule execution. This is the root element of the data graph.

The value of such a JSON mapping may be questionable when XML can be used, but it is possible to co-host the decision service on Process Server, expose it as a RESTful service, and then call it from a coach control using a dojo.request API. This is a natural way to apply business rules in the user interface, without hard coding the rules in Javascript. Data validation or rule based dynamic generation of the HTML elements can be done with this approach. Having the decision service deployed on a remote server (not the process server one) and calling such a service using XMLHttpRequest will violate the same origin policy, which can be avoided using Cross ORigin Sharing (CORS) or JSONP mechanisms on both the client and the server sides.


This section describes how to define a BOM on a unique XOM class that is a JSON object. You can find the JSON API in <odm.home>executionserver/sample/restapi/lib/JSON4J.jar.

Once you have created your rule project, you need to reference the Java executable model in the properties of the project as shown in Figure 9.

Figure 9. Setting the reference to the dependent JARs
Setting the reference to the dependent JARs
Setting the reference to the dependent JARs

Next, you need to create a BOM entry without any reference to an existing XOM (Figure 10). This is a top down definition of the rule business object model.

Figure 10. Defining a BOM entry as top down
Defining a BOM entry as top down
Defining a BOM entry as top down

In the BOM editor, you can add packages and classes. For this example, we added Customer, LoyaltyProgram, Product, and MarketingOffer classes (Figure 11).

Figure 11. Adding some business classes
Adding some business classes
Adding some business classes

To make this work, you need to map each BOM class to the execution class,, using the BOM to XOM mapping field (Figure 12).

Figure 12. Mapping BOM class to XOM class manually
Mapping BOM class to XOM class manually
Mapping BOM class to XOM class manually

Then, for each BOM class, you add an attribute of any basic type and define the setters and getters using the JSONObject API.

Figure 13. Defining a getter for a simple string attribute
Defining a getter for a simple string attribute
Defining a getter for a simple string attribute

Table 1 illustrates some of the mapping for the common attribute types.

Table 1. Common attribute types
<getter language="irl"><![CDATA[
    return (String)this.get("name");
<setter language="irl"><![CDATA[
<getter language="irl"><![CDATA[
    int v=((Integer)this.get("rewardPoints")).intValue();
return v;
<setter language="irl"><![CDATA[
   this.put("rewardPoints",new Integer(value));
Object, like the Loyalty Program for a customer
<getter language="irl"><![CDATA[
  return ( this.get("program");
<setter language="irl"><![CDATA[        
Products of the customer in a list
return (

The mappings are defined in a file with an extension of ".b2x" under the BOM folder of your rule project.

Using the BOM to XOM mapping, you can map to any type. Complex objects are mapped as JSONObject. Similar to a customer who has one reference to a loyaltyProgram, the attribute is a JSONObject and a collection of objects is mappped to JSONArray. The definition of the product list for the customer looks like Figure 14.

Figure 14. Customer has a list of products the company sells
Customer has a list of products the company sells
Customer has a list of products the company sells

What is interesting is that in the BOM editor, you can specify what type of collection it is. In this case, it is a collection of the BOM class products. So now, let's map it to a JSONArray. Listing 12 shows an example of the rules.

Listing 12. Examples of rules
 set 'a product' to a product in  the products of 'the customer';
 the status of the program of 'the customer' is "Gold"
 and the name of 'a product' is "Printer"
 print "Bravo bill";
 set the name of 'the offer' to "Thank giving gift";
 set the value of 'the offer' to 50;

The test case to validate this rule creates a set of JSONObjects shown in Listing 13.

Listing 13. Set of JSONObject
publicstatic JSONObject buildPersonGraph(){
    	// the customer
    	JSONObject c = new JSONObject();
    	c.put("name", "Bill");
        // his loyalty program
    	JSONObject l = new JSONObject();
    	l.put("name", "SmarterRetailFidelity");
    	l.put("rewardPoints", 50000);
    	l.put("status", "Gold");
    	// the products he owns
    	JSONArray products = new JSONArray();
    	JSONObject p = new JSONObject();
    	p.put("name", "Printer");
        JSONObject p2 = new JSONObject();
    	p2.put("name", "Printer");
    	c.put("products", products);
    	return c;	

The JSON representing the customer looks like this:


And the output of the rule execution looks like this:

{"name":"Thank giving gift","value":50}

The decision service operation is becoming quite generic and looks like this:

Public JSONObject validateLoanApplication(JSONObject loanApp)

You can also use this approach with the Service Data Object (SDO), which is the technology of choice when doing BPM Advanced and SCA programming in IBM Integration Designer. Instead of marshalling to XML to do a remote call, you can integrate ODM in the service layer where the SCA runtime executes and performs SDO end-to-end. The main issue with this approach is the heavy work to be done on the BOM to XOM mapping. In fact, it is possible to automate the generation of the .bom and .b2x files by parsing an XML schema, the definition schema of the complex type in BPM Process Designer. You can use tools like Java Emitter Transformer or Freemarker to do that.


Exposing and implementing a decision service is not just using a product feature blindly. You need to spend time to design reusable components and reusable decision service operations, respecting all the best practices developed over the years of SOA adoption. This article presented an approach that brings the most flexible solution to code such decision services by using Java and the ODM ruleset. A ruleset should be exposed with different decision service operations, with different payloads, signatures, and even protocols. The ruleset parameters should not be the unique definition of the service contract. It is possible to use RESTful to expose decision service, as well as SOAP over HTTP or Java serialization and EJB. JAXB implementation is very efficient now to do XML to and from Java, but also JSON to and from Java. Finally, even if this is not used often and also to avoid any unmarshalling, you can use SDO or JSONObject as XOM classes.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Business process management, WebSphere
ArticleTitle=Best practices for designing and implementing decision services, Part 3: Integrating IBM Business Process Manager and IBM Operational Decision Manager RESTful protocol