Getting Started with BizTalk Services: BizTalk Services offers great possibilities for bringing enterprises together in the cloud, and this book is the perfect introduction to it all. Packed with real-world scenarios, you will soon be designing your own tailor-made integration solutions.

BizTalk Services' job is to let you connect this to that. What this and that actually are may not always be clear, well defined, or standardized into some internationally recognized protocol. A mapping capability is therefore crucial—a way to convert this into that. On many occasions, mapping requirements may be complex; the need to fundamentally change the shape or structure of a message, for example, or the need to replace data values from the source message with something that makes sense to the receiver. We can break this down into two classes of problems: one that needs to address the structure of a message, transformation; and one that needs to address its content, transcoding or translating it. The two types of mapping, transformation and translation, are both possible with BizTalk Services, as we'll see in this chapter.

So far, we're being deliberately vague, and with good reason. Often, mapping requirements are not well known and change as more is discovered about the nuances of the messaging formats involved and their variations. It often surprises people familiar with dealing with XML-based messages that describing their validity simply in terms of schema by using XML Schema Definition (http://www.w3.org/XML/Schema) can turn out to be more complicated than it first appears. This is unfortunately sometimes to do with the different productions or instances of XML messages that can be created or produced by a single schema, often unintentionally. XSD is sometimes not precise enough, and integration is therefore often messy, requiring good tools to make things fit, while the purity of standards and specifications doesn't go far enough to avoid ambiguity in implementation. This is a theme we'll come back to many times during this book: to be successful, any integration technology must be flexible...

Take a look at the following screenshot. This shows the new graphical mapping designer that is accessible from Visual Studio 2012. For those familiar with BizTalk Server, don't be fooled. While it may have a similar look and feel to the BizTalk Server mapper, this tool has significant differences; the overriding design aesthetic was to make common mapping tasks as simple as possible, and as such, the mapper has undergone a significant overhaul.

Graphical mapping designer

However, we're getting ahead of ourselves. In order to map one message format or structure to another, to translate its contents for example, we first need to understand the messages themselves. Fundamental to this is schema.

BizTalk Services differentiates between two types of messages: XML and non-XML. All XML message formats are expressed using XSD, and all non-XML message formats are expressed using XSD. So, XSD is important! The purpose of this book is not to provide a primer in XSD; we'll refer to other references if you need some background on the technologies we mention. Instead, we'll provide just enough to show how BizTalk Services uses such technologies so that the less familiar can still understand what is going on.

Now, you're probably wondering how any message formats you can think up can be defined in XSD. Let's look at an example.

Let's expand on the example we looked at in Chapter 1, Hello BizTalk Services. If you recall, this example received a file via SFTP and routed it to a Service Bus endpoint. Now we'll add a map to the solution. The map will transform the incoming message into a different format expected by the recipient. However, as noted previously, if we're to turn one message format into another, we need to define the schema of the target message first in order for us to be able to map to it.

To do this, right-click on the project, navigate to Add | New Item, select Schema from the list of items, and provide the name OrderUS.xsd. Click on Add to create the schema and add it to the solution.

The schema designer will now be open. As you did in Chapter 1, Hello BizTalk Services, add nodes to the schema to build it up, as shown in the following screenshot:

Changing the Order schema

Now, right-click on the project and navigate to Add | New Item. Select Map from the list of items and provide the name...

We can proceed like this for as many nodes as we like, connecting them individually or in groups. However, we often need to do more than just map one node's value to another. For this, we can turn to mapping operations. For those acquainted with BizTalk Server, you will be familiar with functoids; the concept is similar in BizTalk Services. However, despite the similarities, there are many differences in how they are realized. One of the primary goals of the product group is to simplify common tasks, such as looping, which were often difficult or time consuming to achieve previously. This is where we will now focus our attention.

BizTalk Services provides a total of 37 mapping operations that are functionally grouped into categories in the toolbox. There isn't room here to cover every mapping operation, so we'll focus on some of the most useful. For a complete reference, check the MSDN documentation at http://msdn.microsoft.com/en-us/library/windowsazure/hh689870.aspx....

