05 May

BizTalk, WIF, WF Tutorial – Part 2.3a Message content based routing – orchestration

In the previous part we discovered very basic capabilities of BizTalk Server 2010. We decided to implement and actually implemented a simple message routing Business Process that awaited a file as its input and produced XML result in the output directory. As the process was very simple we didn’t even bother to model it in any Business Process Modeler. This time, in spite of the fact, that the process once again is very simple, we decide to model the process so that everyone knows what is going to happen and when.

BizTalk, WIF, WF Tutorial - Part 2.3a - Business Process Model (BPMN)

Here’s our today’s simple business process named Mail filtering. As in every large organization our company needs someone or something (automata) to filter incoming mail too. In our case we consider an e-mail to be a XML file dropped into already known IN-Folder. This time however, we are not going to use simple BizTalk Filters which we configured on the Send Port in order to create a subscription for incoming messages. This time we need a decision based on content and not on the technical information connected to the protocol, file system, BizTalk variables etc. This time we need a fully qualified, well formed input message that will be later routed. Implementing this process is also possible with the use of only ports but we will do this in the next part.

Orchestration

This already well adopted and defined term is in its simplest definition, a series of actions which are invoked to integrate one or more WebServices. Despite we’re not using any WebServices in our example; its definition is totally OK. In BizTalk orchestration are not aware of the implementation of its output and inputs. We model them as special objects on the orchestration diagram and only through configuration in BizTalk Server Administration Console we tell them with who and how (e.g. which protocol) they should communicate.

Creating a new BizTalk Project to transform BPMN into a BizTalk Orchestration

In order to start transforming our BPMN process model shown above into BizTalk Orchestration we need to create a new BizTalk project. We launch installed Visual Studio 2010 Ultimate calling Start Menu -> Visual Studio 2010 -> Visual Studio 2010.

BizTalk, WIF, WF Tutorial - Part 2.3a - Visual Studio 2010 Start Page

We choose New Project… on Start Page.

BizTalk, WIF, WF Tutorial - Part 2.3a - Creating a new BizTalk project

From the Installed Templates list we choose BizTalk Projects and the first one available that is Empty BizTalk Server Project. Let’s name our new project MusialTk-Part2.3. We confirm clicking OK.

BizTalk, WIF, WF Tutorial - Part 2.3a - Solution Exproler - Start

Solution explorer shows an empty project named after our Solution. Although the name is OK for the whole solution, it does not appear to be OK neither to store Orchestration nor Schemas. Let’s remove it. Right click and Remove.

BizTalk, WIF, WF Tutorial - Part 2.3a - Removing project

The next thing we have to do is to prepare our solution form the scratch.

We are going to divide our business process into the following parts:

  • Schemas – here we are going to store all XML Schemas that will be used by our process (orchestration)
  • Orchestrations – this project will reference Schemas and store an orchestration for Mail filtering business process.

There will be more projects, e.g. Maps, they are not yet needed. We are not going to use canonical schemas yet. I leave it for the next part.

Now we need to create & add to the solution two new projects: Schemas and Orchestrations.

BizTalk, WIF, WF Tutorial - Part 2.3a - Adding a new project

We select Empty BizTalk Server Project and type name Schemas.

BizTalk, WIF, WF Tutorial - Part 2.3a - Adding an empty BizTalk project

The same for Orchestrations. And Solution Explorer should look exactly as shown below.

BizTalk, WIF, WF Tutorial - Part 2.3a - Target Solution Explorer

In our simple case there is no real need to group schemas or orchestration in any folders. But when we start e.g. using WebServices and consuming its schemas and bindings we will rebuild our project structure. For now it is enough.

Create a message schema

Before we can start any business process transformation which in result will give a BizTalk orchestration we have to prepare XML Schema that describes the messages that we expect from our orchestration to support.

We right-click on Schemas project and choose Add -> New Item.

BizTalk, WIF, WF Tutorial - Part 2.3a - Adding a new schema item

In the opened window we choose Schema and name it SimpleMessage.xsd (we will get to complex messages in future).

BizTalk, WIF, WF Tutorial - Part 2.3a - Adding a new schema item window

After clicking Add an editor window is opened with default schema with default root element.

BizTalk, WIF, WF Tutorial - Part 2.3a - Default schema structure

