Tutorial: Using BizTalk Service Bridges to Send and Receive Messages from Service Bus Relay Service
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:
-
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
This tutorial provides instructions on how to send XML messages with different schemas to a single bridge endpoint deployed using Microsoft Azure BizTalk Services. The bridge processes the message and routes them to more than one relay services based on the business logic defined as part of the solution. Using this scenario, the tutorial also showcases other capabilities of BizTalk Services such as:
Route Filters: The bridge enables you to route messages to the intended recipient based on filters. The filters are set on certain values that are passed as part of the message. For example, if the value in the element <Recipient> in the XML message is set to Finance, send the message to Service A. Otherwise, send the message to Service B. For more information, see The Routing Condition.
Route Action: Route actions help in bridging protocol mismatch. For example, consider two applications, App A and App B. App A sends messages by using the REST protocol while App B receives only SOAP messages. If App A sends the message to the bridge instead, the bridge includes SOAP headers on the message as part of Route Action. The bridge then sends the message over to App B. For more information, see The Routing Action.
Reply Action: Reply Action provides the same capability while sending a response back to the client, that Route action provides while sending a message to the receiver. So, if App B sends a response to App A, bridges use the Reply Action capabilities to stamp the response with headers that the client requires. For more information, see the Reply Action.
This tutorial demonstrates these capabilities of the bridge, in addition to other, using a business scenario.
Business Scenario
Northwind Traders is an automobile insurance company. Northwind Traders receive request for new policy quotes in an XML format compliant with the standard ACORD schema, an industry standard for insurance messages. The incoming messages can be in any ACORD-compliant format. So, Northwind Traders must configure a solution that can process XML messages that conform to more than one XML schema. After Northwind Traders receive the message, it is validated against the provided ACORD message schemas and transformed into a schema internal to Northwind. Northwind then sends the message to a backend service that processes the message further. However, there are certain routing conditions before the message is sent to the service.
If the quote amount in the message is less than $10000, it must be sent to a relay service, say RelayReceiverServiceA. Before sending the message to the relay service, a SOAP header called QuoteType must be added to the message header. The value of this header must be set to SmallAmounts.
If the quote amount in the message is greater than $10000, it is treated as a high-risk claim and is sent to another relay service, say RelayReceiverServiceB. Before sending the message to the service, a SOAP header called QuoteType must be added to the message header. The value of the header must be set to LargeAmounts.
After receiving the message the services generate a response, add headers, and send a response back to the bridge. The services add the following headers:
Response from service |
Headers added |
|---|---|
RelayServiceA |
MsgStatus - Success Eligibility - ApprovedForSmallAmounts |
RelayServiceB |
MsgStatus - Success Eligibility - ApprovedForLargeAmounts |
The response from the service is in the same format as the Northwind’s internal request format. After the bridge receives the response, it transforms it to the response message schema compliant with ACORD standards. The bridge also extracts the value from the MsgStatus header and assigns it to an element in the response schema. Finally, before sending the message back to the client, the bridge adds another header called ProcessingStatus and sets its value to Complete. The following illustration represents this scenario.
.jpeg "Using bridges with relay services")
How to Achieve the Scenario Using Microsoft Azure BizTalk Services
Northwind Traders use BizTalk Services to set up this scenario. Here’s what Northwind Traders do at their end for this scenario to work end-to-end:
Northwind creates two relay services, RelayReceiverServiceA and RelayReceiverServiceB. RelayReceiverServiceA receives messages with quote amount less than $10000. RelayServiceB receives messages with quote amount greater than $10000. After receiving the message, both the services generate a response message and stamp it with the headers, as described in the business scenario.
Northwind creates a BizTalk Service project and adds a XML Request-Reply Bridge to process the incoming XML messages and send a response. Northwind also adds two-way relay service components, one each for RelayReceiverServiceA and RelayReceiverServiceB.
Northwind adds all the required artifacts (schemas and transforms) to the BizTalk Service project.
Northwind configures the request path of the XML Request-Reply Bridge to do the following:
Configures the Validate stage to validate the XML messages against the ACORD schemas.
Configures the Enrich stage to promote properties based on which the messages are routed to the backend services.
Configures The Transform stage to transform messages from the ACORD schema to Northwind’s internal schema.
Northwind configures the response path of the XML Request-Reply Bridge to do the following:
Configures the Enrich stage to extract the MsgStatus header that the relay services added to the response message.
Configures the Transform stage to transform the response from the relay services into a message schema compliant with ACORD standards. In this stage, the bridge also assigns the value from the MsgStatus header into an element in the response schema.
Configures the Reply Action to include the ProcessingStatus header in the response message that is sent to the client.
Northwind adds two external relay endpoints to the BizTalk Service project representing the two relay services and connects them to the XML Request-Reply Bridge bridge. As part of these routing connectors, Northwind does the following:
Connects all the components on the Bridge Configuration design surface and sets the filter conditions based on the quote amount.
Stamps the QuoteType header on the message and sets its value to either SmallAmounts or LargeAmounts depending on which service the message is being routed to.
Finally, Northwind deploys the two relay service on Service Bus and the BizTalk Service project to BizTalk Services and sends a message to the bridge endpoint.
How to Use This Tutorial
This tutorial is written around a sample, Bridges_RelayServices.zip, which is available as part of the download from the MSDN Code Gallery. You could use the sample and go through this tutorial to understand how the sample was built. Or, you could use this tutorial to create your own application. This tutorial is targeted towards the second approach so that you understand how this application was built. Also, as much as possible, the tutorial is consistent with the sample and uses the same names for artifacts (for example, schemas, transforms) as used in the sample.
Even though Microsoft recommends that you follow the tutorial to understand the concepts and procedures, do the following if you wish to use the sample:
Download the Bridges_RelayServices sample and make relevant changes like providing your Service Bus namespace, issuer name, issuer key. After making the required changes, build and deploy the application.
Build and host the two relay services to accept request messages received via the bridge.
Use the MessageSender tool provided with the package to send request messages to the bridge. Look at the command prompts for the services as well as the MessageSender tool to see if the messages were processed successfully. If the messages are successfully processed, the request and response schemas are saved under the project’s \bin\Debug folder. The location and name of the message files are also displayed on the respective command prompts.
Set Up Your Computer
From the BizTalk Services download location (https://go.microsoft.com/fwlink/?LinkId=235057), download and install the BizTalk Services SDK. For instructions, see Install Azure BizTalk Services SDK. Installing the SDK installs the BizTalk Service project template in Visual Studio. This project template is used to create bridges that validate, Transform, and route messages to different endpoints as described in the business scenario.