Geeks With Blogs

News Find me on LinkedIn at
Robert Kokuti Integrating with Vision
| Home |
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 on Sunday, May 16, 2010 10:46 AM | Back to top

Comments on this post: BizTalk Envelopes explained

# re: BizTalk Envelopes explained
Requesting Gravatar...
Thanks a lot!
Your article was а blessing for me as a BizTalk beginner! I didn't understand envelopes before.
Treating the business data as a ‘black box’ and
attaching additional context information was my usecase exactly!
I created the envelope and tried to enclose the sent message within it using XMLAssembler component in the Send Port.
Everything works perfect!
Left by Sergey Makarov on Jul 22, 2010 10:45 AM

# re: BizTalk Envelopes explained
Requesting Gravatar...
Thank you Robert,

It is very well explained. I look forward to more post from you. i am interested in knowing how to approach ESB-BizTalk pub/sub scenario.

More post please

Left by Shagun Khare on Jan 28, 2011 5:09 PM

# re: BizTalk Envelopes explained
Requesting Gravatar...
Hello Robert,

I tried the practice above, however nothing showed up in destination. Could you email me the sample?

Left by Max on May 03, 2011 6:23 AM

# re: BizTalk Envelopes explained
Requesting Gravatar...
Max, the envelope's body node, the payload, must carry a document which type is known to BizTalk (defined as a schema). Otherwise, the XMLAssembler/DisAssembler will fail.
Left by Robert Kokuti on May 10, 2011 12:02 PM

# re: BizTalk Envelopes explained
Requesting Gravatar...
I get below error after specifying EnvelopDocSpecName,
Unable to read the stream produced by the pipeline.
Details: There was no XML start tag open.

sendport delivers file to folder when i remove the EnvelopDocSpecName,but i need to keep the header informations in envelop. Please suggest when could be the possible error i made ...
Left by Mahendren on Nov 16, 2012 7:46 AM

# re: BizTalk Envelopes explained
Requesting Gravatar...
Is there a schema available that shows how the body was defined as an anyType? I need to do something similar, however I'm not sure what the exact syntax should be.
Left by Nick on Aug 14, 2013 7:39 PM

# re: BizTalk Envelopes explained
Requesting Gravatar...
i did follow the same process but i get the below error at the snd pipeline any ideas?

Unable to read the stream produced by the pipeline.
Details: There was no XML start tag open.
Left by sujith on Feb 20, 2014 6:17 PM

Your comment:
 (will show your gravatar)

Copyright © Robert Kokuti | Powered by: