SALES: 1-800-867-1380

XML Bridge : Configure the Enrich Stage for the Request Message

Updated: November 21, 2013

As the name suggests, 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 supported in this release), 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 topic lists the steps for performing each of these 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

Over and above this, you can specify whether you want to perform any of these actions by turning the Enrich stage on or off.

  • The property names you enter in this stage are not case-sensitive.

  • The property you enter in this stage is not be 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.

This section provides information on how to configure the enrich stage and by using properties and values from different sources, as mentioned above.

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

  2. Select the Enrich stage. In Properties, set the IsEnabled property to True or False.

    noteNote
    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:

  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

    To assign message header values to properties

    Use system-promoted properties

    To use system-promoted properties

    Look up an external data source

    To lookup an external data source

    Extract values from within the message using XPath

    To extract values from a message body using xpath

To assign message header values to properties

  1. In Add Property, do the following:

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

    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:

    <s:Header>
       ...
      <MessageType xmlns="http://schemas.microsoft.com/integration/2011/system-properties">http://POAttr.org#PurchaseOrderAttr</MessageType> 
       ...
    </s:Header>
    
    ImportantImportant
    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.

    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:

    <s:Header>
      ...  
      <PONumber xmlns="http://schemas.microsoft.com/integration/promotedpropertiesinfo">PO1234</PONumber> 
      ...  
    </s:Header>
    

    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.

    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:

    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 http://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:

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

    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.

    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:

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

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

    Identifier

    From the drop-down list, select an already configured provider

    If you haven’t already configured a provider, then configure one:

    1. From the Identifier drop-down list, select Configure New.

    2. In the Provider Configuration dialog box, specify the following values:

       

      Field Name Description

      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.

    3. Click OK to add the provider configuration.

    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.

    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:

    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.

  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:

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

    Identifier

    Specify the xpath query to extract an element or an attribute from a message. A typical xpath query looks like the following:

    /*[local-name()='<root_node>' and namespace-uri()='<namespace>']/*[local-name()='<node_name>' and namespace-uri()=<namespace>']/*@[local-name()='<attribute_name>' and namespace-uri()='<namespace>']
    

    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.

    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:

    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.

  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.

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.

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

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft