Routing Messages from Bridges to Destinations in the BizTalk Service Project

Article
06/12/2017

Important

Microsoft Azure BizTalk Services (MABS) is being retired, and replaced with Azure Logic Apps. If you currently use MABS, then Move from BizTalk Services to Logic Appsprovides some guidance on moving your integration solutions to Logic Apps.

If you're brand new to Logic Apps, then we suggest getting started here:

What are logic apps
Create your first logic app, or quickly get started using a pre-built template
View all the available connectors you can use in your logic apps

Route messages from one component to another using routing conditions.

One of the obvious reasons for connecting various components of a BizTalk Service project is to route the message from one component to another. There’s another requirement though – you might need to route the message from one source component to more than one destination component based on your business logic, which can also be termed as the routing condition. When there are more than one routing conditions, you also need to set the order in which the routing conditions are honored. And finally, there can be some actions (like assigning values to message headers, adding custom headers, etc.) that you perform on the message before it finally gets routed to the destination. This topic discusses these aspects in detail and also provides instructions how to achieve these in a BizTalk Service project.

This topic explains these steps using an example scenario. Assume that an XML message in the following format has to be processed using a XML One-Way Bridge:

<PaymentHistory xmlns:ns0="https://Integration.PipelineChaining">
  <BaseData>
    <Amount>10.4</Amount> 
    <CurrencyCode>CurrencyCode_0</CurrencyCode> 
    <EntryDate>1999-05-31</EntryDate> 
    <EntryTime>13:20:00.000-05:00</EntryTime> 
    <PaymentMode>Mode_0</PaymentMode> 
    <StatusCode>StatusCode_0</StatusCode> 
    <PurposeCode>PurposeCode_0</PurposeCode> 
  </BaseData>
</PaymentHistory>

The business logic is such that if the payment mode is a credit card, the message must be routed to a one-way external service; if the mode is cash, the message must be routed to a one-way relay endpoint; and if the mode is neither of these, it must be routed to a Service Bus queue.

The Routing Destination

This is fairly straightforward. You must define the route destination where the incoming message gets routed to after being processed by the bridge. There are some considerations regarding where a message from an XML One-Way Bridge or an XML Request-Reply Bridge can be routed to. For more information about these considerations, see Constraints on Using an XML One-Way Bridge and Constraints on Using an XML Request-Reply Bridge.

The following procedure describes how to connect two components of a message flow.

To connect two components

Create a BizTalk Service project, as described in Get started with a Visual Studio project.
Add components to the BizTalk Service project, as described in various topics under Create Rich Messaging Endpoints on Azure.
Select Connector under the Bridges category on the Toolbox.
Take the mouse pointer to the right-end of the component (marked by a red dot when you move the cursor over the component) that acta as the source of the message. The mouse pointer changes to show a small “S” sign denoting that this component adds the source of the message. Click and hold the mouse at the dot, drag it to the left end of the target component (at this point the cursor changes again to show a small “T” denoting the target), and then release the mouse. The two components are now connected. Note that you can connect one source component to more than one target component.

Note

For the current milestone, a message flow must always start with either a XML One-Way Bridge or a XML Request-Reply Bridge. After that, you can route the message to any component, as long as you adhere to the constraints. The constraints are listed at Constraints on Using an XML One-Way Bridge and Constraints on Using an XML Request-Reply Bridge.

Going by the example scenario, you must connect the XML One-Way Bridge to a one-way external service, a one-way relay endpoint, and a Service Bus queue.

The Routing Condition

Apart from connecting two components, the other important aspect of routing is to route the message from one source component to more than one destination component based on your business logic.

Going by the example scenario explained above, the routing condition must be based on the mode of payment, which is denoted by the PaymentMode element in the XML message. To implement this business logic in a BizTalk Service project, we need to create routing filters for each condition. The following procedure describes how to do so.

Note

Before you start creating filters, ensure that you have created all the three Connectors (as described in the previous procedure). Also, you must have created a property (e.g. PaymentMode) in the Enrich stage of a bridge to extract the value of the PaymentMode element in the XML message.

The following procedure describes how to set the routing conditions in a BizTalk Service project.

To set filters on the routing connectors

Right-click the route connector between XML One-Way Bridge and the one-way external service, and then click Properties. In the Properties pane, for the Filter Condition property, click the ellipsis (…) button to the open the Route Filter Configuration dialog box.
In the dialog box, select the Filter option, and then enter the following filter string:
```
PaymentMode='credit_card'
```
Note

You must use standard SQL 92 syntax for filter expressions.

Note that PaymentMode is the property that you must have entered for extraction in the Enrich stage and this filter condition (which is entered on the connector between XML One-Way Bridge and one-way external service) specifies that the message is sent to the one-way external service, if this filter condition is met.

