Create an XML Request-Reply Bridge
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 section lists the steps create an XML Request-Reply Bridge in a BizTalk Service project. XML bridges have different stages. In this topic:
Add the Bridge to the BizTalk Services project
Enter the request schemas
Configure the Validate stage for the Request message
Configure the Enrich Stage (and its Properties) for the Request message
Configure the Transform stage for the Request message
Configure the Enrich Stage (post- Transform) for the Request message
Configure the Enrich Stage for the Response Message
Configure the Transform Stage for the Response Message
Configure the Enrich Stage (post-Transform) for the Response Message
Configure the Reply Action Before Routing the Response Message
Add the Bridge to the BizTalk Services project
Create a BizTalk Service project. Get started with a Visual Studio project lists the steps.
Right-click anywhere on the BizTalk Service project design area and select Properties. In BizTalk Service URL, enter your BizTalk Services URL.
From the Toolbox, drag and drop the XML Request-Reply Bridge to the BizTalk Service project design area. A .BridgeConfig file is added to the solution.
Right-click the bridge, select Properties, and then enter the following properties:
Property Name
Description
Associated Project Item
Read-only: The name of the associated .BridgeConfig file. To change the name of the file, change the Entity Name property.
Entity Name
The name of the XML bridge on the BizTalk Service project design area. This name should be unique for the BizTalk Service project. The name of the .BridgeConfig file is the same as the value you enter here.
Relative Address
The relative address where the XML bridge is hosted on Microsoft Azure. This address combined with the BizTalk Services URL you enter in Step 2 creates the complete URL for the bridge.
For example, if the BizTalk Services URL is MyBizTalkService and the relative address of the bridge is UpdateCustomers, the URL for the endpoint on the Service Bus is https://MyBizTalkService.biztalk.windows.net/default/UpdateCustomers.
Route Ordering Table
Enter the routing order of the message from the bridge to other components of the message flow. See The Routing Order.
Runtime Address
The public runtime endpoint URL where the bridge is deployed.
Track Properties
Set this property to define which message properties are tracked by the bridge. See Tracking Messages Processed by the Bridge.
Click Save.
Enter the request schemas
A single BizTalk Service project can have multiple bridges and multiple schemas. For ease of use and to save on processing time, you can associate schemas with bridges. In other words, you can require that a specific bridge can only process messages that conform to a specific schema or a set of schemas. This section lists the steps to create this association.
Add the schemas to the BizTalk Service project. Get started with a Visual Studio project lists the steps. Repeat this step to add any number of schemas that you need for your BizTalk Service project.
Double-click the XML Request-Reply Bridge to open the itinerary designer.
Note
The itinerary designer is a read-only area. You cannot add or remove a stage or an activity from the itinerary designer.
On the bridge design area in the Message Types box, select the add icon [
.jpeg "Add icon")
] to open Message Type Picker. In Message Type Picker:From the Available message types box, select the schema for the Request message.
Select the right arrow icon [
.jpeg "Arrow Icon")
] to associate the Request schema with the bridge.Select the right arrow icon [
] under Response Message Type to associate the Response schema with the bridge.Select OK. The schema that you selected is now listed under the Message Type box.
Additional:
You cannot add multiple schemas at the same time. To associate more schemas with the bridge, repeat this step.
To remove a schema association with the bridge, select the schema from the Message Type box, and then press the delete icon [
.jpeg "Delete Icon")
].To replace one schema association with another, click the edit button [
.jpeg "Edit Icon")
] to reopen Message Type Picker.
Click Save.
Configure the Validate stage for the Request message
In the Validate stage, you can enter whether the stage does any schema validation on the incoming request message and whether the validation warnings can be propagated back to the client as exceptions.
Double-click the bridge to open the Bridge Configuration design area.
Select the Validate stage. In Properties, set IsEnabled to True or False. When True, the stage validates the incoming request message against the schemas you previously added. If False, there is no schema validation and the message is simply passed through to the next stage.
Additional:
To include any custom code that executes before the message enters the Validate stage, set the On Enter Inspector property. See How to Include Custom Code in Bridges.
To include any custom code that executes after the message exits the Validate stage, set the On Exit Inspector property. See How to Include Custom Code in Bridges.
Select the Xml Validate activity. In Properties, set Report Warnings As Errors property to True or False. When True, the bridge reports any warnings as errors encountered during XML validation against a schema and returns them back to the client that sent the request message. A validation warning is thrown as an exception and the validation fails. See Validation and the Schema Object Model to understand the warnings and errors in XML schema validation.
Click Save.
Configure the Enrich Stage (and its Properties) for the Request message
The Enrich stage enables message enrichment by defining properties, the values for which can be derived from the message header (standard or custom), through default properties promoted by BizTalk Services, from an external data source (only Microsoft Azure SQL Database tables are supported), or from an element within the message body. These properties can then be used to either route the message to a destination endpoint or for further processing by the message receiving entity. This section lists the steps for performing each of the following actions:
Assign message header values to properties.
Use default properties or system properties promoted by BizTalk Services.
Look up an external data source
Extract values from a message body element using Xpath
Important:
The property names you enter in this stage are not case-sensitive.
The property you enter in this stage is not for Route or Reply Actions unless you save the Bridge Configuration. See Route and Reply Actions: Bridging Protocol Mismatch for more details on Route and Reply.
You can choose whether you want to perform any of these actions by turning the Enrich stage on or off.
Steps:
Double-click the XML Request-Reply Bridge to open the itinerary designer.
Select the Enrich stage. In Properties, set the IsEnabled property to True or False.
Note
When True and there is no property defined, then the bridge does not throw an error when configuring the bridge (design-time) nor when processing the message (run-time).
Additional:
To include any custom code that executes before the message enters this stage, set the On Enter Inspector property. See How to Include Custom Code in Bridges.
To include any custom code that executes after the message exits this stage, set the On Exit Inspector property. See How to Include Custom Code in Bridges.
Within the Enrich stage, select the Enrich activity. In Properties, select the ellipsis button (…) against the Property Definition property to open Property Definitions.
In Property Definitions, select Add. In Add Property, you can use values from various sources and include them in the message as properties. These properties and their values can then be used later for other processing tasks, like routing messages to different destinations based on property values (see The Routing Action). The following table lists the different sources and ways to add properties to the message:
Source
How To
Assign message header values to properties
Use system-promoted properties
Look up an external data source
Extract values from within the message using XPath
To assign message header values to properties
In Add Property, do the following:
Note
This table lists only the fields required for the header to property assignment operation, which is relevant only for messages that are transferred using the message transfer protocols such as SOAP, HTTP, FTP, and SFTP. So, the following steps are relevant only if you select HTTP, SOAP, FTP, or SFTP from the Type drop-down list. Also, depending on what you select for the Type drop-down list, the required fields are outlined in red and the other fields are greyed out.
Section
Field Name
Description
Source (Read From)
Type
Specifies the message type from which the header values ae extracted. For assigning header values to properties, the possible values are SOAP, HTTP, FTP, SFTP, and Brokered.
Source (Read From)
SOAP Header Namespace (only if the Type is set to SOAP)
Specifies the namespace of the custom SOAP header. For example, in the following excerpt, the namespace for the MessageType custom header is highlighted:
DELETED CODE
Important
This field is greyed out if you select a standard header from the Identifier drop-down list. You must enter a namespace only for custom SOAP headers; however it’s not a mandatory property.
This field is also greyed out if the Type is set to HTTP, FTP, SFTP, or Brokered.
Source (Read From)
Identifier
Specifies the name of message header property, the value of which you want to extract and assign to a property that you are defining in this dialog box. If we take the same excerpt as above, the identifier would be MessageType.
You can also specify custom headers here. For FTP and SFTP, the drop-down lists the standard identifiers. For HTTP message type, because there’s a huge list of standard headers, the drop-down does not list any headers; you can enter the name of the header in such a case. Also, for SOAP, HTTP, and Brokered message types, you can also list a custom header whose value you want to assign to another property.
To understand this better, look at this example. Let’s assume a SOAP message header looks like the following:
DELETED CODE
In this excerpt, PONumber is a custom SOAP header whose value is PO1234. So, if you set the Identifier to PONumber, the value PO1234 is assigned to the property that you are defining here.
Property (Write To)
Property Name
Specifies the name of the property that you are defining. The value of this property is set to the value that is extracted from the message header property you specified earlier.
To continue using the same example as above, if you set the Property Name to P1 and Identifier to PONumber, the value of P1 is set to PO1234.
Property (Write To)
Data Type
Specifies the data type for the property. You can select a value from the drop-down list.
Click OK in the Add Property dialog box. The dialog boxes should now resemble the following:
.jpeg "Property Definition")
So what does this screen capture depict? It means that if the incoming message is a SOAP message with a SOAP header name as PONumber and header namespace as https://schemas.microsoft.com/integration/promotedpropertiesinfo, then a P1 with data type string is created and the value of header is assigned to this property.
To update or remove a property definition, you can select the property definition in the dialog box and then click Edit or Remove. Click OK in the Property Definition dialog box and then click Save to save changes to the Bridge Configuration.
To use system-promoted properties
In Add Property, do the following:
Note
This table lists only the fields required for the system-promoted properties assignment to the message. Also, depending on what you select for the Type drop-down list, the required fields are outlined in red and the other fields are greyed out.
Section
Field Name
Description
Source (Read From)
Type
For using system-promoted properties, select System from the drop-down list.
Source (Read From)
Identifier
Specifies the name of system-promoted property, the value of which you want to extract and assign to a property that you are defining in this dialog box.
Property (Write To)
Property Name
Specifies the name of the property that you are defining. The value of this property is set to the value that is extracted from the system-promoted property you specified earlier.
Property (Write To)
Data Type
Specifies the data type for the property. You can select a value from the drop-down list.
To lookup an external data source
In Add Property, do the following:
Note
This table lists only the fields required for the lookup operation. So, the following steps are relevant only if you select Lookup from the Type drop-down list. Also, depending on what you select for the Type drop-down list, the required fields are outlined in red and the other fields are greyed out.
Important
For this release, you can only lookup from a Microsoft Azure SQL Database table.
Section
Field Name
Description
Source (Read From)
Type
For a lookup operation, select Lookup from the drop-down list.
Source (Read From)
Identifier
From the drop-down list, select an already configured provider
If you haven’t already configured a provider, then configure one:
From the Identifier drop-down list, select Configure New.
In the Provider Configuration dialog box, specify the following values:
Provider Name:
Specify a name for the provider
Connection String:
Specify a valid connection string to connect to a Microsoft Azure SQL Database table
Table Name:
Specify the Microsoft Azure SQL Database table name from which you want to do a data lookup
Query In Column:
Specify a column name in the Microsoft Azure SQL Database table, the values of which are used as the input query for performing the data lookup
Query Out Column:
Specify a column name in the Microsoft Azure SQL Database table, the value is the output value that is eventually assigned to the looked up property.
Click OK to add the provider configuration.
Source (Read From)
Lookup Property
From the drop-down list, select a property that you must have already defined. The value of this property is passed on to the Query In Column specified in the provider configuration above.
Property (Write To)
Property Name
Specify a name for the property that contains the looked up value. The value of this property is derived from the value of the Query Out Column in the provider configuration above.
Property (Write To)
Data Type
Specifies the data type for the property. You can select a value from the drop-down list.
Click OK in the Add Property dialog box. The dialog boxes should resemble the following:
.jpeg "Lookup definition")
So what do these dialog boxes depict? This is how the logic flows (explained using the same purchase order example as above):
The bridge looks up the value of P1 (PO1234) in the input query column (P_Order) in the table (TempTable) defined in the MyProvider provider configuration.
The bridge then picks up the value corresponding to PO1234 from the output query column (Cust_Name) in the TempTable.
The value picked up from the output query column is assigned to the property P2. For example, if the customer name corresponding to purchase order PO1234 is John, the value of P2 is set to John.
The data type of property P2 is set to string.
To update or remove a property definition, you can select the property definition in the dialog box and then click Edit or Remove. Click OK in the Property Definition dialog box and then click Save to save changes to the Bridge Configuration.
To extract values from a message body using xpath
In Add Property, do the following:
Note
This table lists only the fields required for the extract (xpath) operation. Also, depending on what you select for the Type drop-down list, the required fields are outlined in red and the other fields are greyed out.
Section
Field Name
Description
Source (Read From)
Type
Select Xpath from the drop-down list.
Source (Read From)
Identifier
Specify the xpath query to extract an element or an attribute from a message. A typical xpath query looks like the following:
DELETED CODE
Source (Read From)
Message Type
Specifies the message type for the message from which the element or attribute value has to be extracted using the xpath query.
The drop-down list shows all the schemas that you have added to the BizTalk Service project. Select the schema that has the element that you want to extract.
Property (Write To)
Property Name
Specifies the name of the property that you are defining. The value of this property is set to the value that is extracted from the message body using the xpath query.
Property (Write To)
Data Type
Specifies the data type for the property. You can select a value from the drop-down list.
Click OK in the Add Property dialog box. The dialog boxes should resemble the following:
.jpeg "Extraction using Xpath")
So what does this dialog box depict? It means that from a message type (PurchaseOrder, in this example), the bridge extracts the value from the element per the given xpath query, assigns it to the property P3, and sets the data type of property P3 to double.
To update or remove a property definition, you can select the property definition in the dialog box and then click Edit or Remove. Click OK in the Property Definition dialog box and then click Save to save changes to the Bridge Configuration.
How do the Properties get Promoted?
At design-time using the Bridge Configuration design surface, you can define the properties that will be promoted and the values that will get assigned to them. But the property promotion and value assignment actually happens at runtime; which is when a message flows through the bridge deployed on Service Bus. However, at runtime there could be instances when the property promotion fails due to various reasons. Use the following table to understand how and when that can occur:
If this happens
What gets promoted
The SOAP or HTTP header you specify during design time does not exist in the actual message that is sent to the bridge at runtime
The property you defined at design time does not get promoted at run time; no exception is thrown.
The XPATH query you specify during design time does not correspond to an element in the message that is sent to the bridge at runtime
The property you defined at design time does not get promoted at run time; no exception is thrown.
For Lookup, if the Lookup property you specify at design time, does not exist at runtime (because it never got promoted)
The property that would have been assigned a value as a result of the lookup does not get promoted; no exception is thrown.
For Lookup, if the provider configuration you specify (which includes the connection string, table name, etc.) at design time is incorrect
At runtime, an exception is thrown; no property gets promoted. No exception is thrown at design time because the Bridge Configuration design surface does not do a validation of the provider configuration.
Important
Only the user credentials are validated at design-time and if the validation is not successful, deployment fails.
For Lookup, if the value of the Lookup property you specify at design time has no match in the provider data source (Microsoft Azure SQL Database table, in this case) at runtime
An exception is thrown; no value gets promoted
For Lookup, if the value of the Lookup property you specify at design time has more than one match in the provider data source (Microsoft Azure SQL Database table, in this case) at runtime
The property is promoted and only one of the matching values from the data source is assigned as a value to the promoted property.
For SOAP, HTTP, XPATH, and Lookup, if the data type specified for the property at design time is different from the data type of the value that the property will have at runtime
Wherever the type conversion is possible, the type is converted and the property is promoted. For example, at design time you define a property as string but the value assigned to that property at runtime is 30, then the value of that property will be “30” (as a string.)
When type conversion is not possible, an exception is thrown, and the property does not get promoted. For example, at design time you define a property as “double” but the value assigned to that property at runtime is “John”. Because “John” cannot be stored in the property as a “double”, an exception is thrown and the property does not get promoted.
Configure the Transform stage for the Request message
In this stage, you can enter the transforms to be used by the bridge. You can also enable or disable the stage.
Add the transforms to the BizTalk Service project. Get started with a Visual Studio project lists the steps. Repeat this step to add any number of transforms that you need for your project.
Double-click the XML Request-Reply Bridge to open the itinerary designer.
Select the Transform stage. In Properties, set IsEnabled to True or False. If True, the stage uses the transforms that you enter for transforming an incoming request message. If False, there is no message transformation and the message is simply passed through to the next stage.
Additional:
To include any custom code that executes before the message enters this stage, set the On Enter Inspector property. See How to Include Custom Code in Bridges.
To include any custom code that executes after the message exits this stage, set the On Exit Inspector property. See How to Include Custom Code in Bridges.
Within the Transform stage, select the Xml Transform activity. In Properties, select the ellipsis button (…) against the Maps property to open Map Selection.
From the list of maps displayed, select the maps that you want to associate with the Transform stage, and then select OK. The maps you added are now listed under Selected Maps on the itinerary designer.
Important
The dialog box only displays those maps for which the source schema (of the map) matches the request message schema you entered in Enter the request schemas (in this topic).
Note
If the IsEnabled property is set to True on the Transform stage and you do not specify a map as part of the Xml Transform activity, the bridge does not thrown an error; neither while configuring the bridge (design-time) nor while processing the message (run-time).
You can add or remove a map by clicking the ellipsis button (…) against the Map property.
Click Save.
Configure the Enrich Stage (post- Transform) for the Request message
Configuring the Enrich stage after a transform stage is identical to configuring an Enrich stage before a transform stage. See Configure the Enrich Stage (and its Properties) for the Request message (in this topic). The only thing to consider while configuring a post-transform Enrich stage is that the properties you defined in the pre-transform Enrich stage are also available in the post-transform Enrich stage. So, if you want to preserve those properties, do not create properties with the same name. If you do, the new property definition overwrites the old property definition.
The post-transform Enrich stage also provides two properties: On Enter Inspector and On Exit Inspector. These properties are used to include custom code as part of the bridge processing. See How to Include Custom Code in Bridges.
Configure the Enrich Stage for the Response Message
The Enrich stage in the response path of an XML Request-Reply Bridge is used to promote properties on the response message that is received from the message receiver and has to be sent back to the message sender. The procedure for configuring an Enrich stage in the response path of an XML Request-Reply Bridge is identical to configuring an Enrich stage for the request message. See Configure the Enrich Stage (and its Properties) for the Request message. Note that the properties you promoted in all the previous Enrich stages within an XML Request-Reply Bridge are available as part of this Enrich stage.
The Enrich stage for the response message also provides two properties: On Enter Inspector and On Exit Inspector. These properties are used to include custom code as part of the bridge processing. See How to Include Custom Code in Bridges.
Configure the Transform Stage for the Response Message
The Transform stage in the response path of an XML Request-Reply Bridge is used to transform the response message that is received from the message receiver to a format that conforms to the schema of the message sender. The procedure for configuring a Transform stage in the response path of an XML Request-Reply Bridge is identical to configuring a Transform stage in a request message. See Configure the Transform stage for the Request message. Note that only those maps are available for selection whose destination schema (of the map) matches the response message schema you specified in Enter the request schemas (in this topic).
The Transform stage for the response message also provides two properties: On Enter Inspector and On Exit Inspector. These properties are used to include custom code as part of the bridge processing. See How to Include Custom Code in Bridges.
Configure the Enrich Stage (post-Transform) for the Response Message
The post-transform Enrich stage in the response path of an XML Request-Reply Bridge is used to promote properties on the transformed response message that is received from the message receiver and has to be sent back to the message sender. The procedure for configuring a post-transform Enrich stage in the response path of an XML Request-Reply Bridge is identical to configuring an Enrich stage in request message. See Configure the Enrich Stage (post- Transform) for the Request message (in this topic). Note that the properties you promoted in all the previous Enrich stages within an XML Request-Reply Bridge are available as part of this Enrich stage.
The post-transform Enrich stage of the response message also provides two properties: On Enter Inspector and On Exit Inspector. These properties are used to include custom code as part of the bridge processing. See How to Include Custom Code in Bridges.
Configure the Reply Action Before Routing the Response Message
While Reply Action is technically not a ‘stage’ in an XML Request-Reply Bridge, it plays a key role in ensuring that any protocol mismatches between the message sender and message receiver are bridged right before the response message is finally sent back to the message sender. See Reply Action.
This section lists the steps on how to configure a Reply Action.
Double-click the XML Request-Reply Bridge to open the itinerary designer.
Select the Send Reply box. In Properties, set the IsEnabled property to True or False to determine whether you want to configure a reply action before sending the response message back to the message sender.
Click the Reply Action activity within the Send Reply box. In Properties, select the ellipsis button (…) against the Reply Action property to open the Reply Actions dialog box.
In Reply Actions, select Add to open the Add Reply Action dialog box. In Add Reply Action, do the following:
Section
Field Name
Description
Property (Read From)
Property Name
Lists all the properties that have been defined in all the previous four Enrich stages in the XML Request-Reply Bridge. When you select a property, you specify that the value of the selected properties be assigned to the relevant message header of the outgoing response 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 response message. You can also use this option to specify 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 four previous Enrich stages
'Fabrikam', is a string constant
Important
You must always specify 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
Specify the message type (SOAP or HTTP), the headers of which would be assigned the value that you specified earlier.
Destination (Write To)
SOAP Header Namespace (only if the Type is set to SOAP)
Specify the namespace of the custom SOAP header to which the value will be assigned.
> [!IMPORTANT] > <P>This field is greyed out if you select a standard header from the <STRONG>Identifier</STRONG> drop-down list. You may choose to enter 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>.</P>Destination (Write To)
Identifier
Specifies the name of message header property to which the value will be assigned.
You can also specify 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.
Click OK in the Add Reply Action dialog box. The dialog boxes should now resemble the following:
.jpeg "Send Actions")
So what does this dialog box depict? It means that the bridge uses the value of property P1 (already defined in one of the previous Enrich stages) and assigns it to the custom SOAP header, PONumber with namespace https://schemas.microsoft.com/integration/promotedpropertiesinfo and then sends the response message back to the message sender.
To update or remove a reply action, you can select it in the dialog box and then click Edit or Remove. Click OK in the Reply Actions dialog box and then click Save to save changes to the Bridge Configuration.
Next
The XML Request-Reply Bridge is configured. You can now connect the bridge to a Line-of-Business system, route messages, and/or deploy the bridge:
Connect to LOB systems from a BizTalk Services Project
Routing Messages from Bridges to Destinations in the BizTalk Service Project
Deploying and Refreshing the BizTalk Services Project
See Also