Create an XML Request-Reply Bridge

This section lists the steps create an XML Request-Reply Bridge in a BizTalk Service project. XML bridges have different stages. In this topic:

1. Add the Bridge to the BizTalk Services project

2. Enter the request schemas

3. Configure the Validate stage for the Request message

4. Configure the Enrich Stage (and its Properties) for the Request message

5. Configure the Transform stage for the Request message

6. Configure the Enrich Stage (post- Transform) for the Request message

7. Configure the Enrich Stage for the Response Message

8. Configure the Transform Stage for the Response Message

9. Configure the Enrich Stage (post-Transform) for the Response Message

10. Configure the Reply Action Before Routing the Response Message

Add the Bridge to the BizTalk Services project

1. Create a BizTalk Service project. Get started with a Visual Studio project lists the steps.

2. Right-click anywhere on the BizTalk Service project design area and select Properties. In BizTalk Service URL, enter your BizTalk Services URL.

3. 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.

4. 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.

5. 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.

1. 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.

2. 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.

3. On the bridge design area in the Message Types box, select the add icon [ ] to open Message Type Picker. In Message Type Picker:

   1. From the Available message types box, select the schema for the Request message.

   2. Select the right arrow icon [ ] to associate the Request schema with the bridge.

   3. Select the right arrow icon [ ] under Response Message Type to associate the Response schema with the bridge.

   4. 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 [ ].

      • To replace one schema association with another, click the edit button [ ] to reopen Message Type Picker.

4. 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.

1. Double-click the bridge to open the Bridge Configuration design area.

2. 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.

3. 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.

4. 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:

1. Double-click the XML Request-Reply Bridge to open the itinerary designer.

2. 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.

3. Within the Enrich stage, select the Enrich activity. In Properties, select the ellipsis button (…) against the Property Definition property to open Property Definitions.

4. 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

1. 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.

   2. Click OK in the Add Property dialog box. The dialog boxes should now resemble the following:

      

      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.

   3. 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

   1. 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

   1. 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.

   2. Click OK in the Add Property dialog box. The dialog boxes should resemble the following:

      

      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.

   3. 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

   1. 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.

   2. Click OK in the Add Property dialog box. The dialog boxes should resemble the following:

      

      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.

   3. 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.

   1. 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.

   2. Double-click the XML Request-Reply Bridge to open the itinerary designer.

   3. 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.

   4. Within the Transform stage, select the Xml Transform activity. In Properties, select the ellipsis button (…) against the Maps property to open Map Selection.

   5. 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.

   6. 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.

   1. Double-click the XML Request-Reply Bridge to open the itinerary designer.

   2. 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.

   3. 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.

   4. 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.

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

         

         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.

      6. 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

      Create an XML One-Way Bridge