eInsight Correlations in CAPS 5.

1
Correlation Examples, Example 1

Simple ELS Counted Implementation

[email protected]
November 2007

Introduction
Correlations are probably the single least understood area of eInsight functionality.
The example discussed here implements one of the “Event Linking and Sequencing”
patterns, present in e*Gate 4.5 and eGate SRE, that is alleged to have been lost in
ICAN and Java CAPS. In as much as implementing ELS in eInsight 5.1 using
correlation requires some development, rather then just configuration, one could argue
that it was lost. In as much as implementing ELS in eInsight 5.1 is possible and
relatively simple, one could also argue the opposite.

This example implements a part of the ELS functionality dealing with linking a
specific number of related messages, a counted correlation pattern, or an aggregator
pattern.

Counted Correlation Pattern

Assume that messages processed by an integration solution are related in groups.
Each message contains an element that identifies it as a member of a certain group. A
series of Items related to the same Purchase Order, might be an example of this. Each
Item message carries the Purchase Order Number that identifies it as belonging to a
particular Purchase Order. The task of an implementation of a Counted Correlation
Pattern is to collect these related messages and aggregate them into a single message.

This discussion deals with a specific implementation of an Aggregator Pattern,

specialised as a Counted Correlation Pattern, specialised as a solution which
aggregates exactly two related messages.

Implementation
The job of correlating two messages will be performed by an eInsight business
process using eInsight Correlations facilities.

eInsight correlation relies on XPath-based inspection of message content to determine

the key identifying component(s) of each message. eInsight Engine extracts these key
identifying components from each message and compares them to a list of keys
associated with existing eInsight business process instances. If the new key is
matched to an existing eInsight business process instance then the message is
delivered to that instance. If the key is not matched, then eInsight Engine initiates a
new process instance and delivers the message to it.
This example will be triggered by an arrival of a JMS message to a specific JMS
Queue and will correlated two related messages in the same JMS Queue.
Implementations using other sources of messages are naturally possible.

Pre-processor Java Collaboration

As a consequence of the way correlation keys are extracted it is necessary to provide
eInsight with a message it can process using XPath. In this example we will use JMS
messages. eInsight can inspect the JMS message structure. Where eInsight can inspect
individual JMS Message Headers, it can only inspect the JMS Message Body as a
blob, even if the message body is actually an XML message. Thus to allow eInsight
access to a key value we must place it in one of the JMS Message Header properties,
for example the Correlation Id header. The essential point is to ensure that a message
carries the key value in one of the JMS Message Header properties so that eInsight
Engine can find it.

To keep the example simple we will use the Enterprise Manager to create JMS
messages which to deliver for correlation. Since the Enterprise Manager, through
version 5.1.3, does not allow us to set JMS Message Header property values we will
use a simple Java Collaboration to set it. We will use the value of the Text Message as
the Correlation Id. This both keeps the example simple and illustrates one way to
prepare a message for use in correlation.

Let’s create a project CountedSimple and a Java Collaboration

jcdSetCorrelationID, whose input will be a JMS Message and whose output
will also be a JMS Message.

Figure 1 shows the receive method of this Java Collaboration in source code mode.

public void receive

( com.stc.connectors.jms.Message input
, com.stc.connectors.jms.JMS W_JMS )
throws Throwable
{
com.stc.connectors.jms.Message jmsMsg = W_JMS.createMessage();
jmsMsg.setTextMessage( input.getTextMessage() );
jmsMsg.getMessageProperties().setCorrelationID
( input.getTextMessage() );
W_JMS.send( jmsMsg );
}
Figure 1 Set Correlation Id JCD

Note that this collaboration simply takes the text message and uses it, in its entirety,
as the Correlation Id. This is to keep the example simple and uncluttered with non-
essentials. A more realistic implementation would unmarshal the message into an
OTD and use one or more field values to assemble a more appropriate Correlation Id.

Correlating eInsight Business Process

Since the example correlates two messages from the same JMS Queue the eInsight
process will be very simple, consisting of two JMS Receive activities, a JMS Send
activity and a single Business Rules activity. The business rules activity will simply
concatenate the values of the Text Message nodded of the two messages with the
literal text “==”, see Figure 2, and send the result to a JMS queue.
Figure 2 Two Message correlation

Let’s configure the Correlation Key.

Right-click on the process name in the Project Explorer, choose Properties and click
on the Correlations Tab. Click Create. See Figure 3.

Figure 3 Create a Correlation Key, Step 1

Enter the name of the correlation key. In the tree of messages scroll to the top level
node called Message – this represents the JMS OTD Message structure. Expand node
tree under Message to Message Properties node and select the Correlation Id element.
Click the Add button. See Figure 4.
Figure 4 Create a Correlation Key, Step 2