What we should start from is changing the target namespace of our XML Schema. This in my opinion should never be left in its default state, because what does it actually mean http://Schemas.SimpleMessage? Let’s change it to fit our naming concept.

We select Schema node in the editor window, and go to the Properties window and type in Target Namespace: http://MusialTk.Tutorial.Part.2.3.SimpleMessage.

BizTalk, WIF, WF Tutorial - Part 2.3a - Changing target namespace

We have already named the new schema SimpleMessage but the root node does not reflect it yet. We should rename it to match the schema name. In order to do so, select the root node and click F2.

BizTalk, WIF, WF Tutorial - Part 2.3a - Renamed root node

Having renamed our root node we should create any of the actual fields that can handle any data input. For now, creating instance of SimpleMessage.xsd gives only the following file.

BizTalk, WIF, WF Tutorial - Part 2.3a - Instance XML file

You may wonder how this instance was created, but there is no magic behind the scenes. We simply right-click on SimpleMessage.xsd in Solution Explorer and choose Generate Instance.

BizTalk, WIF, WF Tutorial - Part 2.3a - Generating schema instance

In the Console appears a line saying where a new instance was generated.

BizTalk, WIF, WF Tutorial - Part 2.3a - Generated instance - console output

Adding fields to the schema

In order for an instance XML to carry any data we should create at least a few fields as child nodes of the SimpleMessage root node. There is nothing simpler than that. We right-click on SimpleMessage node in SimpleMessage.xsd and select Insert Schema Node -> Child Field Element.

BizTalk, WIF, WF Tutorial - Part 2.3a - Adding XSD child element

Let’s name the new field reason. But we still do not have a filed on which the routing should be based (see BPMN model of Mail filtering business process). We follow the same path and create the second field name. This should be enough for our simple process. Both elements we leave with their default data types, that is xs:string. SimpleMessage.xsd should look exactly as below.

BizTalk, WIF, WF Tutorial - Part 2.3a - Target SimpleMessage schema

 

For those not yet familiar with XSD Schema syntax, our fields were by default surrounded by <xs:sequence> and <xs:complextType>. The former means that elements in an instance file for this schema must appear in exactly the same order, that is: if the name element appears before the reason then a XML file is invalid for this schema. The latter complexType element says that our root node SimpleMessage is composed of subtypes like name and reason.

Let’s try to generate instance once again. This time the content should be more comprehensible and usable.

BizTalk, WIF, WF Tutorial - Part 2.3a - SimpleMessage XSD instance

Better, isn’t it? Let’s copy the instance file to the desktop so that we could easily play with it and drop it into IN-Folder in the future.

BizTalk, WIF, WF Tutorial - Part 2.3a - Instance file on the desktop

Creating orchestration

When we already have a message schema we can start modeling the actual business process. We go back to our favorite Solution Explorer, right click on Orchestrations project and select Add -> New Item. Then we choose BizTalk Orchestration and name it after BPMN Pool from the diagram: MailFiltering.odx.

BizTalk, WIF, WF Tutorial - Part 2.3a - Adding new Orchestration item

Quite lot naming and not only naming conventions concerning BPMN modeling are to find in BPMN Method & Style by Bruce Silver. This book is strongly recommended not only for business analysts & business process modelers, but also for more technical aware IT people. It really helps in understanding and in doing it right (BPMN modeling).

Newly created orchestration for MailFiltering should look like the one shown below.

BizTalk, WIF, WF Tutorial - Part 2.3a - Mail filtering empty orchstration

There are two main parts of this editor window:

  • Orchestration surface – here are all the orchestration shapes dropped. All of the shapes have a corresponding operation, for example if-statement.
  • Port surface – here are dropped all the ports that represent inputs & outputs of our orchestration. As I have already said, here there is no physical implementation considered. We say only which schema should messages have and whether ports as one-way or two-way.

The question is: where to start? We can make it step by step analyzing the BPMN model.

Mail filtering business process starts on the left hand side with an event invoked on a message arrival.

BizTalk, WIF, WF Tutorial - Part 2.3a - BPMN Message Event

This means nothing more than that we should start the orchestration from receiving the message. When we do so, every time a message appears on the connected Receive Port it is automatically forwarded into the orchestration. What’s more important, we can and we will specify than on the message arrival a new instance of the orchestration should be created. But step by step…

