Every major integration project requires a functionality to split the execution sequence for a message based on the message’s content. Integration solutions such as SAP HANA Cloud Integration (SAP HCI) must provide functionality to solve this problem elegantly. I explain how to apply the content-based router (CBR) in your integration flows and the configuration of the CBR step in great detail. For the definition of the expressions (which finally selects the route to follow) you have two options at your disposal: XML and non-XML. I describe how to formulate routing conditions using XML and non-XML expressions and how you can influence the conditions evaluation sequence. Cloud computing is currently one of the most hyped topics in the IT industry. However, this trend to cloud computing leads to an increased heterogeneity of a company’s IT landscape and, with that, to an increased need for integration. Messages need to be exchanged between on-premise and cloud applications. Fortunately cloud-based integration solutions such as SAP HCI help companies solve this integration challenge. If you take a closer look at how messages are being treated within SAP HCI, one question needs to be answered repeatedly: How can you model different message-handling execution paths (aka routes) in one integration scenario? This question stands in the middle of what is known as the CBR, the topic of this article. Well, the CBR is nothing new. It is one of the famous enterprise integration patterns described in the book by Gregor Hohpe and Bobby Woolf (Enterprise Integration Patterns (2003), Addison Wesley). As you know from previous SAP HCI articles, Apache Camel is the basic integration framework on which SAP HCI is built. Right from the beginning, one major goal of the Camel project was the implementation of those enterprise integration patterns. You find the implementation of the CBR in SAP HCI as well. In this article you will learn how to apply the CBR pattern in your integration projects.

The Scenario

Let’s start with a look at the scenario you want to build. An example integration flow using the CBR is shown in Figure 1. The depicted integration flow shows different message-handling execution paths after the diamond shape. The integration flow’s semantical behavior can be described as follows: the sender on the left (represented by the Sender pool) sends a message via Simple Object Access Protocol (SOAP) to the integration flow. You are again reusing the same input message you already had in the previous SAP HCI articles. Its structure is shown in Figure 2. The incoming message starts the integration flow on the SAP HCI server. The first Content Modifier step takes the order number from the message and stores it in the message’s header area. The Content Modifier’s configuration is depicted in Figure 3. Obviously the order number is stored in the newly created variable OrderNo. You can later access this value for defining routing conditions. If you want to learn more about the configuration of the Content Modifier and the different areas where data can be stored, I recommend the first article of my SAP HCI series titled “Your First HCI Integration Flow.” Next, the CBR comes into the picture (Figure 1). It is modeled using a Business Process Model and Notation (BPMN) exclusive gateway (the diamond shape). As you know from the first article, the whole modeling environment of SAP HCI is based on BPMN. In BPMN the exclusive gateway is used to indicate the split of the sequence flow in several independent execution paths. Exactly one of the paths leaving the gateway (which is also known as a gate in BPMN nomenclature) is later executed during run time, obviously depending on some conditions that are attached as labels to each of the outgoing sequence flows. However, if you take a close look at the gates you recognize one exception: The sequence flow leaving the gateway vertically (decorated with the tickmark []) has no condition associated with it. It is called a default gate, which is executed during run time in case none of the other conditions evaluate to the Boolean value true. Now you can describe the behavior of the gateway as follows:

1. If the incoming order number equals 10249, then the upper path is followed.
2. If the incoming order number equals 10250, then the gate in the middle is taken.
3. In all other cases the default gate is activated.

To verify the correct behavior of the gateway during run time, set the body of the reply message via the respective Content Modifier shapes that are connected with each of the three sequence flows leaving the gateway. The Content Modifier steps write the following messages as replies into the message’s body:

1. orderNumber = 10249 for the upper sequence flow
2. orderNumber = 10250 for the sequence flow in the middle
3. orderNumber unknown for the default gate

An example configuration for the uppermost Content Modifier is shown in Figure 4.

Configuration of the CBR