Click OK to complete the dialogue and click Create … button in the Correlation Set
section, see Figure 5.

Figure 5 Create Correlation Set, Step 1

Enter the name of the correlation set, select the correlation key in the list on the left
and click Add to add it to the correlation set. See Figure 6.
Figure 6 Create Correlation Set, Step 2

Click OK to complete the New Correlation Set dialogue and click OK to dismiss the
Business Process Properties dialogue.

Click on the first JMS Receive activity in the business process. Click on the “Show
Property Sheet” toolbar button to open the property sheet if not already open. Click at
the right end of the “Use Correlations” property value to open the “Use Correlations”
dialogue box. Click the Add … button. In the Assign Correlation Set dialogue box
select the correlation set and click the Add … button. See Figure 7.

Figure 7 Use Correlations on the initial JMS Receive activity, Step 1

Click OK to complete the Assign Correlation Set dialogue box.

Click on the “Initialize Set” drop-down in the Use Correlations dialogue box, select
Yes and complete the dialogue by clicking OK, see Figure 8.
Figure 8 Use Correlations on the initial JMS Receive activity, Step 2

This set of steps will ensure that the correlation set is initialised with the value of the
JMS Message Header Property Correlation Id, which we chose as the correlation key,
when the process instance is created. This value will then be used by the eInsight
Engine to attempt to match subsequent messages.

Let’s configure the second JMS Receive activity to also use correlations and to do so
in such a way that messages received from the JMS Queue will be matched to existing
business process instances.

Choose the second JMS Receive activity, click on the “Show Property Sheet” toolbar
button to open the Property Sheet, if it is not already open. Click on the far right of the
value of the “Use Correlations” property. Click on the Add … button. Select the
correlation set and click Add … to select the correlation set. Click OK to complete the
Assign Correlation Set dialogue. See Figure 9.

Figure 9 Use Correlations on the second JMS Receive activity, Step 1

In the Use Correlations dialogue box ensure the Initialize Set property is set to “no”
and complete the dialogue box by clinking OK, Figure 10.
Figure 10 Use Correlations on the second JMS Receive activity, Step 2

Create a Connectivity Map, drag the business process and the collaboration onto it,
create 3 JMS Queues and connect. See Figure 11.

Figure 11 Connectivity Map

The initial queue is called qIn. The intermediate queue is called qCorrIn. The final
queue is called qOut. Your queues can be called whatever seems good to you.

Note that although the business process has two JMS Receive activities there is only
one inbound queue. Both receive activities will receive a message from the same
queue. If the process did not use correlations the process instance would process
messages in consecutive pairs, regardless of their content. It is the use of the
correlation facilities that ensures that the second message a process instance receives
is related to the message that triggered instance creation.

Let’s create a deployment profile, build and deploy the solution.

Exercise the solution

To exercise the solution let’s start the Enterprise Manager, navigate to the
connectivity map and choose the appropriate JMS Queue, qIn in this case. Once the
queue view pane opens, click the “Send/Publish” toolbar button. See Figure 12.

Figure 12 Submit a message to a queue, step 1

This will open a dialogue box that will allow us to enter text for the JMS Text
Message and submit the message to the selected queue.
Let’s submit a message with text “aa”, see Figure 13.

Figure 13 Submit a message to a queue, step 2

Assuming this is the first time this solution is exercised, choose queues qCorrIn and
qOut in turn to see that there are no messages in either. The message we submitted to
qIn has been consumed and delivered to the business process. The process now waits
on the second receive activity for a message whose Correlation Id matches that in the
first message. Had we enabled persistence for monitoring on this process we could
have inspected the process in Enterprise Manager and visually determined which
activity the instance is stopped on.

Let’s submit another message, containing the same text “aa”, to qIn. The process will
resume, combine the two messages and write the result to qOut. Select qOut and
inspect the message queued there, figure 14.
Figure 14 Aggregated message

To make sure correlations work let’s submit six messages to qIn with the following
content, in order: “qq”, “ww”, “ee”, “ww”, “qq”, “ee”. After submitting the second
“ww” message we should see a message with “ww==ww” in qOut. After submitting
the second message with “qq” we should see a message with “qq==qq” in qOut. After
submitting the second message with “ee” we should see a message with “ee==ee” in
qOut. This demonstrates that correlations indeed work and that correlation ids are
indeed matched.

Summary
This example implemented a part of the ELS functionality dealing with linking a
specific number of related messages, a counted correlation pattern, or an aggregator
pattern. In the example two related messages, originating in the same JMS Queue,
were correlated, with the aggregated message written to another queue. This example
demonstrates, beyond doubt, that at least one aspect of ELS can be implemented in
Java CAPS 5.1.3 and that correlating messages in the same queue is possible.