How and in what cases Property demotion works in BizTalk

  • Article

Introduction

All of us are well aware of Property Promotion, but property demotion is less known topic.

MSDN defines property demotion at http://msdn.microsoft.com/en-us/library/aa547894.aspx as below:

“You can use property demotion to copy a property value from the message context into the message content or to its header or trailer”

Property Demotion happens in send pipelines (other than passthru transmit) assembler stage. Property demotion only happens for the applicable properties in the message context. I will explain them later what they are.

So when a BizTalk send port receives message from message box, it gets message as IBaseMessage with message content(message parts) + message context.

If it is a send pipeline other than pass thru, then it will receive message as IBaseMessage with message content(message parts) + message context. And few applicable properties are demoted in assembler and after processing all stages this IBaseMessage is sent to send adapter, and the adapter leaves the message context to garbage collection and sends message content(message parts) to destination.

If it is a pass thru transmit pipeline, it still receives message as IBaseMessage with message content(message parts) + message context and since there are no components to process, this IBaseMessage is sent to send adapter, and the adapter leaves the message context to garbage collection and sends message content(message parts) to destination.

Property Demotion Example Cases

We use property demotion in cases for example

You receive an envelop message with some fields in header. You want to debatch it and for every out going message you want to send it with a custom envelop which will have some of the field values extracted from header of the incoming envelop file.

In this case:

  1. We promote the required fields in Header of incoming envelope.
  2. Promote the required fields in header of the outgoing message in to the same property schema fields created in step 1.

You may get confused for step 2, I will elaborate it later.

That’s it, when you drop the incoming file, properties of the incoming envelope header fields will be promoted and while sending out the debatched message, those properties are demoted from the context into the header section of every outgoing envelop message.

Similarly we use property demotion for another case, where we want to use some field values from the header part of the incoming file to the body part fields of every out going message (in first example, we demoted into header section fields of outgoing message, but in this case we want to demote in to body part fields).

Walk Through steps

As I said I will dig in to show how property demotion happens for applicable fields with 2nd example case.

we shall create 2 xml schemas:

  1. EmployeeInfo–> that contains employee information
  2. Employees–>this is an envelop schema for the EmployeeInfo used for debatching

Create EmployeeInfo schema like below.

http://programmingatease.files.wordpress.com/2014/03/employeeinfo.png?w=219&h=184

Create Envelop Schema Employees like below.

http://programmingatease.files.wordpress.com/2014/03/employees.png?w=224&h=159

Now import Employee schema into this envelop schema.
 
Now set the data structure type of the record EmployeeInfo to ns0:EmployeeInfo like below.

http://programmingatease.files.wordpress.com/2014/03/datastructuretypeofemployee.png?w=300&h=89

Now the employees envelop schema should look like below.

http://programmingatease.files.wordpress.com/2014/03/employeesenvelopwithimportedschema.png?w=250&h=254

If you notice I have created the names of fields in header and in body parts with similar names “companyName” and “city” as it is. I set it so just for simplicity, not mandatory, you can set any name.
 
Now our agenda is to populate data from header part to some fields in individual outgoing message using property demotion. For this purpose whatever the fields you want to populate values in outgoing message, we have to keep those fields empty in the incoming file. Then the outgoing file should come with populated values in them using property demotion.
 
In this case, I want to populate CompanyName, City from Header part and File path location from the system promoted property InboundTransportLocation.
 
So our input file contains empty nodes like below.

http://programmingatease.files.wordpress.com/2014/03/employeesinputfilewithemptynodes.png?

So when this envelope message comes into BizTalk, we have to debatch it with following conditions:

  1. “CompanyName” and “City” fields values from the header part should be copied to every out going individual message in to the fields of “CompanyName” and “City” respectively.
  2. File received location path(the path where the input file was dropped) should be set to FileReceivedLocation element on every outgoing message.

Now that you have imported the schema into envelope schema , select the Root node in envelop schema and set the BodyXpath property to the node “Body”.
 
Now we will dive into property promotion and demotion. We need to promote the fields now. Because they should be available in the context so as to demote them and write them to outgoing message in send port.
 
In Employees envelop schema, promote the two properties “CompanyName” and “City”. You may use quick promoted option to create the property schema auto created.
 
Now the following step is important, we will promote elements from EmployeeInfo schema into already created fields in property schema.
 
So open EmployeeInfo schema, right click on CompanyName element –> Promote –> and select show promotions options. In the opened window, click on PropertyFields tab.

Now click on folder open icon and import/refer following two things:

  1. Refer already created property schema.

  2. Refer system global property schema “BTS.bts_system_properties” (you have to select from references section in the window) and click OK.

    http://programmingatease.files.wordpress.com/2014/03/biztalksystempropertyschema.png?w=628&h=401

  3. Now from the window add the fields “company”, “city” and “FileReceivedLocation” to promote them. Now here make sure you set the right node for the Node Path section. By default it selects first element, change as per need.            

  4. For FileReceivedLocation property, set inboutTransportLocation property.
    At the end it should look like below.

    http://programmingatease.files.wordpress.com/2014/03/propertydemotiondemo-promotionwizard.png?w=627&h=384

Now create a receive pipeline to process this XML envelop, deploy the solution. Set up ports, set pipelines, set filters etc.  

NOTE: you should not use passthru pipeline at send port, otherwise it will not demote properties into outgoing messages.  

Create sample envelop instance with few messages inside the envelop. (make sure you set the required fields empty as explained earlier)

Drop the message in receive location, once processed you should see output files with the fields “CompanyName”, “City” and “FileReceivedLocation” fields having values.

 

For example I am dropped the following envelope containing 3 messages inside,

http://programmingatease.files.wordpress.com/2014/03/propertydemotiondemo-sampleinputfile.png?w=735&h=594

Notice that I have set the required few fields empty,(it is required).
 
Once I dropped them, the envelop got debatched and produced 3 output files.

http://programmingatease.files.wordpress.com/2014/03/propertydemotiondemo-outputfiles.png?w=628&h=128

And the output message contains the field values which are demoted from the context.

http://programmingatease.files.wordpress.com/2014/03/propertydemotiondemo-outputsample.png?w=628&h=143

Keep following things in mind if you follow the above example.

  1. You must and should keep the required nodes with empty tags in the input file to work this scenario/example.
  2. If you do not keep empty nodes (I,e if you keep some values) then you will not get the values from header/system properties whatever.. .. you will get the same value that you set in the input file.
  3. If you do not keep the empty node itself in the input file, the output node itself is not created.
  4. for cases like in example 1, no need to keep elements with empty tags in incoming file as we are demoting into outgoing message Header section.

In what cases Property Demotion happens?

I noticed that if multiple schemas share the same fields in property schema, property demotion attempt happens.

In our case:

  1. We have promoted 2 elements in envelop schema from header “CompanyName” and “City” .  so 2 fields are created in newly auto created property schema.
  2. We have promoted 2 elements from document schema “CompanyName” and “City” into the same fields in property schema which are created in step 1.
  3. We have promoted FileReceivedLocation field in to the biztalk global property schema “BTS.bts_system_properties”.

So, for one field in property schemas(be it custom or BizTalk Global property schema) if there is a match from multiple schemas, then in such cases property demotion attempt happens.

There may be other cases too depending on requirement.  Your ideas, inputs are welcome!

See Also

Another important place to find an extensive amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.