Uses and Stages of XML Bridges
This section provides information on the uses and stages of an XML bridge.
Uses of an XML Bridge
The XML bridge can be used to mediate and bridge mismatches between two or more disparate systems that communicate by exchanging XML messages. XML bridges, possibly in conjunction with other Service Bus entities in a message flow, provide a variety of mediation paradigms and scenarios, such as following:
- Message Validation: The XML bridge supports validation of incoming XML messages against an XSD schema. Messages that fail validation are rejected.
- Message Enrichment and Extraction: The XML bridge supports message enrichment through data lookup from other data sources. This is typically useful in real-world scenarios where messages may require contextual data present beyond the message boundaries typically from a configuration store, an external service, or the likes.
The XML bridge also enables you to extract properties from an XML message that can be used for routing eventually. For example, in a purchase order message, the Quantity element can be marked. The message can then be routed based on the value of quantity ordered.
- Message Transformation: The XML bridge supports message body transformations from one XML structure to another. This capability of an XML bridge can also be used to ‘normalize’ a message in scenarios where multiple messages are mapped to a single message. For example, a bridge may need to accept purchase orders in different schemas from different clients but they are eventually transformed into a single purchase order schema required by the organization.
- Location Virtualization: The XML bridge provides primitive location virtualization of backend services. Clients send messages to the XML bridge endpoint exposed on the cloud and not the actual service (which may be on the cloud or on premises). The bridge then routes the messages to the backend service based on routing rules.
Stages of an XML Bridge
This section provides information about the different stages of an XML bridge. Note that each stage is optional and can be turned on or off.
The first stage in the XML bridge is the Validate stage. This provides XSD validation of XML messages against specified schemas. The schemas to use for validation are specified during the configuration of the bridge. A single XML bridge can receive and process XML messages with different schemas. During the validate stage, depending on the incoming message, the corresponding schema is picked and used for validation. Once the message is validated against the schema, the Validate stage promotes the X_PIPELINE_MESSAGETYPE property on the message. The value of the property is a combination of target namespace for the schema and the root node name, for example,
http://IntegrationServices.Schema#RootNode. If the message validation fails either because no matching schema was found or because of an ambiguous match (more than one schema matched), an exception is thrown.
For instructions on how to configure the validate stage, see To configure the Validate stage.
Within the Enrich stage you can enrich a message by creating properties, the values of which can be derived from the incoming message header, an element or attribute in the incoming message body, or through a lookup on an external data source such as Windows Azure SQL Database tables. These properties can then be used for routing messages to destination endpoints and protocol bridging.
Header to Property Assignment
In this operation, you can use a value from the message header and assign it to a property. For example, you could extract the action from the SOAP header, assign it to a property, and then use that property for further processing and/or routing.
For instructions on how to configure the header to property assignment, see To assign message header values to properties.
The Extract operation of the Enrich stage is used to extract the values of specific elements or attributes of the message body itself for use during message routing or further processing.
For instructions on how to configure the extract operation, see To extract values from a message body using xpath.
The Lookup operation of the Enrich stage is used to enrich the message by looking up and including data from sources outside a message boundary. For example, there could be an online retail store that lets users place their orders using their local currency while the backend service for order processing uses one single currency, say Dollars, for any order processing. In such a case, before the message is sent to the backend service, the value of the order has to be converted from the local currency to Dollars. This could be done by looking up another service that provides the latest exchange rates.
For this release, the enrich stage only supports looking up data from Windows Azure SQL Database. In other words, Windows Azure SQL Database is the only lookup ‘provider’ supported for the current release. The information about the lookup provider is stored in a LookupProviderConfigurations.xml, that is added to an Enterprise Application Integration project. You can have multiple providers defined in a single .xml file, corresponding to the fact that you can look up from more than one Windows Azure SQL Database data source as part of a single Enrich stage. A typical provider definition in a LookupProviderConfigurations.xml file looks like the following:
<ArrayOfLookupProviderConfiguration xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/WindowsAzureServiceBus/Bridge"> <LookupProviderConfiguration i:type="SqlTableLookupProviderConfiguration"> <ProviderName>...</ProviderName> <ConnectionString>...</ConnectionString> <QueryInColumnName>...</QueryInColumnName> <QueryOutColumnName>...</QueryOutColumnName> <TableName>...</TableName> </LookupProviderConfiguration> </ArrayOfLookupProviderConfiguration>
In the above excerpt, notice that the type attribute for the LookupProviderConfiguration element is fixed to SqlTableLookupProviderConfiguration. This is because currently you can only look up a table in Windows Azure SQL Database.
There are also some considerations while looking up data from a Windows Azure SQL Database.
For instructions on how to configure the lookup operation, see To lookup an external data source.
While the information about the providers is stored in the LookupProviderConfigurations.xml, the information about which values to assign from header to message properties, what values to extract, and what values to lookup are stored in a bridge configuration file. When you build a Enterprise Application Integration project, the LookupProviderConfigurations.xml also rolls up into a bridge configuration file. When you deploy the Enterprise Application Integration project, it is this bridge configuration file that gets deployed to the Service Bus.
What Can I do with the Properties?
In the Enrich stage, you create properties and assign values to those properties. But the question that comes to mind is what can I do with these properties? How do these properties make my task easier? You can use the properties in two ways:
You can use the properties to set filter conditions to route messages to different destinations. For instructions on how to achieve this, see The Routing Condition.
You can use the properties to bridge protocol mismatch between the message sender and the message receiver. For example, you have an incoming SOAP message that has a custom header value. You want to pass on this value as the custom header of an HTTP message because the message receiver wants a REST message and does not understand a SOAP message format. You can use properties to do so. You can first assign the value from the incoming message header to a property, say P1, and then while sending the message to the receiver, assign the value of P1 to the message header of the outgoing message. For more information, see Route and Reply Actions: Bridging Protocol Mismatch .
What is the Lifetime of the Properties?
Within a Bridge Configuration, the properties that you define as part of the Enrich stage are available throughout the flow of the message for each stage in Bridge Configuration. In other words, if you defined a property in the Enrich stage, you can use that property during the Transform stage as well as for any map operations. The properties defined in the Enrich stage can also be used outside the boundary of a Bridge Configuration, with some considerations. Before we go into the details of that, we must understand that the property values are stored as properties of the Service Bus BrokeredMessage class. Now that we are aware of this fact, let’s talk about the lifetime of the properties outside a Bridge Configuration.
Because only a Service Bus Queue or a Topic can consume messages of BrokeredMessage type, the properties and their values (as a key-value pair), can directly be consumed by Queues and Topics. After that, Topics for instance, can potentially use the properties for further processing and routing
You cannot pass on the properties and their values to other Bridge Configuration components like One-Way/Two-Way Relay Endpoints or One-Way/Two-Way External Service Endpoints. If you do want to pass the property values to these entities, you must assign the property values to the headers of the outgoing message. For more information, see Route and Reply Actions: Bridging Protocol Mismatch.
In a “chaining” scenario where the message from one bridge is routed to another bridge and then finally to a Service Bus Queue (for example), only the properties from the last bridge in the chain are available for any further routing or processing. Also, to pass property values to the subsequent bridges, property values must be assigned to the headers of the outgoing message. These properties must then be extracted in the second bridge.
The Transform stage, as the name suggests, provides the capability to perform structural transformations on the messages. Like the other stages in the pipeline, the Transform stage can work with multiple message-types, so you can have more than one transform available as part of the transform stage. The right transform to be performed is automatically looked up at runtime based on the incoming message type, provided the corresponding transforms have been configured and uploaded while configuring the bridge. The transform resolution happens based on the message type of the incoming message.
The Transform stage matches the message type of the message with the message type of the source schema in a map.
If the validation stage is turned off, the transform stage matches the incoming message with the source message schema. If the resolution happens, it then promotes the MessageType property on the message.
The current release only supports single source to single destination transforms. For more information, see Transforms. For instructions on how to configure the Transform stage, see To configure the Transform stage.
Enrich Stage – Post Transform
The Enrich stage, post transform, is similar to the Enrich stage before transform. The only difference is that in the post-transform Enrich stage, you can enrich the transformed message. The way you configure the Enrich stage remains the same as pre-transform Enrich stage. For instructions on how to configure the Enrich stage, post transform see XML One-Way Bridge : Configuring the Enrich Stage (post- Transform) for the Request Message.
|All the properties extracted or looked up before the transform stages are also available on the transformed message. A previously extracted or enriched property will be overwritten if it is modified in the post-transform enrich stage.|
Artifacts for an XML Bridge
In the previous section we saw that in the Validate stage, the validation happens against schemas and in the Transform stage, the message is transformed using a transform. So, the artifacts those are available as part of an XML bridge are:
- Schemas. These have .XSD extension
- Transforms. These have .TRFM extension and there can be multiple transforms within a Transform stage.
|A bridge configuration file is not an artifact because it cannot be shared between different bridges. A bridge configuration file is specific to a bridge.|
An Enterprise Application Integration application can have multiple bridges and each bridge can be using multiple transforms and schemas. So, a typical Service Bus EAI and EDI Labs application would have a large number of transforms and schemas. However, at the same time, every transform and schema might not be required for each XML bridge. Hence, there must be a way to associate the transforms and schemas to a bridge. You can do this association while configuring the bridge.
For instructions on how to associate schemas, see XML One-Way Bridge : Specifying the Schemas for the Request Message and XML Request-Reply Bridge : Specifying the Schemas for the Request and Response Messages
For instructions on how to associate transforms, see XML One-Way Bridge : Configuring the Transform Stage for the Request Message
© 2011 Microsoft Corporation. All rights reserved.