Archive for April, 2012

Envelope Schemas in BizTalk

Posted: April 11, 2012 in Uncategorized

Reblogged from BizTalk Envelopes explained – Robert Kokuti:

Sunday, May 16, 2010 10:46 AM

Recently I’ve been trying to get some order into an ESB-BizTalk pub/sub scenario, and decided to wrap the payload into standardized envelopes. I have used envelopes before in a ‘light weight’ fashion, and I found that they can be quite useful and powerful if used systematically. Here is what I learned.
The Theory

In my experience, Envelopes are often underutilised in a BizTalk solution, and quite often their full potential is not well understood. Here I try to simplify the theory behind the Envelopes within BizTalk.

Envelopes can be used to attach additional data to the ‘real’ data (payload). This additional data can contain all routing and processing information, and allows treating the business data as a ‘black box’, possibly compressed and/or encrypted etc. The point here is that the infrastructure does not need to know anything about the business data content, just as a post man does not need to know the letter within the envelope.
BizTalk has built-in support for envelopes through the XMLDisassembler and XMLAssembler pipeline components (these are part of the XMLReceive and XMLSend default pipelines). These components, among other things, perform the following:

XML Receive Pipeline

  1. Extracts the payload from the envelope into the Message Body
  2. Copies data from the envelope into the message context, as specified by the property schema(s) associated by the envelope schema.

Typically, once the envelope is through the XMLDisassembler, the payload is submitted into the Messagebox, and the rest of the envelope data are copied into the context of the submitted message. The XMLDisassembler uses the Property Schemas, referenced by the Envelope Schema, to determine the name of the promoted Message Context element.


XML Send Pipeline

  1. Wraps the Message Body inside the specified envelope schema
  2. Populates the envelope values from the message context, as specified by the property schema(s) associated by the envelope schema.

Notice that there are no requirements to use the receiving envelope schema when sending. The sent message can be wrapped within any suitable envelope, regardless whether the message was originally received within an envelope or not. However, by sharing Property Schemas between Envelopes, it is possible to pass values from the incoming envelope to the outgoing envelope via the Message Context.
The Practice
Creating the Envelope

Add a new Schema to the BizTalk project:
Add New Envelope

Envelopes are defined as schemas, with the <Schema> Envelope property set to Yes, and the root node’s Body XPath property pointing to the node which contains the payload.
Typically, you’d create an envelope structure similar to this:

Envelope Schema Structure

Click on the <Schema> node and set the Envelope property to Yes.

Then, click on the Envelope node, and set the Body XPath property pointing to the ‘Body’ node:

Setting Body Path

The ‘Body’ node is a Child Element, and its Data Structure Type is set to xs:anyType. This allows the Body node to carry any payload data. The XMLReceive pipeline will submit the data found in the Body node, while the XMLSend pipeline will copy the message into the Body node, before sending to the destination.
Promoting Properties

Once you defined the envelope, you may want to promote the envelope data (anything other than the Body) as Property Fields, in order to preserve their value in the message context. Anything not promoted will be lost when the XMLDisassembler extracts the payload from the Body. Typically, this means you promote everything in the Header node.
Property promotion uses associated Property Schemas. These are special BizTalk schemas which have a flat field structure. Property Schemas define the name of the promoted values in the Message Context, by combining the Property Schema’s Namespace and the individual Field names.
It is worth being systematic when it comes to naming your schemas, their namespace and type name. A coherent method will make your life easier when it comes to referencing the schemas during development, and managing subscriptions (filters) in BizTalk Administration. I developed a fairly coherent naming convention which I’ll probably share in another article.
Because the property schema must be flat, I recommend creating one for each level in the envelope header hierarchy.
Property schemas are very useful in passing data between incoming as outgoing envelopes. As I mentioned earlier, in/out envelopes do not have to be the same, but you can use the same property schema when you promote the outgoing envelope fields as you used for the incoming schema. As you can reference many property schemas for field promotion, you can pick data from a variety of sources when you define your outgoing envelope. For example, the outgoing envelope can carry some of the incoming envelope’s promoted values, plus some values from the standard BizTalk message context, like the AdapterReceiveCompleteTime property from the BizTalk message-tracking properties. The values you promote for the outgoing envelope will be automatically populated from the Message Context by the XMLAssembler pipeline component.

Using the Envelope


Enveloped messages are automatically recognized by the XMLReceive pipeline, or any other custom pipeline which includes the XMLDisassembler component. The Body Path node will become the Message Body, while the rest of the envelope values will be added to the Message context, as defined by the Property Shemas referenced by the Envelope Schema.


The Send Port’s filter expression can use the promoted properties from the incoming envelope.

If you want to enclose the sent message within an envelope, the Send Port XMLAssembler component must be configured with the fully qualified envelope name:

Send Pipeline Envelope

One way of obtaining the fully qualified envelope name is copy it off from the envelope schema property page:

The full envelope schema name is constructed as <Name>, <Assembly>

The outgoing envelope is populated by the XMLAssembler pipeline component. The Message Body is copied to the specified envelope’s Body Path node, while the rest of the envelope fields are populated from the Message Context, according to the Property Schemas associated with the Envelope Schema.

That’s all for now, happy enveloping!

Posted: April 6, 2012 in Uncategorized

I am currently working on two different Biztalk Solutions which need to perform multiple dynamic manipulations preferably BEFORE anything is stored to the Message Box, but I wasn’t sure about the execution order of pipeline components vs. Inbound/Outbound Maps on ports. Fortunately, I have found that answer from yet another one of Thiago Almeida’s excellent post’s.

[INACTIVE BLOG] Connected Thoughts - Thiago Almeida


For future reference to all those that want to remember in what order maps and pipelines get executed on receive and send ports:

One-way Receive Port:

End system –> Receive Adapter –> Receive Pipeline –> Inbound Map –> Message Box

Request Response Receive Port:

End system –> Adapter –> Receive Pipeline –> Inbound Map -> Message Box-> Outbound Map –> Send Pipeline –> Adapter –> End System

One-way Send Port (static and dynamic):

Message Box –> Outbound Map –> Send Pipeline –> Send Adapter –> End System

Request Response Send Port (static and dynamic):

Message Box-> Outbound Map –> Send Pipeline –> Adapter -> End system –> Adapter –> Receive Pipeline –> Inbound Map -> Message Box


See the pattern? Pipelines always get executed right before or right after the end system adapter. And maps are always executed right before or right after the…

View original post 3 more words

Sandro Pereira posted the 6th of a series titled, ‘BizTalk Server: Basics principles of Maps’ which is probably the best explanation I have seen since I started working with Biztalk Server.

BizTalk Server: Basics principles of Maps – Testing and Validation of maps (at design time) (Part 6).

Here is a great explanation of how to use polling with the WCF-SQL adapter.

Richard Seroter's Architecture Musings

A few years back now (sheesh, that long already??) I wrote a post about debatching messages from the classic BizTalk SQL adapter.  Since that time, we’ve seen the release of the new and improved WCF-based SQL adapter.  You can read about the new adapter in a sample chapter of my book posted on the Packt Publishing website.  A blog reader recently asked me if I had ever demonstrated debatching via this new adapter, and to my surprise, I didn’t found anyone else documenting how to do this.  So, I guess I will.

First off, I created a database table to hold “Donation” records.  It holds donations given to a company, and I want those donations sent to downstream systems.  Because I may get more than one donation during a WCF-SQL adapter polling interval, I need to split the collection of retrieved records into individual records.

After creating a new…

View original post 571 more words