BizTalk 2010 Recipes : Orchestrations - Receiving Messages

4/3/2011 11:30:40 AM

1. Problem

You are building a solution that requires the implementation of a business process. You must configure an orchestration to receive messages, which begins the business process.

2. Solution

BizTalk Server orchestrations receive messages either through a Receive shape or directly from another orchestration as an orchestration input parameter. A Receive shape allows messages to be routed from the MessageBox to the orchestration, as demonstrated in this solution.

To create an orchestration that receives messages via a Receive shape, follow these steps:

Open a project that contains a schema that represents the message that will be received.
Right-click the project in Solution Explorer, and select Add→New Item.
In the Add New Item dialog box, select Orchestration Files from the Installed Templates list, choose the BizTalk Orchestration template, and give a descriptive name to your new orchestration, as shown in Figure 1. In our example, the orchestration is named ReceiveShapeOrchestration. Then, click Add.

Figure 1. Adding a new orchestration to a project
In the Orchestration View window, expand the top node of the tree view (this node will have the same name as the orchestration), so that the Messages folder is visible. (If the Orchestration View window is not visible, select View→Other Windows→Orchestration View.)
Right-click the Messages folder, and select New Message, which creates a message called Message_1 by default.
Click the new message, and give it a descriptive name in the Properties window. In our example, the message is named msgCustomerMessage.
Click the Message Type property in the Properties window, and select the appropriate type to associate with the message, as shown in Figure 2 . In our example, we select the CustomerSchema message type.
NOTE

Notice all of the types available for setting the message. A very common option is to set a message to System.Xml.XmlDocument, which allows an XML document of any format to be received (rather than strongly typed against a specific XSD). Of course, subscribing to the generic XMLDocument will cause all documents on the MessageBox to be picked up, so make sure your filtering is set up!

Figure 2. Creating a message
From the toolbox, drag a Receive shape onto the orchestration directly beneath the green circle at the top of the design surface.
NOTE

In addition to dragging and dropping shapes from the toolbox, you can also add shapes to an orchestration by right-clicking a section of the vertical process flow arrow and selecting Insert Shape.
With the Receive shape selected, specify the shape's Name, Message, and Activate properties, as shown in Figure 3. The Message property is set via a drop-down list, which is populated with all the messages that are in scope for the Receive shape. The Active property is also set via a drop-down list, with the choices True or False. In our example, we use ReceiveCustomerMessage, msgCustomerMessage (created in step 6), and True, respectively.

Figure 3. Adding a Receive shape
To configure a port and port type for the orchestration to use to receive a message, right-click the Port Surface area, and select New Configured Port. This will start the Port Configuration Wizard.

Step through the Port Configuration Wizard, specifying the following items (accept all other defaulted values):

Port name: oprtReceiveCustomerMessagePort.
New port type name: oprtTypeCustomerMessagePortType.
Port binding: Select Specify Now, and configure the appropriate receive adapter to consume inbound messages, as shown in Figure 4 . In this example, we configure the port to use the FILE adapter, which receives XML messages from the C:\Users\Administrator\Desktop\Drops\ReceiveShapeOrchestration folder.

Using Specify Now as your method of port binding can make your development and deployment process easier, but be careful when using this feature. It is not the recommended method for production code, because you should not embed port bindings inside an orchestration. A better approach is to use a binding file.

Figure 4. Configuring an orchestration port for receiving messages

Connect the orchestration port's request operation to the Receive shape, as shown in Figure 5.

Figure 5. Connecting an orchestration port to a Receive shape
The project can now be deployed. During the deployment process, the port will automatically be created, along with all bindings to the orchestration (this does not happen when a port is set up using the Specify Later option). Figure 6 shows the port created for this solution.

Figure 6. The receive port created automatically during deployment

3. How It Works

Understanding how messages are received into orchestrations is critical when designing and implementing orchestrations in BizTalk Server. Receive shapes are the most common method used to deliver messages to orchestrations. In this recipe's solution, we showed how to add a Receive shape to an orchestration, configure the Receive shape's Message Type and Activate properties, and connect it to a receive port.

If the Receive shape is the first shape in the orchestration, it must have its Activate property set to True. If an orchestration does not have an activating Receive shape, it must be called or started (instantiated) from another orchestration.

The data a Receive shape accepts is defined by its Message property, which relates to a message that has been defined within the orchestration. All messages in BizTalk are bound to a specific type, which can be an XSD schema or a .NET class. This allows orchestrations to receive instances of XSD schemas or .NET classes as inputs. While our example used a single Receive shape, orchestrations can use many Receive shapes to accept different types of messages at different points in the business logic.

Each Receive shape must be bound to an operation, or orchestration port. An orchestration port is the interface through which messages pass on their way into or out of orchestration instances. Orchestration ports define the direction messages flow (receiving into an orchestration, sending from an orchestration, or both), and are bound to a physical port, another orchestration, or directly to the MessageBox database. Binding orchestrations is important to understand the methods by which orchestration ports can be bound and how they affect the way messages are received into an orchestration:

Physical receive port: All messages that are consumed by the specified receive port are routed to the orchestration. This setting creates subscriptions in the MessageBox database, which deliver messages passing through the physical receive port to the orchestration port.
Another orchestration: Only those messages explicitly being passed from the calling orchestration are routed to the orchestration.
Directly to the MessageBox: All messages in the MessageBox database that validate against the Receive shape's message type are routed to the orchestration.

Each Receive shape has a number of properties associated with it, as listed in Table 1.

Table 1. Receive Shape Properties
Property	Description
Activate	Flag indicating whether the Receive shape activates the orchestration instance.
Description	Summary of the Receive shape.
Filter Expression	A filter that is applied to all messages being received via the Receive shape.
Initializing Correlation Sets	A list of correlation sets that are initialized as messages pass through the Receive shape.
Following Correlation Sets	A list of correlation sets that are followed as messages pass through the Receive shape. This property is not available on the first Receive shape of an orchestration.
Message	The message that will be created when a document is passed through the Receive shape. A message with a message type of XmlDocument can be used to receive a generic XML message, without limiting documents to a specific XSD schema.
Name	Name of the Receive shape.
Object Type	Name of the object type (read-only, automatically set to Receive).
Operation	Specifies through which orchestration port operation the Receive shape receives its message.
Report To Analyst	Flag indicating whether the message part should be exposed via the Visual Business Analyst Tool.

The Filter Expression property allows you to be a bit more specific about which messages make it into your orchestration. Clicking the ellipsis in the input box for the Filter Expression property launches the Filter Expression dialog box. This dialog box allows you to create specific filters, which include one to many logical expressions that must be met in order for a message to be received into the orchestration. These logical expressions are based on a property, an operator, and a value and can be grouped by using the And and Or keywords.

A filter expression can be set on only a Receive shape that has its Activate property set to True. When the value portion of the filter expression is a string, you must put double quotes around the actual value for the expression to work properly.

The Initializing Correlation Sets and Following Correlation Sets properties specify which correlation is followed when messages are received on the Receive shape. Generally speaking, correlation sets allow you to send and receive messages in and out of orchestrations that directly relate to one another.