Orchestrations

Introduction

Orchestrations are an optional component in your BizTalk projects, as you can simply make a solution with orchestrations respond to integrations that required more complex logics or respond to business process flows.

In a very simple way, orchestrations are a representation of the business process in a visual way ( the association of links between shapes, representation of ports, and some configurations) that can subscribe to (receive) and publish (send) messages through the MessageBox database, making it easier to manage and read than textual language (C#, Java). It simplifies the process of creating orchestration models of business processes that are compiled into executable code. Or, we can say that it is a BizTalk artifact representing an arbitrary portion of a business process.

Important benefits of using BizTalk orchestrations include:

• Handling different types of transactions.
• Better error handling.
• Defining correlation types between messages for asynchronous processes.

Adding an orchestration to your project is easy; just right-click your project in the Solution Explorer and select Add > Add New Item > Orchestration. BizTalk will open an Orchestration Editor so that you can start developing your orchestration.

Orchestration Editor

As you can see in the previous figure, the Orchestration Editor is divided into four main work areas. These areas are:

Toolbox

This is where all the tools available to create the business logic of your orchestration (workflow) are available. Drag and drop them to the Orchestration Designer to use them.

Orchestration Designer

This is where you design your orchestration or your business process in a visual way. Using a drag-and-drop operation, you add the tools you need to build the orchestration. This is a very helpful component, as it allows you to see your orchestration workflow.

Orchestration Overview

This is where you can create your messages, port, variables, and any other allowed object to use inside the orchestration.

Properties Window

The Properties window is common to every Visual Studio-based project; it allows you to set selected object properties.

Available Shapes

The toolbox available for the Orchestration Editor displays multiple shapes for you to use in order to set up your business processes. With these shapes, you will be able to add intelligence to the business processes, applying business rules and conditions so that in runtime the messages take their correct flow. The following table shows you the available shapes in the toolbox.

Available shapes for orchestrations

Available shapes for orchestrations II

Available tools for orchestrations III

Creating a Simple Orchestration

We will be creating step-by-step a simple orchestration in which you receive a message, apply a pre-created map, and then send it through a send port. After creating the orchestration, we will deploy the project and set up the application with the BizTalk Server Administrator.

To create our Project, we must start with the input and output schemas. These are very simple as we are going to transform a schema containing records with just three elements (First Name, Middle Name, and Last Name) into a schema containing just one full name record. Our schemas are shown in Figures 52 and 53:

Destination Schemas

Source Schemas

Our map is going to be pretty simple as well. In the following map you can see that we will loop through all person records in the XML document and then evaluate if the name is a string, and if it is, map it to a concatenate functoid, and link the result of the concatenate functoid with our destination node.

.

Map example

After developing all our schemas and maps, we can start our orchestration development. To do so, right-click your project in the Solution Explorer and click Add New Item. In the new item selection screen, select Orchestration. BizTalk will then open the Orchestration Editor.

Once the Editor opens, drag the receive shape and drop it into the designer as shown in Figure 55. It’s a best practice to rename to shapes to names that will suggest their function and execution.

Add receive shape

Next, add the transformation shape to the designer, and add the send shape. This will allow you to set up a process in which a message is received, transformed using a map, and sent to a location using the send shape. As you can see in this very simple example, however, orchestrations can become complicated when you start adding intelligence to them. Once you add the three shapes, you should have an orchestration as shown in Figure 56.

Example orchestration

After designing our orchestration, it’s now time to configure it, setting up the messages and ports it will use. Let’s start with the messages. Just as we have one source schema and one destination schema, we are going to have two messages as well—one based in the source schema, and another based on the destination schema. To create a new message, right-click the Message folder in the Orchestration View panel and select New Message.

New Messages

BizTalk will open the New Message properties in the Properties window. Give the message a name, and in the Message Type property, select the schema it should be based on, as illustrated in Figure 58.

Configure New Messages

In this example we are going to create two messages: one called MsgInput, for the Source Schema message type, and another one called MsgOutput, for the Destination Schema message type. When you finish creating and configuring both, your message folder should have the messages shown in Figure 59.

Messages created

After creating the messages, it’s time to tell our receive/send shapes which message type they should be expecting when a document arrives to one of their ports. In this example, we have one receive shape and one send shape. To start with the receive shape, click it in the designer and, in the Properties window, configure the Message property to MsgInput. Set the Send Shape property to MsgOutput.

Configure Receive/Send shape message

Now, let’s set up our transformation shape. Double-click it, and the Transform Configuration window will appear. Figure 61 shows you this screen.

Transform Configurations

In this configuration screen, you are going to tell the orchestration how it should transform the MsgInput when it arrives. Choose the Existing Map radio button on top of the screen, so that we can select our created map. Next, select our map in the Fully Qualified Map Name property. Last, we need to tell the transform shape which is the input message and which is the output message. Select our already created messages in the respective Variable Name combo box.

As you can see, we haven’t defined any receive or send ports, just the shapes. Note that these are just logical ports, not physical ports; those are going to be configured later in the BizTalk Server Administrator.

To configure these logical ports in the orchestration, you need to drag and drop the port shape to the Port Surface lane of the the orchestration designer. There are two Port Surfaces, one for receive ports on the left, and another for send ports on the right of the designer. Figure 62 shows you the receive ports lane.

Receive ports lane

Now let’s add the first port to the orchestration—the receive port. To do so, drag and drop it to the port surface lane on the left. Once you drop it, BizTalk will launch the Port Configuration Wizard, as you can see in Figure 63.

Port configuration Wizard

The first step in this wizard is naming the port.

Port configuration Wizard—Name

Once you click on Next, the wizard will take you to one of the most important screens in the Port Configuration Wizard, where you set up the Port Type, which defines the direction of your port (one or two way) and the access restrictions. The following figure shows this Port Configuration Screen.

Configure Port Type

The first configuration item lets you choose between an creating a new port type and using an existing one. For our example, select Create a new Port Type.

Next, give your port type a name and select One-Way as the Communication Pattern. This one-way option defines that your port will only receive or send messages. We will choose this one because we are going to transform our received message, and only after that send it, so we need to create two distinct ports—one to receive, and another to send. However, if you wanted to receive and send to a partner without any transformation, or even communicate with a web service in which you send a request and receive a response, you could use the Request-Response pattern.

The available access restriction lets you define who can use this port type: only this module (Private), only the artifacts allowed to use port types within this project (Internal), or everyone (Public). Let’s choose the Internal option for our example, as this will be a single project port type. Although we will be choosing the internal options, as you can see, there are three types of access restrictions:

• Private—This port type can be used only within this orchestration
• Internal—This port type can be used across different orchestrations within this project
• Public—This port type can be used by anyone in any project

After defining your port type, select Next to open the Port Binding screen of the Configuration Wizard. As you can see, you haven’t yet defined whether this is a receive or a send port; this configuration is set in this screen. Now, as we are creating a receive port, lets choose I’ll always be receiving messages on this port under Port direction of communication. Under Port binding, choose Specify later, as we are binding the ports with the BizTalk Administrator later. Click Next.

Configure receive port type

Port Binding is the configuration information that determines where and how a message will be sent or received. Depending on its type, a port binding might refer to physical locations, pipelines, or other orchestrations. There are three types of port bindings for receive messages:

• Specify Now—Allows you to specify at design time what pipeline you want to use and the location you want to communicate with. It is also called “Binding at Design Time.”
• Specify Later—If you do not have all of the information you need to specify a physical location, you can select the Specify Later port binding option in the Orchestration Designer, and you only need to specify the port type that describes the port. Also called “Binding at Deployment Time.”
• Direct—Your orchestration can communicate directly with another orchestration by using direct binding. In this case, the message is processed internally by the engine, and no external transport of the message takes place.

There is one last port binding type, which is restricted to send messages:

• Dynamic—If you will not know the location of a communication until run time, you can use dynamic binding for a send port. The location might, for example, be determined from a property on an incoming message.

When the wizard is complete, BizTalk will take you back to the orchestration designer. Now it’s time to link this recently created receive port to our receive shape. This is how you tell the orchestration that those receive messages will arrive from this port and port type.

Figure 67 shows you how your orchestration should look at this point:

Link the port to the receive shape

Now, repeat this process for the send port. Drag and drop the port shape to the Port Surface on the right of the designer, and configure your port using the Port Creation Wizard, giving attention to the step in which you define if your port is a receive or send port. The following figure illustrates the Port Binding step.

Configure send port

To finish the design of our orchestration, link the recently created send port to the send shape, and your orchestration should look like Figure 69.

Final orchestration examples

Even though it might look like it’s complete, you still need to make several configurations before compiling and deploying your application to the BizTalk Server. The first mandatory step is to set an active receive shape, as BizTalk requires that at least one receive shape is listening to message arrival in our orchestration. This is a common error for those new to BizTalk Server. Figure 70 shows you the error message when you try to compile your application without an active receive shape.

Error when there is no active receive shape

To avoid this problem, you should select the receive shape you want to activate, and in the Properties window for your receive shape, set the Activate property to True.

Activate receive shape

Now your application is ready to be compiled and deployed to the BizTalk Server. The next chapter will show you how.