Click OK to save the changes and exit.
Similarly, for the connector between XML One-Way Bridge and one-way relay endpoint, enter the filter string as:
```
PaymentMode='cash'
```
If the payment mode is neither cash nor credit card, the message should be routed to a Service Bus queue. To achieve that in your message flow, for the connector between XML One-Way Bridge and Service Bus queue, you must open the Route Filter Configuration dialog box, and then select Match All. This specifies that if neither of the filter conditions matches, this filter condition is honored and the message is routed to a Service Bus queue.

The Routing Order

In the previous section we set the filters on the route connectors to ensure that the right messages get routed to the right components of a message flow. However, the order of routing is equally important. For example, going by the scenario we discussed earlier, if a message that has PaymentMode set to credit_card is routed to the filter condition that has Match All set, it is routed to a Service Bus queue instead of the one-way external service endpoint. So, according to the business logic, the Match All condition should be honored last. You can do so by setting the order in which the filter conditions must be honored.

To set the order in which routing connectors are honored

Right-click the XML bridge (XML One-Way Bridge or XML Request-Reply Bridge) and select Properties. In the Properties pane, click the ellipsis (…) button against the Route Ordering Table property.
The Route Ordering Table dialog box displays the default order of honoring the route filters. This default order is the order in which you created the route connectors. To re-order the route filters, select a route filter and then use the up and down arrow buttons to arrange them in the right order. You must repeat this step for all the route filters until you have the correct route order that you want.
Click OK to save the changes and exit.

The Routing Action

You might want to add some custom message headers or assign values to standard message headers before sending the message to the message receiver. You can do so using Route action. For more information, see Route Action.

To continue with the example used above, assume that the message has to be sent to the one-way external service with a custom SOAP header (CustomerName) and a value.

To configure the Route action

Right-click the route connector between the bridge and the one-way external service, and then click Properties. In the Properties pane, for the Route Action property, click the ellipsis (…) button to the open the Route Actions dialog box.

In the Route Actions dialog box, click Add to open the Add Route Action dialog box. In the Add Route Action dialog box, do the following:

Section	Field Name	Description
Property (Read From)	Property Name	Lists all the properties that have been defined in the previous two Enrich stages in the XML Request-Reply Bridge. When you select a property here, you specify that the value of the selected property must be assigned to the relevant message header of the outgoing message.
Property (Read From)	Expression	Use this option to provide an expression, the resultant value of which is passed on to the relevant message header of the outgoing message. You can also use this option to enter a constant value that is assigned to a message header. Some example expressions are: P1 + P2, where P1 and P2 are two properties that are already defined in any of the previous two Enrich stages 'Fabrikam', is a string constant Important You must always enter the value for an expression within single quotes. `> [!IMPORTANT] > <P>You can either choose the <STRONG>Property Name</STRONG> option or the <STRONG>Expression</STRONG> option. These options are mutually exclusive.</P>`
Destination (Write To)	Type	Enter the message type of the outgoing message, the header of which would be assigned the value that you entered earlier. Depending on the message destination, the values available in the drop-down change. If you are routing to an external service or a relay endpoint (one-way or two-way), the values available from the drop-down list are SOAP and HTTP. If you are routing to a queue or a topic, the values available from the drop-down list are SOAP and Brokered. If you are routing to an FTP destination, the value available from the drop-down is FTP. If you are routing to an SFTP destination, the value available from the drop-down is SFTP. If you are routing to an Azure blob, the value available from the drop-down is Azure Blob.
Destination (Write To)	SOAP Header Namespace (only if the Type is set to SOAP)	Enter the namespace of the custom SOAP header to which the value is assigned. `> [!IMPORTANT] > <P>This field is greyed out if you select a standard header from the <STRONG>Identifier</STRONG> drop-down list. You are required to enter a namespace only for custom SOAP headers.</P> > <P>This field is greyed out also if the <STRONG>Type</STRONG> is set to <STRONG>HTTP</STRONG> or <STRONG>Brokered</STRONG>.</P>`
Destination (Write To)	Identifier	Enter the name of message header property to which the value is assigned. You can also enter custom headers here. For SOAP message type, the drop-down lists the four standard identifiers. For HTTP message type, because there’s a huge list of standard headers, the drop-down does not list any headers. For both SOAP and HTTP message types, you can list a custom header whose value you want to assign to another property. For other destination types such as FTP, SFTP, and Azure blobs, you can select the message headers to which the property value must be written. Going with the example we took earlier, you must set this to CustomerName because that is the custom header name you must include in the outgoing message.

Click OK in the Add Route Action dialog box. The dialog boxes should now resemble the following:

So what does this dialog box depict? It means that the bridge would use the value of property P1 (already defined in one of the previous Enrich stages) and assign it to the custom SOAP header, CustomerName with namespace https://schemas.microsoft.com/integration/promotedpropertiesinfo and then send it out to the message receiver.

Important

If you create two route actions on the same route connector that point to the same destination using two different properties, for example P1 and P2, you do not get a build error. The last route action overrides the previously defined route actions. In this example, the route action for the property P2 is honored.
To update or remove a route action, you can select it in the dialog box and then click Edit or Remove respectively. Click OK in the Route Actions dialog box and then click Save to save changes to a Bridge Configuration.