Phew! This may seem quite complex, but it's really quite simple once you break it down. The next step is to test the map and see if it looks like it's producing the right results. Testing is built right into Visual Studio, so there's no need to compile and deploy the solution to Windows Azure in order to see if it works. This is important as creating anything other than trivial maps is a very iterative process. It's made easier by building up the functionality in the map gradually and examining the test results along the way. This way, any mistakes are much more obvious and easily corrected.

To test a map, we need some input. This is most easily generated in Visual Studio itself. Right-click on the OrderFF.xsd schema in the Solution Explorer window and select Generate Instance. Open the file that's created and edit the values to match the one shown in the following code (don't forget, you can just download the source for this example from the website):

<ns0:Order xmlns:ns0="http...

A map is no good on its own though. We need to be able to use it in an integration solution. It should hopefully come as no surprise that the way we do this is by configuring a bridge. The next screenshot shows part of the bridge configuration. This configuration represents the pipeline of processing that can be configured. There are multiple stages to this pipeline, as mentioned in Chapter 1, Hello BizTalk Services. In the middle of the pipeline, there is a Transform stage; it is here that we can specify a map to execute.

Configuring a bridge with a map

Double-click on the MessageFlowItinerary.bcs file in the Solution Explorer window to open it. In the designer, open the OrderProcessing bridge configuration by double-clicking on it. Click on the Transform stage and look at the Properties window. Here, we can choose a map by clicking on the ellipsis (…) next to the Maps property to open up the configured maps. This will show us all the maps the solution contains.

We can...

The solution is now ready. Build and deploy as before, and once deployed, point your browser to https://<yourdeployment>/default/OrderProcessingBridge and you should see a 401 HTTP error code stating that a manage claim is required for this operation.

Now you will use two tools provided as a part of the BizTalk Services SDK. These are MessageSender and MessagerReceiver which you can download from the following links. These tools allow you to send messages to and receive messages from the bridge you created:

Unzip both solutions and open the MessageReceiver sample in Visual Studio 2012 and build it. Run it from the command prompt by typing the following and pressing the Enter key.

<path>MessageReceiver.exe ServiceBusNS owner <issuerkey> USAddressRelay OneWayRelay

In the preceding command, <path...

We've covered a lot of ground so far, but there is much more to mapping in BizTalk Services besides the other 27 operations we've not used here. There are two other groups of operations that deserve some discussion.

The first of these is the Get Context Property mapping operation. This provides an often-asked-for feature in BizTalk Server—the ability to retrieve properties from the message context and include them in a map. The way this works is by configuring it, specifying the property name to retrieve it, and then connecting it to a target node; no input nodes are required. We haven't covered context properties in detail yet, but for now, remember that they are a set of name/value pairs that hold contextual information about the current message flow; for example, the transport details (for example, a filename) of the message received, or even properties of the message itself that have been extracted. If you're wondering how you can test this from within Visual Studio as...

One very important point a developer must consider is how to deal with failures that occur. In integration solutions, failure is particularly important as it can be hard to isolate and diagnose. On a map, it is possible to configure what action to take should a particular operation fail, usually due to bad data provided to it. The Settings button at the top of the designer displays the dialog, as shown in the following screenshot, when clicked.

Here, each operation (or group of operations in some cases) can be set to either Fail Map on an error occurrence or continue and output a null value. This is very useful; we'll look at error handling in much more detail in a later chapter.

Setting runtime properties

In this chapter, we have looked at the mapping features of BizTalk Services. You've seen how to create maps, use many of the powerful operations provided, and test them. While we haven't been able to cover every operation, many are self-explanatory and easy to understand; after all, the whole point of the mapper is to make the job of format and content conversion easier. We urge you to experiment on your own and see what you can come up with.

In the next chapter, we'll look at the different types of bridges BizTalk Services provides, starting with EDI.