Экспорт (0) Печать
Развернуть все

XML One-Way Bridge : Configuring the Enrich Stage for the Request Message

Обновлено: Ноябрь 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, from an external data source (only База данных SQL Microsoft Azure 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. In this section, we will go through the procedures for performing each of these actions, namely:

  • Assigning message header values to properties. See

  • Using default properties or system properties promoted by Службы BizTalk.

  • Looking up an external data source

  • Extracting 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.

There are a few things you must consider when defining properties in the Enrich stage.

  • Property names you specify in the Enrich stage are not case-sensitive.

  • The property you specify in an Enrich stage will not be available for Route or Reply Actions unless you save the Конфигурация моста. For more information about Route and Reply actions, see Route and Reply Actions: Bridging Protocol Mismatch.

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

To configure the Enrich stage

  1. Double-click the Односторонний мост XML component to open the itinerary designer.

  2. Select the Enrich stage, and from the Properties pane, set the IsEnabled property to True or False.

    noteПримечание
    If the IsEnabled property is set to True and there is no property defined, the мост does not throw an error, neither while configuring the мост (design-time) nor while processing the message (run-time).

  3. If you want to include any custom code that must be executed before the message enters the Enrich stage, set the On Enter Inspector property. Similarly, if you want to include any custom code that must be executed after the message exits the Enrich stage, set the On Exit Inspector property. For more information, on how to set these properties, see How to Include Custom Code in Bridges.

  4. Within the Enrich stage, select the Enrich activity, and then from the Properties pane click the ellipsis button (…) against the Property Definition property to open the Property Definitions dialog box.

  5. In the Property Definitions dialog box, click Add to open the Add Property dialog box. In the Add Property dialog box, 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 the Add Property dialog box, 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 either 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 will be outlined in red and the other fields will be greyed out.

     

    Section Field Name Description

    Source (Read From)

    Type

    Specifies the message type from which the header values will be 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>
    
    ImportantВажно!
    This field will be 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.

    Let’s take an example here to understand this better. 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 will get 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 will be 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 will be 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:

    Определение свойства

    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 respectively. Click OK in the Property Definition dialog box and then click Save to save changes to an Конфигурация моста.

To use system-promoted properties

  1. In the Add Property dialog box, 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 will be outlined in red and the other fields will be 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 will be 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 the Add Property dialog box, 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 will be outlined in red and the other fields will be greyed out.

    ImportantВажно!
    For this release, you can only lookup from a База данных SQL Microsoft Azure 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, perform the following steps to 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 База данных SQL Microsoft Azure table

      Table Name

      Specify the База данных SQL Microsoft Azure table name from which you want to do a data lookup

      Query In Column

      Specify a column name in the База данных SQL Microsoft Azure table, the values of which will be used as the input query for performing the data lookup

      Query Out Column

      Specify a column name in the База данных SQL Microsoft Azure table, the value of which will be the output value that will eventually get 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 will be 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 will contain the looked up value. The value of this property will be 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:

    Просмотр определения

    So what do these dialog boxes depict? This is how the logic flows (explained using the same purchase order example as above):

    • The мост 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 мост 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 respectively. Click OK in the Property Definition dialog box and then click Save to save changes to an Конфигурация моста.

To extract values from a message body using xpath

  1. In the Add Property dialog box, 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 will be outlined in red and the other fields will be 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 would look 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. 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 will be 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:

    Извлечение с помощью запроса Xpath

    So what does this dialog box depict? It means that from a message type (PurchaseOrder, in this example), the мост 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 respectively. Click OK in the Property Definition dialog box and then click Save to save changes to an Конфигурация моста.

At design-time using the Конфигурация моста 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, when a message flows through the мост deployed on Служебная шина. However, at runtime there could be instances when the property promotion fails due to various reasons. Using the table below, let us now understand how and when that might happen.

 

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 мост 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 мост 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 Конфигурация моста 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 (База данных SQL Microsoft Azure 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 (База данных SQL Microsoft Azure 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.

Добавления сообщества

ДОБАВИТЬ
Корпорация Майкрософт проводит интернет-опрос, чтобы выяснить ваше мнение о веб-сайте MSDN. Если вы желаете принять участие в этом интернет-опросе, он будет отображен при закрытии веб-сайта MSDN.

Вы хотите принять участие?
Показ:
© 2014 Microsoft