You know from the description above how the CBR should behave during run time. However, how is this achieved during development time? This is explained next. First of all: Where can you find the gateway in the modeling palette of SAP HCI’s graphical editor? Take a look at Figure 5. In the main menu of the palette you find the message routing shape (), also represented by the diamond shape. In the sub-menu that opens when you click the message routing icon, you finally find the router symbol. As always, click it, move the mouse into the pool for the integration flow, and click again to position the shape. Afterwards model the three Content Modifiers and connect them with sequence flows from the diamond shape to the respective Content Modifier activities. Note that you can only configure the gateways once you have connected them with the three other steps. Otherwise you won’t be able to configure the gateways correctly as you wouldn’t have access to the sequence flow’s properties to define the labels and the evaluation conditions. So, let’s configure each gate one after another. Start with the uppermost one. Click the sequence flow leaving the gateway so that its color turns to orange (Figure 6). As usual you are able to configure the attributes of the selected shape in the properties section beneath the process model. In my example, you want to tell the run-time engine that the execution of the model should be continued on the upper path of the model if the order number equals 10249. You have two options for defining such a routing condition.

• Option 1: You directly access the contents of the message (which is actually in the body area of Camel’s message model) and retrieve the value that should be used for the decision from there. Note: This option is only possible for XML-based message content. If your incoming message isn’t available in XML, you have to convert it to XML first. See my article “Working with Mappings in SAP HANA Cloud Integration,” for more details about converters.
• Option 2: You make use of header variables that have been declared and set before.

