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.
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.
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)
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.
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;
|
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");
|
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.
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.
|
|
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.
