Create an XML One-Way 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:

• 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

This section lists the steps create an XML One-Way 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 for the XML messages that are processed by the XML bridge.

3. Configure the Decode Stage

4. Configure the Validate stage

5. Configure the Enrich Stage and its Properties

6. Configure the Transform stage

7. Configure the Enrich Stage (post- Transform)

8. Configure the Encode stage

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 One-Way 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 One-Way 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 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 Decode Stage

The Decode stage decodes an incoming text message to an XML message and passes it on the Validate stage in the XML One-Way Bridge bridge. Unlike other stages in the bridge, the Decode stage does not have an IsEnabled property. The IsEnabled property for a stage defines whether the stage processes the message passing through the bridge. The Decode stage does not include this property because whether the message is decoded or not depends on the content type of the incoming message. If a bridge receives a message of ‘text/plain’ content type, the decode stage decodes the message and converts it to an XML message. Rest of the processing at each stage within the bridge happens on the XML message and not the flat file message. However, if a message with the any of the other content types is received by the bridge, the decode stage is not activated and the message is simply passed over to the next stage.

The Decode stage does provide two properties, the 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 Validate stage

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

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 One-Way 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
      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

   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 One-Way 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)

   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 (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 Encode stage

   In this stage, you can enter the flat-file schema to use for converting an XML message into a flat-file message. By the time a message reaches the Encode stage, it is already in the XML format. Depending on how the Encode stage is configured, the message is either encoded to a flat-file format or sent out as an XML message.

   1. Double-click the XML One-Way Bridge to open the itinerary designer.

   2. Select the Encode stage. In Properties, set the IsEnabled property to True or False. If True, the stage uses the flat-file schemas that you enter for encoding the XML message to a flat-file message. If False, there is no encoding and the XML message is sent out from the bridge.

      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 Encode stage, select the Flat File Encode activity. In Properties, click the ellipsis button (…) against the Flat File Schemas property to open the Flat File Schema Selection dialog box.

   4. From the list of flat-file schemas displayed in the dialog box, select the schemas that you want to use to encode the XML message to a flat-file message, and then click OK. At run time when an XML message reaches the Flat File Encode activity, the message type (Namespace#Root) is mapped against the flat file schemas provided as part of the activity configuration. If a match occurs, then that schema is used to convert the XML message to a flat file message. The HTTP header for the converted messages is set to “text/plain”. If a match does not occur, the XML processed is sent out by the Encode stage as-is.

      Note

      If the IsEnabled property is set to True on the Encode stage and you do not specify a flat file schema as part of the Flat File Encode 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 schema by clicking the ellipsis button (…) against the Flat File Schemas property.

   5. Click Save.

   Next

   The XML One-Way 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 Request-Reply Bridge
   Create and Configure a Bridge