In previous blog posts in this series, More rapid business insight with ODM and CICS integration and Emitting CICS Events for ODM Decision Server Insights, we described the advantages of integrating events from CICS applications with Operational Decision Manager (ODM) Decision Server Insights, and introduced a scenario based on the CICS Catalog Manager example application. This scenario uses events emitted to ODM Decision Server Insights when catalog orders are placed, to look for a pattern where a customer has ordered more than three items, and to offer the customer a discount voucher to reward their loyalty.

In the previous post, we showed how to set up CICS Transaction Server for z/OS (CICS TS) to emit an event whenever an order is placed, and in this post we will show you how to define a solution in Insight Designer that will look for examples of loyal customers who can receive a discount voucher. The number of items that triggers a discount (3), and the time period within which those orders must be received (4 minutes), have been chosen so that the scenario is easy to demonstrate and test. In a more realistic scenario, the customer would be allowed a longer time period to accumulate their orders, and probably they would also be required to order more items before they would qualify for a discount.

ODM Decision Server Insights

IBM ODM Advanced Decision Server Insights (DSI) is a highly available event-driven solution for transactional workloads that combines change detection capabilities with decision making and business analytics. Decision Server Insights has a very rich and intuitive rule language that allows users to write their business logic in natural language, providing nontechnical users with the ability to directly influence and control the situations that represent opportunities or risks within the business.

DSI has four key concepts that enable it to sense interactions across a business, detect situations in real time, make a decision, and then act. The concepts are Events, Entities, Agents and Context.

Events
An event for DSI is a machine readable description of something that has happened in the real world.

Entities
Events are typically correlated with an entity. For example, “a change of address event is related to a customer”. The event represents a real world change for the customer entity.

Agents
Agents are units of business logic that subscribe to events and may detect situations for their referenced entity, also known as the bound entity. They contain the logic that determines if a situation has occurred and decide the actions that occur, such as updating the bound entity or emitting another event.

Context
DSI can collect contextual information from a wide range of sources and events over a period of time. The contextual information can include the state of the bound entity, a history of events received over a period of time, global information across the entire system and scores calculated by predictive scoring services.

Insight Designer is the DSI development environment in which users design and build their solutions. It is an Eclipse-based tool that provides access to the natural language capabilities that make DSI such a powerful and flexible event processing platform.

For more information, see: ODM Advanced – Decision Server Insights – Technical Overview

Setting up ODM Decision Server Insights to consume CICS events

The steps involved in setting up Decision Server Insights to consume events from CICS, are as follows. Further details of these steps, illustrated using the ‘Catalog Order’ event and user loyalty scenario, are shown in the next section.

  1. Open Insight Designer.
  2. Create a Solution Project to contain the basis of the Insights solution. This step also creates a Business Object Model (BOM) project that is used to describe the business model.
  3. Import the event schema, as exported from CICS, into the BOM project. This defines the type of events to be consumed by the solution.
  4. In the BOM Project, create a Business Model Definition file to define the entities required by the solution.
  5. Create a Rule Agent Project to contain the rules that detect situations of interest.
  6. Define connectivity in the Solution Project for the events that are emitted from CICS.
  7. Deploy the Solution to a running Insight Server, to start receiving and processing events from CICS.

Catalog User Loyalty Scenario: Completing the scenario

In the previous blog post in this series (Emitting CICS Events for ODM Decision Server Insights), we walked through the steps in CICS to define and emit the ‘Catalog Order’ event used in this scenario. The scenario uses these events, which are emitted to ODM Decision Server Insights each time a catalog order is placed, to look for a pattern where a customer has ordered more than 3 items, and to offer the customer a discount voucher to reward their loyalty. In this section, we show how to set ODM Decision Server Insights up to consume and process the ‘Catalog Order’ events.

Step 1: Create a Solution Project

