Skip to content

Splitting Messages with Null Join

Note: It is recommended that the Neuron process documentation be reviewed before running this sample. The documentation thoroughly describes each process component individually and describes how to configure each one as well as how to construct a process and associate it with a Neuron Publisher or Subscriber. See the Configuration Notes section at the end of this document for more information.

Overview

This sample demonstrates how a Neuron Process can split a message into parts and send those parts as separate messages on a different topic for further processing. A Message may contain multiple elements, each of which requires special processing. For example, a purchase order published to the bus may contain several individual orders that must be processed separately. Batch file processing is another common scenario which requires the ability to split and process the individual parts of the original message as separate distinct messages.

Users may also wish to publish the original message (before splitting and processing) on the topic which it was originally published to. This sample demonstrates how the Push process step can be used to effectively preserve the original message body before any processing steps execute within a process. The sample continues by demonstrating how the original message can be restored within the process using the Pop process step. This would allow new or distinct processing on the original message, independent of the executed processing steps which directly preceded the Pop process step. For example, after each individual message of the batch message is processed and published to a new topic, the user may want to publish the original, unprocessed batch message to bus for either logging purposes or to update another subscribing system.

Process Components Demonstrated:

  • Push/Pop
  • Split
  • Publish

Solution

The Split Orders – Null Join process depicted in Figure 2 begins with a Push process step named “Save Message” that saves the incoming message before sending it on to the Split process step. Saving the original message is only necessary if there will be further processing of the message after exiting the process.

The second process step in the Split Orders – Null Join process is the Split portion of the Split process step. In this process step the message is split using an XPath expression into individual child messages.

Figure 1: An empty Split process component as displayed in the Neuron Process designer.
Figure 2: The completed Split Orders-Null Join process as displayed in the Neuron Process designer.
<Orders>
   <Order>
      <OrderID>1234</OrderID>
      <OrderDate>4/22/09</OrderDate>
      <OrderAmount>100.00</OrderAmount>
   </Order>
   <Order>
      <OrderID>1235</OrderID>
      <OrderDate>4/22/09</OrderDate>
      <OrderAmount>110.00</OrderAmount>
   </Order>
   <Order>
      <OrderID>1236</OrderID>
      <OrderDate>4/22/09</OrderDate>
      <OrderAmount>120.00</OrderAmount>
   </Order>
</Orders>
<Order>
  <OrderID>1234</OrderID>
  <OrderDate>4/22/09</OrderDate>
  <OrderAmount>100.00</OrderAmount>
</Order>

Figure 3: The original message (on the top) with the desired selection elements highlighted and an Order message that is the result of the split. An XPath expression of “Orders/Order” will select each Order block that is found under the root element of Orders.

Inside the Split process component is a process execution block named “Steps”. In this block any number of process steps can be specified. In this example there is a single Publish process step named “Send Order” in the execution block, which each child message is forwarded to.

Note: The Split portion of the Split process step extracts each child message from the parent message. As each child message is extracted, it is forwarded to the process steps configured in the execution block of the Split process step. Upon successful processing of the first child message, the next child message is extracted from the parent and forwarded to the execution block. This is repeated until all child messages are processed. Once finished, the Join portion of the process step is executed.
Note: The Split process step has a property named Synchronous that controls how to process the messages that are split from the parent message. If this property is set to “True”, each messages is processed individually in the execution block on a single thread. The first message must complete before the second message is processed, etc. If this property is set to “False”, each message is processed asynchronously in the execution block on its own thread. Several threads are used during asynchronous processing.

The Publish process step publishes each child message to a topic as a new message. For example, if the original message (before being split) contained 10 orders, then 10 orders would be published to the topic configured for the Publish process step. In this example the Publish process step is configured to publish on the “Orders.Processing” topic.

The Join part of the Split (displayed as Null Join) process step receives each message part in sequence and reassembles the contents. A wrapper element tag as well as a namespace can be specified for the Join to use as a wrapper around the reassembled parts.

Note: Although in a Split process step, the Join is always executed, it is not used in this sample to reassemble the message because Change Join Type -> Null was selected from the short cut menu of the Split Process Step. Instead a Push and Pop are used to guarantee the original message is restored at process exit.

The final process step is a Pop process step named “Restore Message” that restores the original message that was saved in the Push process step.

Running the Sample

Open the Sample

To open this sample, see the topic Using the Neuron Samples and select the Splitting Messages with Null Join sample.

Run the Samples

  1. The sample launcher opens 2 Neuron Test Clients. Connect one client to the OrderSplitter party. Connect the other client to the OrderProcessor party.
  2. From the Repository tab in Neuron Explorer copy the test message OrdersTestMessage from the Xml Documents area. Copy the test message into the OrderSplitter test client’s Send tab message field.
  3. Make sure that the topic “Orders” is selected in the Topic Dropdown located above the message field on the Send tab of the OrderSplitter test client.
  4. Click the Send button on the test client connected to the OrderSplitter party and review the results in the History tab of the test client connected to the OrderProcessor party. Note that there are 3 Order messages received as shown in Figure 4 below.
Figure 4: OrderProcessor test client history tab showing 3 Order messages received.
  1. Optional Step: Open a third test client and connect to the Orders party. Send the same message from the OrderSplitter client and note the received message in the Orders client. This demonstrates the saving and restoring of the original Orders message using the Push and Pop steps.
    Note: An Optional Trace process step can be added in the Steps execution block of the Split process step to write the output of each message to the Trace Window.
Figure 5: The Neuron Process Designer’s Trace Window displaying each message split from the original message. This was accomplished by dragging a Trace step into the Steps execution block of the Split process.

Configuration Notes

All processes with the exception of the Code process step are configured by selecting and setting their properties in the property grid located at the bottom right of the process designer. The Code process step is configured by selecting the “Edit” option from the short cut menu that is available when right-clicking the Code step in the process designer. See the process documentation for more information.

Figure 6: The Neuron Process Designer displaying the SplitOrders – Null Join process. Property Grid at the bottom right displaying the properties of Publish process step named “Send Order”. Note the topic that the step publishes on is “Orders.Processing”.
Was this article helpful?
Dislike 0
Previous: Splitting Messages with Join
Next: Testing Processes from Visual Studio