In the previous blog post in this series (More rapid business insight with ODM and CICS integration), we discussed how integration of CICS event processing support with IBM Operational Decision Manager (ODM) Decision Server Insights opens up the possibility of new decision scenarios.
We also introduced a scenario based on the CICS Catalog Manager example application. In this post, we will show you how easy it is to set up CICS to emit events that can then be consumed by Decision Server Insights, as part of that scenario. Part 3 will show how to set up Decision Server Insights to consume and process the events.
Integrating CICS events with ODM Decision Server Insights
CICS Event Processing support is a core component of the CICS runtime, and will detect occurrences of events which are currently enabled, and capture the events without the need to make application code changes â enabling rapid, easy deployment of event-based solutions. Tooling is used to: define events and their data; specify to the CICS runtime how to detect when the events occur; indicate how events are to be formatted and routed; and deploy the events to CICS. This tooling, known as the Event Binding Editor, is Eclipse based and included as part of the CICS Explorer and in Rational Developer for z Systems (RDz). The Event Binding Editor allows you to create event bindings, which contain one or more event specifications. Event bindings are included in CICS Bundle Projects, and deployed to CICS as CICS bundles. This allows them to be installed into the CICS runtime and, when enabled, to allow CICS to detect events as they occur. The tooling also supports the definition of Event Processing adapters (EP adapters), which are also installed into the CICS runtime via CICS bundles. There are a number of EP adapter types supplied with CICS, which can send the event in one of the provided formats to its intended consumer. Because CICS EP adapters all use a standard interface, it is also possible to write custom EP adapters to emit events in any format and using any transport. An EP adapter can be specified as part of an Event Binding, or separately using the EP Adapter editor. Separate EP adapters can be used by more than one Event Binding and combined into an EP Adapter Set for routing an event to multiple consumers. The EP Adapter editor, or the Adapter tab of the Event Binding Editor, also provides an option to export schemas that describe the events included in the event binding.
For more details about CICS event processing support, see the Redbook on âEvent Processing with CICSâ (http://www.redbooks.ibm.com/abstracts/sg247792.html) and the topic on âGetting started with eventsâ in the CICS Knowledge Center.
Setting up CICS events for ODM Decision Server Insights
This section describes the steps you would take to integrate CICS events with ODM Decision Server Insights. Further details of these steps, illustrated using the âCatalog Orderâ event and scenario, are shown in the next section.
- Create a CICS bundle project containing the CICS event specification in an event binding, using the Event Binding Editor in CICS Explorer or Rational Developer for z Systems (RDz).
- Create an EP Adapter to emit the events to your ODM Insight Server, specifying âDecision Server Insights Event (XML)â, or DSIE, as the event format (you will need version 18.104.22.168 of the CICS Explorer to do this). The EP Adapter type can be HTTP or MQ, as either of these transports can be used to send events from CICS to ODM Insights, but in our example below we use the HTTP EP Adapter. The âTS Queueâ EP Adapter type can also emit events in DSIE format to a CICS temporary storage queue, to allow you to test your events and easily see the output using the CICS CEBR transaction. You could add your EP Adapter into an EP Adapter Set if you want the events to be received by more than one consumer.
- If you are using the HTTP EP adapter, install a URIMap in CICS, to specify the URL and port for your ODM Insight server.
- Export the CICS bundle project to a directory on zFS, and install a CICS bundle definition that references that location. (You will need APAR PI55134 for CICS TS V5.3, or APAR PI55133 for CICS TS V5.1 and V5.2, to install a bundle that uses the DSIE event format.)
- Use the Event Binding Editor or EP Adapter editor to export an XML schema which describes the event in the Insights format. This schema can be imported into the Insight Designer tooling, so that the event can be included in Decision Server Insight rules.
- Drive your application, which will cause events to be emitted. In the next blog post, we will explain the steps to allow the CICS event to be recognized and processed by Decision Server Insights. Within Insight Designer you will
- Import the event XML schema produced by the CICS EP tooling into a Solution Project
- Create a business model definition to define entities used by the Solution
- Create rules that detect situations of interest
- Define connectivity to the Solution Project, to receive the events from CICS
- Deploy the Solution to a running Insight Server
Catalog User Loyalty Scenario: CICS steps
In the previous blog post in this series, we 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 3 items, and to offer the customer a discount voucher to reward their loyalty. In this section, we show how to set CICS up to emit an event whenever an order is placed. Figure 2.1 illustrates this scenario.
We use the CICS supplied catalog manager example application, and Catalog Order example event, in this scenario. To follow this scenario, and emit the events from CICS, you will need to install the CICS catalog manager example base application into CICS. Please refer to the CICS TS Knowledge Center for how to do this: http://www.ibm.com/support/knowledgecenter/SSGMCP_5.3.0/com.ibm.cics.ts.exampleapplication.doc/topics/dfhxa_t100.html?cp=SSGMCP_5.3.0
Step 1: Create a âCatalog Orderâ event specification
The catalog manager âCatalog Orderâ event is provided as an example event by the CICS Event Binding Editor (in CICS Explorer V22.214.171.124). To include the event binding for this event in a CICS bundle project, create a bundle project in the Resource perspective of the CICS Explorer, select the bundle project then enter Ctrl+N for the new wizard (CMD+N on Mac OS X) and type âinsightâ into the filter box, as shown in Figure 2.2. Select the ‘Catalog Orders for Decision Server Insights Event’ and in the next box, ensure that the correct bundle is selected and name the event binding. We have used âCatalog_Orderâ as the event name in our example.
The resulting event specification for this event is shown in Figure 2.3, which shows the data items (‘Emitted Business Information’) to be included in the event:
This event is captured when the program, DFH0XVDS, that handles catalog orders is initiated. The Application Capture Point used in the event capture specification is therefore âPROGRAM INITâ. However, this program also handles other catalog requests, so in the Filtering tab of the capture specification, in addition to specifying that the event is to be captured when initiating the program DFH0XVDS, we also need to check that the type of request is a catalog order request. The type of request is passed to the program as a field in the COMMAREA. Figure 2.4 shows the filtering used in the capture specification for this event.
The emitted business data for this event is also obtained from the COMMAREA passed to the program, as seen in Figure 2.5.
Step 2: Create an EP Adapter to emit the event
Create an HTTP EP adapter with the Decision Server Insights Event (DSIE) format, so that the Catalog_order event specification emits events to it. The Example Catalog Order event includes an embedded EP adapter which specifies HTTP as the Adapter tab and DSIE as the event format (see Figure 2.6). You can alternatively choose to define a standalone (predefined) EP adapter resource, which could then be used by other event bindings containing events that you also want to emit to your Insight Server. For initial testing of the events, you could use an EP Adapterset with both the HTTP EP Adapter and also a TS Queue EP Adapter to show the emitted events in CICS.
You should not need to change any of the Advanced Options in the EP adapter, but in our case we used a transaction JEPH to emit the event instead of the default of CEPH. The first event sent to Decision Server Insights requires some additional processing, which in our basic test environment took longer than the default RTIMEOUT value of 5 seconds set in the DFHECEPH profile that is used by CEPH. So we cloned CEPH and DFHECEPH and changed RTIMEOUT in the cloned profile to a higher value. You might not need to do this, unless you see any timeouts when emitting events to your server.
Step 3: Install CICS resources for HTTP
Define and install a URIMAP âURIDSIE’ that is used by the EP adapter, and set the following attributes.
USAGE: CLIENT PATH: /Order/HTTPIncomingFromCICSEndPoint SCheme: HTTP PORT: DSI port HOST: DSI server IP address
Note that PATH will be the same as you will specify in the inbound HTTP end point in Insight Designer. PORT and HOST are the Insight serverâs HTTP port and host.
Step 4: Export and install the CICS bundle
From the CICS Explorer Resource perspective, select the option to ‘Export Bundle Project to z/OS UNIX File System’, and then from the CICS SM perspective, define and install into CICS a bundle that references the location of the exported bundle project on zFS. You can include definitions for the event binding, EP adapter (or EP adapters) and URIMAP in the same bundle project, which will allow all the resources required for this scenario to be installed together:
Step 5: Export the event schema
In the EP Adapter tab of the event binding (or separate EP Adapter resource), use the âExport Event Specificationsâ button to export the event schema that represents the Catalog_order event; see Figure 2.7. This schema will be used to import details of the event into the ODM Insight Designer tool.
The schema is in the format recognized by Decision Server Insights. Weâll take a look in the next blog post at what it looks like, and how it is used by Insights.
Step 6: Emit some events
Start the main menu of the catalog manager application by launching the EGUI transaction, and order items from various users. Each order will emit an event to the Insight server. At this stage, we have not yet defined a solution in Insight Server to receive and process the events, but if you also used a TS Queue EP Adapter you can use the CICS CEBR transaction to browse the TS queue and see the events there.
In the third blog post in this series, we show how to set up Decision Server Insights to consume the CICS event, and use it to look for the situation where a user has ordered several items and is therefore eligible for a discount voucher. See Consuming CICS Events in ODM Decision Server Insights.