Start Insight Designer (see https://www-01.ibm.com/support/knowledgecenter/SSQP76_8.8.0/com.ibm.odm.distrib.install/starting_topics/tsk_start_open_rule_designer.html?lang=en). Create a solution project, or use an existing solution project, to contain the basis of the Insights solution for this scenario. The solution we use in this example is called OrderSolution. When you create a solution project, you will be prompted to create an empty Business Object Model (BOM) project that is used to describe the business model.

Step 2: Create a Business Object Model for the event by importing its schema

Click on OrderSolution in the Solution Explorer view, then in the Solution Map view click ‘Import event / entity types from XSD’. In the Import wizard, click on Select External XSD and select the Catalog_order DSIE event schema exported from CICS Explorer. The schema is interpreted by the wizard as shown in Figure 3.1.

Figure 3.1: Importing the schema for the Catalog_order events
Figure 3.1: Importing the schema for the Catalog_order events

We import a .xsd file that conforms to the Decision Server Insights event schema format and matches the Catalog_order CICS event. The schema as exported from CICS Explorer is as shown below in Figure 3.2.


   <?xml version="1.0" encoding="UTF-8" ?>
   <schema elementFormDefault="qualified"
     targetNamespace="http://www.ibm.com/prod/cics/Catalog_order"
       xmlns="http://www.w3.org/2001/XMLSchema"
       xmlns:m="http://www.ibm.com/prod/cics/Catalog_order">

     <element name="Catalog_order" type="m:Catalog_order" />
     <complexType name="Catalog_order">
       <annotation>
         <appinfo source="http://www.ibm.com/ia/Annotation">
           <event elementName="Catalog_order" />
         </appinfo>
       </annotation>
       <sequence>
         <element name="cics_usertag" type="string">
         </element>
         <element name="cics_networkapplid" type="string">
         </element>
         <element name="cics_timestamp" type="dateTime">
           <annotation>
             <appinfo source="http://www.ibm.com/ia/Annotation">
               <timestamp />
             </appinfo>
           </annotation>
         </element>
         <element name="cics_bindingname" type="string">
         </element>
         <element name="cics_capturespecname" type="string">
         </element>
         <element name="cics_UOWid" type="string">
         </element>
         <element name="Charge_department" type="string" >
         </element>
         <element name="Item_ref" type="string" >
         </element>
         <element name="Quantity_required" type="decimal" >
         </element>
         <element name="User_id" type="string" >
         </element>
       </sequence>
     </complexType>
   </schema>

Figure 3.2: Schema for the Catalog_order event in Decision Server Insights format

After the import is finished, you can find the event in a business object model (BOM); see Figure 3.3. The elements or data items with names prefixed by ‘cics_’ are standard contextual information which are included in all CICS events. Elements or data items without the ‘cics_’ prefix are specific to this event type.

Figure 3.3: Business Object Model created from the Catalog_order event schema
Figure 3.3: Business Object Model created from the Catalog_order event schema

Step 3: Create an entity and event to model the scenario

To detect any situation within Decision Server Insights, the system requires a model that describes events and entities vital to the situation that is being detected. Events represent messages in a business system, a notification that “something” has happened or as an action for another system to execute. Entities represent an artifact in the business that the user wants to detect situations around. Entities contain the state, and are used to provide the contextual information, that feeds into detecting a situation. In our example, our entity is the catalog user and our events are the Catalog_order event emitted from and a discount event.

Upon arrival of a Catalog_order event, a catalog user entity will be created for each user who orders from the catalog, and will be updated upon each arrival of an event which has the corresponding user identifier. Depending upon the business logic, Decision Server Insights may emit a discount event for another system to execute.

If a Business Model Definition (BMD) file has not yet been created in the BOM project, click on ‘Define events and entities’ in the Solution Map to open the BMD file creation wizard. Specify a package and name for the model file; in this example, ‘order’ was used for the package name and BusinessModel for the BMD.

Open the new (or existing) BMD file to begin defining the business entity that will represent the catalog user. Type the following into the editor to define the user business entity:

a user is a business entity identified by a user id, 
with an item ref, an order quantity (numeric), a time ( date & time ) .

Note that this is formatted for you by Insight Designer as you type, as shown in this screenshot:
CICSDSI_fig3_4a

In the solution, we would like to issue a discount; therefore we need a discount event in the business model:

a discount event is a business event time-stamped by a discount time.
a discount event is related to a user. 
a discount event has a user id.

Figure 3.4 shows the user entity and discount event defined in the Business Model.

Figure 3.4: Business Entity for a user
Figure 3.4: Business Entity for a user

Note that each user who places an order from the catalog will have a unique user id, which has to be a string as required by Decision Server Insights.

You can find the newly defined business entity User and the DiscountEvent in the solution project as shown in Figure 3.5.

Figure 3.5: Business model in the OrderSolution project
Figure 3.5: Business model in the OrderSolution project

Step 4: Add a rule agent and action rule for the user business entity

Our next step is to add a rule agent that contains the business logic for the user business entity. Click on ‘Add rule agent’ in the Solution Map to create a Rule Agent Project. Type in the following in agent.adsc.

'OrderSolutionRules' is an agent related to an user ,  
processing events :
- catalog order , where this user  comes from the user id of this catalog order , with a horizon of 4 minutes
- discount event , where this user comes from the user id of this discount event, with a horizon of  5 minutes

Much of this will be completed and formatted for you by Insight Designer: at each stage, it will prompt you with appropriate selections for what should come next, and will format the text, so that it will look something like this:
CICSDSI_fig3_6a

In OrderSolutionRules, the agent links the user business entity to the Catalog Order event. The user_id of the catalog order is used to identify the user. The identifying field has to be of string type, as required by Decison Server Insights. The agent also links the discount event to the user business entity. The identity userID of user will become the userId of the discount event.

Next we will add an action rule for initializing the user entity as shown in Figure 3.6. Select File → New → Action Rule, give the rule a name, and place it in the package. We set the priority of this action rule to 100 (in the properties panel) so this rule will be processed first when a catalog order event happens.

The text to enter for the InitializeUser Action Rule is:

when a catalog order occurs 
if 
	 'the user' is null 
then 
     set 'the user' to a new user where 
	the item ref is the item ref of this catalog order , 
	the order quantity is the quantity required of this catalog order , 
	the time is the cics timestamp of this catalog order , 
	the user id is the user id of this catalog order ;  
Figure 3.6: Action rule to initialize a catalog user entity
Figure 3.6: Action rule to initialize a catalog user entity
Note:  As of ODM Decision Server Insights 8.8.0.1, it is possible to initialize entities from events defined in an additional BOM entry using Business Model Statements. This means that you can replace the complexity of the initialization rule in the agent with a simple business model statement.  For more information see: http://www.ibm.com/support/knowledgecenter/SSQP76_8.8.0/com.ibm.odm.itoa.develop/modeling_topics/con_bdl_definitions.html

Step 5: Add a rule to raise a discount voucher when the user has ordered enough items

Because we want to offer a discount when at least 3 catalog items across the whole catalog have been ordered by a particular user, we create a second action rule which checks for this condition:

when a catalog order occurs 
if 
	 'the user' is null 
then 
     set 'the user' to a new user where 
	the item ref is the item ref of this catalog order , 
	the order quantity is the quantity required of this catalog order , 
	the time is the cics timestamp of this catalog order , 
	the user id is the user id of this catalog order ;  

The resulting Action Rule, which we have called CheckOrder, is shown in Figure 3.7. For demonstration or testing purposes, we will be checking for the criteria to be met within 4 minutes. You may set a longer period; for example, 24 hours. We set this rule’s priority to 70 so this rule will be processed later than the InitializeUser rule.

Figure 3.7: Rule to check whether the user has placed at least 3 catalog orders
Figure 3.7: Rule to check whether the user has placed at least 3 catalog orders

For demonstration purposes, we print out a line in the Insight Server server trace.log as a voucher when a discount event is raised. Create an action rule PrintDiscountVoucher with the following content:

when a discount event occurs 
then print "Discount voucher to Customer " + the user id of this discount event + "is issued.";

The formatted rule is shown in Figure 3.8. This could be changed to send an email to the customer; for example, by emitting an event from DSI that could be consumed by an event listener, perhaps running in CICS, which would send an email to the customer with the discount voucher included.

Figure 3.8: Action on occurrence of discount event
Figure 3.8: Action on occurrence of discount event

The event, the business entity, and the rules are now defined.

Step 6: Create the Connectivity Definition

The last artifact to be defined in Insight Designer is the connectivity definition (.cdef). Click on Define connectivity in the solution map (see Figure 3.9) and give the connectivity a name. The connectivity definition has information about the inbound HTTP endpoint. You could also define an outbound endpoint, if you want to drive further processing out of this scenario.

Figure 3.9: Solution Map for the CatalogSolution
Figure 3.9: Solution Map for the CatalogSolution

The connectivity definition contains the inbound binding and inbound end point. This end point will be where the CICS HTTP EP adapter sends events and should match the URIMAP PATH (as shown in the previous blog post):

// Connectivity definitions for the solution
 define inbound binding 'HTTPIncomingFromCICS' 
	with 
		 description "Events from CICS via HTTP", 
	using 
		message format application/xml , 
		protocol HTTP , 
	accepting events : 
		- catalog order . 

 define inbound HTTP endpoint 'HTTPIncomingFromCICSEndpoint' 
	with 
		 description "Endpoint for HTTP events incoming from CICS" , 
	using 
		binding 'HTTPIncomingFromCICS' , 
	url path "/Order/HTTPIncomingFromCICSEndpoint" . 

The connectivity definition is formatted by Insight Designer as shown:
CICSDSI_fig3_6b

To find out the HTTP port number for the Insight Server, which is needed for the URIMap in CICS, locate the bootstrap.properties file for your server, typically at Insights Install Directory\runtime\wlp\usr\servers\server-name\bootstrap.properties, and look for the http.port attribute. We used the sample server available from Insight Designer.

Step 7: Deploy the solution to Insight Server

The solution is complete, and the next step is to deploy the solution to DSI. Start the Insight Designer as Administrator before deploying the solution. Click on ‘Configure and deploy’ in the Solution Map (Figure 3.10) to bring up the wizard.

Figure 3.10: Solution Map for the Catalog Solution
Figure 3.10: Solution Map for the Catalog Solution

Follow the instructions in the wizard. Be sure to check the box to select the inbound endpoint created earlier, as shown in Figure 3.11.

Figure 3.11: Configuring and Deploying the Solution
Figure 3.11: Configuring and Deploying the Solution

After clicking Finish, you should see success messages in the console. Start the server if it is not yet running. Decision Server Insights is now ready to accept events from CICS.

You can now use the EGUI transaction in CICS to order items from the catalog. When the orders from a particular user have amounted to at least three items, then a discount event should be sent by Decision Server Insights. The following section shows how you can check what is happening.

Diagnostic information

For testing purpose, it is useful to see the trace showing that the CICS event arrived at the Insight Server, which results in creation of the business entity and actioning of the rules. You can check the Insight Server trace at: Insights-install-directory\runtime\wlp\usr\servers\server-name\logs

In the trace.log, when a Catalog Order event is received, you should see trace such as the following:

[06/01/16 12:32:54:826 GMT] 00000154 id=         com.ibm.ia.connectivity.inbound.impl.xml.XMLChannel          1 submit OrderSolution:: XML message received: <event:Catalog_order xmlns:event="http://www.ibm.com/prod/cics/Catalog_order">
<event:cics_usertag/ >
<event:cics_networkapplid>GBIBMIYA.IYCWZCAB2016-01-06T12:32:41.404+00:00CatalogOrderEventBindingorder_prog_init1A11C7C2C9C2D4C9E8C14BC9E8C3E6E3F1F7F11B9D5993715C0001HEJD1   </event:Charge_department>
<event:Item_ref>70  </event:Item_ref>
<event:Quantity_required>002</event:Quantity_required>
<event:User_id>HEJU1   </event:User_id>
</event:Catalog_order>

This CICS event is interpreted by the Insight Server as follows:

[06/01/16 12:32:55:401 GMT] 00000115 id=         com.ibm.ia.runtime.EventDequeuer                             1 OrderSolution:: GetNextKey [GetNextKey-OrderSolution-3] received [event] [{
  "$class" : "com.ibm.prod.cics.catalog_order.Catalog_order",
  "$Id" : "7C6DD79C2CBD30B47111E555EF5249C9",
  "$TimeAttrib" : "cics_timestamp",
  "charge_department" : "HEJD1   ",
  "cics_UOWid" : "1A11C7C2C9C2D4C9E8C14BC9E8C3E6E3F1F7F11B9D5993715C0001",
  "cics_bindingname" : "CatalogOrderEventBinding",
  "cics_capturespecname" : "order_prog_init",
  "cics_networkapplid" : "GBIBMIYA.IYCWZCAB",
  "cics_timestamp" : {
    "$class" : "java.time.ZonedDateTime",
    "value" : "2016-01-06T12:32:41.404+00:00"
  },
  "cics_usertag" : "",
  "item_ref" : "70  ",
  "quantity_required" : {
    "$class" : "java.math.BigDecimal",
    "value" : "002"
  },
  "user_id" : "HEJU1   "

The DSI InitializeUser rule will be driven and will create a user business entity:

[06/01/16 12:32:55:713 GMT] 0000015b id=         com.ibm.ia.agent.RuleAgent                                   1 OrderSolution:: Output Entity: 
{
  "$class" : "order.User",
  "$CreationTime" : null,
  "$IdAttrib" : "userId",
  "itemRef" : "70  ",
  "orderQuantity" : 2.0,
  "time" : {
    "$class" : "ZonedDateTime",
    "value" : "2016-01-06T12:32:41.404Z"
  },
  "userId" : "HEJU1   "
}

After another Catalog order event is received and the total order quantity reaches 3, the CheckOrder rule is actioned.

[06/01/16 12:34:06:996 GMT] 0000016e id=         com.ibm.ia.agent.impl.RuleAgentEngineObserver                1 Rule CheckOrder execution started
[06/01/16 12:34:06:996 GMT] 0000016e id=         com.ibm.ia.agent.impl.RuleNoteObserver                       I RuleNoteObserver.note CWMBD9751I: Rule Agent OrderSolutionRules print: Customer HEJU1    has ordered enough quantity, discount event is emitted.

Finally, when the discount event is raised, PrintDiscountVoucher is actioned.

[06/01/16 12:34:07:127 GMT] 0000016e id=         com.ibm.ia.agent.impl.RuleAgentEngineObserver                1 Rule PrintDiscountVoucher execution started
[06/01/16 12:34:07:127 GMT] 0000016e id=         com.ibm.ia.agent.impl.RuleNoteObserver                       I RuleNoteObserver.note CWMBD9751I: Rule Agent OrderSolutionRules print: Discount voucher to Customer HEJU1    is issued.

Summary

In this series of blog posts, we showed the simple steps that you should follow to enable CICS events to be consumed by Decision Server Insights, and to be included in Insights rules. We also gave a worked example of a scenario that leverages the power of Decision Server Insights together with an example event provided by CICS.

Acknowledgements

The following are thanked for their considerable contribution to the integration of CICS with ODM Decision Server Insights, and to this series of blog posts:

    Andy Wharmby,  Caroline Thomas,  Chris Backhouse,  Daniel Selman,  Dave Rushall,  David Drakard,  David Harris,  Gemma Virtanen,  Jackie Scott,  James Taylor,  Jenny He,  Lewis Evans,  Steve Bolton

What’s Next?

You can try this out for yourself, either stepping through the Catalog User Loyalty Scenario shown in these blog posts, or applying the steps to a scenario of your own. If you have ODM Advanced V8.8 or later, you could run the Insight Server on z/OS, and benefit from co-location with the CICS systems that emit the events.

Feel free to get in touch if you would like to know more.

2 comments on"Consuming CICS Events in ODM Decision Server Insights"

  1. Catherine,
    Great article on DSI! I am based out of St Louis and work for an IBM Premier Business Partner. We specialize in delivering IBM ODM and BPM to our clients. One of the technology we are running into with our clients is DSI. I was wondering if you can suggest someone I can connect with that would be knowledgeable with DSI in the United States so I can learn more about this technology. Any help would be great. Thanks!

    • Catherine Moxey March 19, 2017

      Many thanks for the feedback! I will try to get back to you with a suggestion.

Join The Discussion

Your email address will not be published. Required fields are marked *