We start from dragging & dropping Send shape from Toolbox onto the orchestration surface.

BizTalk, WIF, WF Tutorial - Part 2.3a - Toolbox with Receive Shape

Like this..

BizTalk, WIF, WF Tutorial - Part 2.3a - MailFiltering orchestration only with Receive Shape

What does this exclamation mark mean? That there is no Receive Port connected with the Receive Shape. Let’s rename our shape to ReceiveSimpleMessage and drag & drop Port from Toolbox onto the Port Surface. When we do so Port Configuration Wizard is opened.

BizTalk, WIF, WF Tutorial - Part 2.3a - Port Creation Wizard - Start Page

We click Next.

BizTalk, WIF, WF Tutorial - Part 2.3a - Port creation wizard - Port Name

We name the port after the message it receives (SimpleMessage) and continue clicking Next.

BizTalk, WIF, WF Tutorial - Part 2.3a - Creating a new port type

Here we decide if we want to create a new Port Type or use an existing one. As none already exists we choose Create a new Port Type. Below we say it is a One-Way type (we use FILE Adapter which works without any problems with One-Way Receive Port – see Part 2.2).

There are three leaves of Access Restrictions:

  • Private – is not available from the outside world so no physical port can be connected,
  • Internal – available from BizTalk Server Administration Console but cannot be published as WebService or WCF-Service,
  • Public – freely available for everything.

We choose Internal and click Next.

BizTalk, WIF, WF Tutorial - Part 2.3a - Port direction

In the next step we specify the Port direction which in our case is I’ll always be receiving message on this port. We decide not to specify Port biding as we would like to keep the orchestration unaware of the physical implementation. It is enough to say that we will receive messages and we will do it one way. Orchestrations do not require any more information. We click Next.

BizTalk, WIF, WF Tutorial - Part 2.3a - Port creation wizard - Finished

Finished. Click Finish. Orchestration is automatically updated and in Port Surface appears the newly created port. But the exclamation mark stays.

BizTalk, WIF, WF Tutorial - Part 2.3a - Orchestration with the newly created receive port

Let’s switch to the Orchestration View. There are among all the folders also the port and the port type we created before. But next to the SimpleMessageOneWayPortType we notice another exclamation mark.

BizTalk, WIF, WF Tutorial - Part 2.3a - orchestration view - configuring port

Once extended, the node shows a more detailed structure of the Port Type.

BizTalk, WIF, WF Tutorial - Part 2.3a - Orchestration View - More details

Interesting? Yes. The wizzard created automatically an operation named Operation_1 that accepts an input named Request. That’s exactly how one-way ports are modelled. They allow us to post the content, but do not return any value.

What is this Operation_1 for? If we publish the Receive Port using Orchestration publishing wizzard this operation would be transformed into a SOAP method described in WSDL. This means than we try to consume our service in visual studio, generated snippet would contain a void method named Operation_1 accepting a parameter Request. The problem is that we do not know what type the Request is. And that is the reason why the error message is shown. Before we select the node Request and switch to the Properties view, let’s change names to reflect our process naming concept.

BizTalk, WIF, WF Tutorial - Part 2.3a - Orchestration View - Missing message type in Port Type

Now Properties.

BizTalk, WIF, WF Tutorial - Part 2.3a - Port Type's message properties

We see an exclamation mark next to the empty Message Type field. BizTalk expects us to provide a type for the message accepted by the method. Otherwise no content based message routing inside an orchestration would be available.

While browsing all the available data types we see, that SimpleMessage schema is nowhere to find. That is because we did not reference Schemas project in the Orchestrations. In order to do so we right-click on Orchestrations and select Add reference….

BizTalk, WIF, WF Tutorial - Part 2.3a - Adding reference to Schemas

We select Schemas and click OK. Now when we go back to properties of the Port Type we can choose Schemas -> Select from referenced assemblies.

BizTalk, WIF, WF Tutorial - Part 2.3a - Message Type from the referenced Schemas assembly

After selecting Schemas assemblies we can simply select SimpleMessage schema. We can simply click OK and move forward as our simple example should not be influenced by any changes in future. But let’s do it already the right way.

If we choose to have SimpleMessage as a type for the parameter and later on for the Receive Port and then Receive Shape, when we liked to change the parameter type in the future that would cause us a lot of pain. There is no way to change the type without disconnecting the shape from the port. There is actually no way to skip editing Port as well as Receive/Send shape. However, there is an easy way to save ourselves all that trouble. We will use Multi-part message type.