Let’s begin with option 1. Here you have to define an XPath expression to the field you want to test. In my example it is the orderNumber field of the incoming message (Figure 2). The configuration looks like the one depicted in Figure 7. The Name field holds the string that shows up as a label attached to the sequence flow in Figure 1. The Expression Type drop-down list is important. It contains the values XML and Non-XML. The selected value influences the way the Condition field is interpreted by the execution engine during run time. If XML is chosen, the condition is interpreted as an XPath expression. If Non-XML is chosen, it is interpreted as an expression using Camel variables. You see an example for the second case when you define the other gate, but first stick with the XML case. Obviously the condition is formulated using a classical XPath expression. You can also combine several expressions using the logical operators ‘and’ and ‘or’ (e.g., //orderNumber = ‘10249’ or //orderNumber = ‘10250’) to formulate more sophisticated routing logic. For the second gate you make use of the header variable OrderNo that you created by the invocation of the very first Content Modifier in Figure 1 with the configuration shown in Figure 3. The condition can be formulated now as shown in Figure 8. You can easily identify the typical Camel syntax for accessing variables (dollar sign, curly brackets). The header part of the variable’s name indicates the area from which you want to load the value (the message’s header area). The OrderNo part after the dot indicates the name under which you stored the value previously. Note that the Expression Type drop-down list has been changed to Non-XML. Because you define by this drop-down list how the Condition string will be interpreted, it should be clear that you cannot mix XML-based variables with Camel-based variables. If you try to mix them (e.g., ${header.OrderNo} = '10250' or //orderNumber = '10251'), you get a validation error (see Figure 9 for an example). The definition of the last gate is probably the easiest part of the CBR’s configuration. You just have to set the Default Route check box (Figure 10) in order to define the gate that should be followed during run time if none of the explicit conditions of the other gates evaluate to true. From what you have learned so far you know how to formulate expressions for the XML setting of the Expression Type field in Figure 8. You just have to apply the rules laid out in the XPath specification defined by the World Wide Web Consortium (W3C). But what do you have to consider for the Non-XML expressions? Which operators are allowed here? For your convenience I have provided the table from the SAP HANA Cloud Integration help website for you (Table 1). It summarizes the operators allowed for formulating Non-XML expressions.

Running the CBR Scenario

Now that the configuration is finished, you can run the scenario. As I’ve explained in my other articles, use a SOAP tool of your choice (e.g., SoapUI) and invoke the solution. As an input message take the one depicted in Figure 2. Depending on the value of the order number, you get respective replies from the integration flow. If your order number is 10250, the reply should look similar to Figure 11. If you provide a number for which no routing rule exists, the response in Figure 12 is shown because the default route of the gateway was fired. You could stop at this point with the description of the CBR. However, one interesting question is still not answered: What happens if the routing rules contain overlapping conditions? Mistakes can always happen and, especially for complex routing conditions, it sometimes results in overlapping conditions. That means that potentially two or more of the conditions could evaluate to true during run time. Hence, more gates could potentially fire. You know, on the other hand, that the exclusive gateway fires exactly one, and only one, gate. So the questions are: In case of overlapping conditions, which of the gates will fire and can I influence the sequence in which the expressions will be evaluated? Let’s try a little experiment. You can change the conditions in such a way so that they overlap. In my case I change the condition of the gate labeled with orderNumber = '10250' to ${header.OrderNo} = '10249'. This obviously overlaps with the gate already labeled with orderNumber = '10249' and its condition //orderNumber = '10249' (compare with descriptions above). Both are checking against order number 10249. Once done, save your changes, deploy them, and run the scenario again using 10249 as the input value for the order number. In my scenario I get the result shown in Figure 11. So the changed path was executed, although it is positioned in the middle of the three gates if you compare my design of the scenario in Figure 1. Obviously the visual appearance of the model has nothing to do with the execution sequence because one could think the conditions are evaluated from top to bottom in the visual diagram. My experiment proves that this is not the case. I also stressed that my scenario works this way. It might even happen that your scenario is still working correctly. What else influences the execution sequence then? The answer is hidden behind the gateway shape itself. Select the diamond shape of the router and take a look at its properties. In my example, the gateway has the properties shown in Figure 13. The Order column is important because it tells you the sequence in which the conditions are evaluated, with the obvious exception of the first row, which represents the gate being fired if no expression can be successfully evaluated. It is the default route. Indeed, the route labeled with orderNumber = '10250' is evaluated first. As the condition is true, you get the experienced result. The third row is not to be evaluated anymore as the gateway has found a valid gate already and no more gates are allowed to fire because of the exclusive behavior of the gateway. This explains the gateway’s behavior but how can you influence the evaluation’s sequence? The answer is pretty straightforward: The order of the rows is determined by the connection’s modeling sequence. Every connection you are modeling from the gateway to any task following the gateway adds a new row to this table. Note: Every new row will be added at the bottom of the table. You can conclude from this description how I created the process model of Figure 1: I first draw the connection to the Content Modifier at the bottom (resulting in the first row in the table), then to the one in the middle (second row in the table), and finally to the Content Modifier at the top (third row in the table). If I want to change the execution sequence, what do I need to do? Take a look at Figure 13 again. You want the third row to be at second place, right? So in your process model just delete the connection that is responsible for the second table row: the connection labeled with orderNumber = '10250'. Automatically the third row moves up on second place (because there is no second row anymore—it was deleted), which is exactly what you want. Then draw the connection that you just deleted, add the label and the condition in its properties, and verify the condition’s list at the gateway. It should now look like the one depicted in Figure 14. Note the changed order sequence in comparison to the one in Figure 13. If you invoke the route again with order number 10249 you get the expected (correct) result shown in Figure 15.

Summary

Routing messages to different message-handling paths is an important aspect in every integration project. SAP HCI is based on Apache Camel, which implements typical enterprise integration patterns. One of those patterns is the CBR. Its task is to split the sequence flow into different independent execution paths that can be activated based on some conditions. Exactly one of those execution paths is selected during run time. You have learned how to model the CBR in SAP HCI’s graphical modeling environment and how to configure the conditions correctly. For defining the expressions you have two options at your disposal: XML and Non-XML. You learned when to use what and how the condition’s evaluation sequence can be influenced. Now it is your turn to work with the CBR in your own integration projects.