I think most BizTalk users have some idea about what Property Promotion is.  I would say Property Promotion is the process of taking message or system data and putting it into the message context.  The tricky part is when and how properties get promoted.

The items that are promoted using a property schema attached to your schema are promoted in the pipelines.  When and how the system properties are promoted is somewhat of a mystery.  I think some items are promoted in the adapters (like the specific file, HTTP, and FTP properties) while others seem to be promoted as the messages enters or leaves the Orchestration (like Sending Orchestration Type).  

Some properties are only available inside the Receive Pipeline and Orchestration (like Received Port Name and Received File Name).  In the sample below I manually copy them into the message inside the Orchestration.

It is possible to overwrite read only properties inside the pipeline (like MessageType).  This is dangerous but I am sure could have some benefits.  The MessageType property is read only inside the Orchestration but if it is promoted inside the Receive Pipeline the promoted value is used rather then the true message type.

It appears that system properties that are manually promoted in the Receive Pipeline are carried throughout the whole message flow and the system does not change them.  I can set Message ID to 12345 on the Receive Port and that value comes back out on the Send Port.  But, this message ID does not seems to actually be used internally. 

MessageType on the other hand is used by the system if promoted in the Receive Pipeline.  If I change this property, it shows up in HAT with the value I set for it.  I have found one exception to this.  It is the MessageType property when working with untyped messages.  That property is cleared when the message is sent out of the Orchestration.

Property Demotion.  This is something a little less known to BizTalk users.  This is the process of taking message context data and putting it into the message.  This is done in the Send Pipeline.  It is sometimes hard to determine what values are actually in the context and only values in the message context can be demoted. 

CRITICAL: If you use a pass through pipeline your properties are not demoted.  They are only demoted using the XML Assembler component.

Ok, so how do you go about Demoting values into your message?  First, you have to add the Property Schema to your schema that contains the values you want to demote.  If you want BTS System properties follow the steps below.

How to add the BizTalk System Properties Schema to your Schema:

1. Go to the Promote Properties Dialog Box

2. Go to Property Fields Tab

3. Go to the BizTalk Type Picker by clicking on the folder icon

4. Expand Microsoft.BizTalk.GlobalPropertySchema

5. Select BTS.bts_system_properties

Then, follow the same steps just like you are promoting the properties by selecting the elements you want to promote and select the corresponding element in the Property Schema.  It is that simple.

CRITICAL: If you have the same schema on the inbound and outbound you may inadvertently promote or demote values.

I have put together a sample working with both Typed messages and Untyped messages.  I have included several start messages that set various values.  You can check out the schema to see how I accessed the propertied for Promotion and Demotion.

DOWNLOAD: Promotion and Demotion Sample

Take Away: Property Promotion and Demotion is an important part of BizTalk allowing for message context data to be demoted into a message that is sent out of the system.