BizTalk 2010 Recipes : Document Mapping - Passing Orchestration Variables into Maps

3/29/2011 3:31:07 PM

1. Problem

You need to include information from variables in an orchestration in the destination message of a BizTalk mapping.

2. Solution

Begin by creating a new message schema with fields for capturing the information from the orchestration, as shown in Figure 1 . The information from the orchestration variables must be set in a separate message from the input message, referred to here as a context message. In this recipe, the mapping will transform a customer purchase message for the customer support department, and the orchestration will define the support information with the business process. BizTalk will use the new message schema to capture the support information.

Figure 1. Defining the context message schema

Follow these steps to set up the orchestration.

To access the fields of this message easily from within the orchestration, define them as distinguished fields. Right-click the context message schema tree, and select Promote => Show Promotions. In the Promote Properties dialog box, select each field in the left window, and click the Add button, as shown in Figure 2. Then click OK.

Figure 2. Designating the distinguished fields
Define the following orchestration properties on the Orchestration View tab (see Figure 3):
- Messages
  - msgInputMessage (map to the Input message schema)
  - msgOutputMessage (map to the Output message schema)
  - msgContext (map to the MapContext schema)
- Orchestration variables
  - strSupportCode (a string)
  - strSupportCodeExpires (also a string)
  - xmlXmlDoc (of type System.Xml.XmlDocument)
Figure 3. The orchestration messages and variables
In the Orchestration Designer, drag a Message Assignment shape from the toolbox onto the orchestration surface. In the properties of the Construct Message shape that appears around the Message Assignment shape, specify msgContext as the only message constructed, as shown Figure 4.

Figure 4. The Construct Message
Double-click the Message Assignment shape to open the BizTalk Expression Editor window. Load an XML string conforming to the schema of the context message into the xmlXmlDoc variable. Then create the msgContext message by assigning the loaded XmlDocument variable to it. This example uses the code shown in Listing 1 and in Figure 5.

NOTE

Obtain a sample XML string by right-clicking the schema in the Solution Explorer and selecting Generate Instance. Copy and paste this into the LoadXml method.

Example 1. Build the Context Message

xmlXmlDoc.LoadXml("<ns0:MapContext xmlns:ns0=
'http://PassingOrchestrationVariablesIntoMaps.MapContext'>
<SupportCode>SupportCode_0</SupportCode> <SupportExpires>SupportExpires_0</SupportExpires>
</ns0:MapContext>");

msgContext = xmlXmlDoc;

Figure 5. The Message Assignment

Once instantiated, the values in MapContextMsg can be set anywhere in the orchestration. For simplicity in this example, they are created and set in the same Message Assignment shape, and the expiration is the same day that the context message is created, as shown in Listing 2 and Figure 6.

Example 2. Set the Values in the Orchestration

msgContext.SupportCode = "R-2";
msgContext.SupportExpires = System.DateTime.Now.ToString("yyyy-MM-dd");

Figure 6. Setting the values of the context message

Once the context message contains the required orchestration information, the BizTalk orchestration must create the mapping. The orchestration must create mappings that have more than one source or destination message.

Drag a Transform shape onto the Orchestration Designer surface.
Double-click the new Transform shape to open the Transform Configuration dialog box.
Specify the source messages to be the msgInputMessage and MapContextMsg messages, as shown in Figure 7.

Figure 7. Configuring map source messages
Specify msgOutputMessage for the destination message, and then click OK.

BizTalk will generate a new transformation with two input messages and one output message. One of the input messages will be the MapContextMsg message containing the values from the orchestration. The developer can choose to either drive mapping logic from these values or map them directly to the destination message as in this example, as shown in Figure 8.

BizTalk may not be able to recognize the second schema if the project name begins with a number.

Figure 8. Defining mapping logic from the source messages

3. How It Works

BizTalk developers often think about translation among message types when defining integration processes in an orchestration. They can place a Transform shape directly within an orchestration to transform a message into different formats, so it seems that the transformation and orchestration are integral to each other. However, the BizTalk mapper cannot directly access the contextual information of the business process and the logic existing in the orchestration.

The BizTalk Mapper can natively access many resources outside the map with the default functoids. For example, the Database Lookup functoid can access records in a database, and the Scripting functoid can invoke an external assembly. However, the most direct way to access information about the context of the business process is by creating a message specifically for capturing the state of the business process. Add the information required in the mapping to this additional message, and then add the context message as an additional input message to the map.

The possible reasons for passing information from an orchestration into a mapping with a second message are as varied as the capabilities of BizTalk orchestrations. However, in all cases, the mapping destination message must contain information that cannot or should not be added to the schema of the input message. Here are some examples:

A standards body such as RosettaNet sets the source message schema, and it should not change.
The mapping must access message context properties. A map cannot access these values. For example, if the SMTP adapter is used, an orchestration can access the sender with the SMTP.From property but not directly from the BizTalk Mapper. The destination message may need this information.
The mapping must include information about the business process that is not known until runtime and is required in the orchestration. Rather than duplicating the logical definitions, define each definition once within the orchestration and pass the information to the mapping.
BizTalk must be capable of modifying the mapped values without redeploying the BizTalk artifacts. For example, the BizTalk rules engine can be easily invoked from within an orchestration and facilitates additional capabilities like rule versioning and seamless deployment.