Why Multi-part messages are so special?

As we have already said binding schemas directly to Ports and Shapes can cause problems when we want to apply any changes in future. But how Multi-part messages solve this problem? As the name says, they are composed of many parts, headers and the most important body. There is always only one body pro message. What is the most interesting: we can dynamically change which part is actually the body. Which means that when any changes happen, we can simply introduce a new part, and switch isBody flag to true. How is it possible with Shapes and Ports? Simple. They are all now type aware but Multi-part type aware. This means that they do not care what the message contains as the type before and after the change matches. What difference does it make if the same Multi-Part Message has different body? No difference. We can easily swap & switch & change.

Creating a Multi-part message for SimpleMessage schema

We go back to the Properties view of the sendSimpleMessage‘s parameter. Instead of selecting Schema from referenced assemblies we expand Multi-part messages and then click Create new Multi-part Message Type.

BizTalk, WIF, WF Tutorial - Part 2.3a - Creating a Multi-part Message Type

Message type is automatically created in Orchestration View and Visual Studio switches Properties View to the newly created type.

BizTalk, WIF, WF Tutorial - Part 2.3a - Multi-part Message Type properties

We start from changing the name to SimpleMessageMultiPartType. Let’s switch to the Orchestration View.

BizTalk, WIF, WF Tutorial - Part 2.3a - Multi-part Message Type in Orchestration View

We see that there is already one MessagePart_1 created. In its Properties we can find Message Body Part set to TRUE. In Properties vie for MessagePart_1 we change the name to BodyPart and select SimpleMessage as Type (we expand the list, select Schemas and click Select from referenced Assemblies, look for Schemas assembly, select SimpleMessage and click OK).

BizTalk, WIF, WF Tutorial - Part 2.3a - Body Part Properties

Now only one exclamation mark has left.

BizTalk, WIF, WF Tutorial - Part 2.3a - MailFiltering Orchestration - one exclamation mark

There is an easy way to fix it: drag this trianglo-square from the Receive Port to the “socket” of the Receive Shape.

BizTalk, WIF, WF Tutorial - Part 2.3a - Receive Shape connected with the Port

Now we are almost prepared for receiving. We need to set Activate flag on Receive Shape on  TRUE. We have already spoken about that. It means that for every incoming message a new orchestration instance should be created.

BizTalk, WIF, WF Tutorial - Part 2.3a - Receive Shape properties

We can now click F6 and build the whole solution. Build succeeded. But in spite of the fact that we are receiving we are doing completely nothing with the message.

We go one step forward and transform BPMN conditional branch.

BizTalk, WIF, WF Tutorial - Part 2.3a - BPMN Branch

One quick look on Toolbox and there it is: Decide Shape.

BizTalk, WIF, WF Tutorial - Part 2.3a - Decide Shape in Toolbox

We drag it and drop it right after Receive Shape. After a quick rename operation it should look exactly as shown below.

BizTalk, WIF, WF Tutorial - Part 2.3a - Prchestration with Decide Shape

We have another exclamation mark to resolve. This time we select IsTom branch and go to Properties view.

BizTalk, WIF, WF Tutorial - Part 2.3a - Rule Shape properties

Conditional Expression is missing. So we set focus on the Expression field and click…

BizTalk, WIF, WF Tutorial - Part 2.3a - Empty expression window

For those of you already familiar with C#, writing conditional expression should not cause any trouble.

On the Receive Shape Properties we saw that the message that is created in the orchestration after receiving it from the BizTalk MessageBox is named Message_1. So let’s try to type it.

BizTalk, WIF, WF Tutorial - Part 2.3a - BodyPart in Expression Window

No surprise, BodyPart is available. We select it and type dot.

BizTalk, WIF, WF Tutorial - Part 2.3a - Missing name property

This time it is not so simple. There are no properties available in spite of the fact that we know that name and reason are there. We close the window clicking Cancel.

Promoted properties

The problem with not available XML elements can be resolved with use of Promoted Properties. These are those XML Schema elements that we choose to promote in order to provide, for example routing and conditions like the one above. (http://support.microsoft.com/kb/942250)

Promoting SimpleMessage name property

In order to fix the problem with missing properties and allow us to write the proper condition we go to Schemas project and open SimpleMessage.xsd. We right click on name node, select Promote and then Show promotions.

BizTalk, WIF, WF Tutorial - Part 2.3a - Quick promotion

All we need to do in order to apply IF condition in the Decide Shape is to click Add and create Distinguished property. The difference between the distinguished and promoted properties is as follows: the former is dynamically resolved every time is read and promoted property is statically filled when message arrives.

BizTalk, WIF, WF Tutorial - Part 2.3a - Dinsguished Properties

We click OK. And now we go back to the IsTom expression window.

Warning: sometimes the promoted property is available once all the projects in solution are cleaned & built.

BizTalk, WIF, WF Tutorial - Part 2.3a - Expression window with name property available

We confirm clicking OK. And after that the orchestration should look as shown below.

BizTalk, WIF, WF Tutorial - Part 2.3a - Orchestration with the proper condition

Now we have to react somehow on messages addressed to Tom and all the other. In both situations messages should be saved but in different directories.

BizTalk, WIF, WF Tutorial - Part 2.3a - BPMN - Sending to directories

We are going to use FILE adapters once again so at this point all we need to know is that One-way Send Ports are the most suitable. We start from dragging and dropping two receive shapes, one in each branch. After a simple rename to SendTomsMessage and SendOtherMessage the orchestration should look as follows.

BizTalk, WIF, WF Tutorial - Part 2.3a - Decide branch with Send Shapes

Once again we have to cope with exclamation marks next to Send Shapes. Once again they appeared due to lack of corresponding Send Ports on the Port Surface. We start by dragging and dropping TomsMessageOneWayPort. We click Next in the first step.

BizTalk, WIF, WF Tutorial - Part 2.3a - One Way Send Port - Name

In the next step we type the Name: TomsMessageOneWayPort and click Next.

BizTalk, WIF, WF Tutorial - Part 2.3a - New Send Port Type

Once again we choose to create an Internal, One-Way port. We confirm clicking Next.

BizTalk, WIF, WF Tutorial - Part 2.3a - Always sending

This time I’ll always be sending messages on this port. Then Next. And we are done. Confirm clicking Finish.

In the Port Surface should appear the following port.

BizTalk, WIF, WF Tutorial - Part 2.3a - Send Port - Default names

We apply some renaming.

BizTalk, WIF, WF Tutorial - Part 2.3a - Renamed Send Port

The question is: why can’t we simply add another operation for sending messages for other names? It’s impossible due to the static binding between orchestration ports and Send Ports in BizTalk Server Administration Console. FILE Adapter requires specific directory settings pro port so we need to specify two orchestration send ports. If we were using for example a WebService with the two methods for both cases, we could implement it using only one orchestration’s send port.

After renaming we need to specify the message type. In order to do so, we go to the Orchestration View, expand TomsMessagesPortType -> sendToTom and select message node. We switch to the Properties View and chose in the field Message type the following option: Multi-part Message Types -> Orchestrations.SimpleMessageMultiPartType. Why? We received the following message, we didn’t transform it, but we would like to store it unchanged. That is why we can use the already created multi-part message type.

BizTalk, WIF, WF Tutorial - Part 2.3a - Send Port Message Properties

Even though we have connected the Send Shape with the newly created Send Port exclamation mark stays.

BizTalk, WIF, WF Tutorial - Part 2.3a - Connected Send Port with exclamation mark

Properties for the SendTomsMessage Shape shows that BizTalk does not know the message it should send.

BizTalk, WIF, WF Tutorial - Part 2.3a - Send Tom's Message Shape properties

We simply select our already known Message_1. The only one available though. After choosing the message exclamation mark disappears. SnedTomsMessages done. We should do exactly the same with SendOtherMessages. I mean: create a new Send Port (OtherMessagesOneWayPort), create a new One-Way Port Type (OtherMessagesPortType), select existing multi-part message, connect the shape with the port and select the message to be sent.

BizTalk, WIF, WF Tutorial - Part 2.3a - Connected Send Port - no errros

We are done. We switch to Release and build the whole solution clicking F6.

BizTalk, WIF, WF Tutorial - Part 2.3a - Switch to release

As it is already a pretty long note, we will continue with configuration in BizTalk Server Administration Console in the next part (Part 2.3b)

Leave a Reply