Property Promotion inside Orchestration

|  Posted: January 8, 2007  |  Categories: BizTalk Server

Promoting properties inside BizTalk is quite common task, after all back bone of BizTalk’s underlying routing infrastructure Publish-Subscribe is based on property promotion. There are tons of articles published in the web explaining this concep

Properties get promoted within BizTalk at different places, Example: some of the properties gets promoted by Adapters, Pipelines Components, Messaging Engine etc,etc. In custom pipeline components ,developers can use either IBaseMessageContext.Write to write context properties or IBaseMessageContext.Promote to promote context properties. The basic difference between writing and promoting (aka distinguished and promoted) properties are, properties that are written cannot be used for message routing, whereas properties that are promoted can be used for message routing. (There are quite few other important differences, but they are not relevant for this article).

You can download the entire article as a PDF document.
Property Promotion inside Orchestration.

Orchestration

The syntax for promoting properties within Orchestration is

Message(PromotedPropertyName) = value;

Example

MSG_OUT_PERSON(HTTP.ContentType) = “text/xml”;

this is the only direct option available within an orchestration to promote a property. Properties promoted by this method are written rather than promoted. That means it can’t be used for message routing (filter expressions in Send Port, Orchestration etc).

The sample code contains an orchestration named “PromoteProperty.odx” as shown in below figure, it just receives a message, does property promotion inside the message assignment stage and send the message out.

PromoteProperty.odx

The following two lines are present inside the “Message Assignment” shape:

MSG_OUT_PERSON = MSG_IN_PERSON;
MSG_OUT_PERSON(PropertyPromotionInsideOrchestration.PropertySchema.ID) = “SK007”

If you look at the outgoing message context, it will look like as shown in figure below, and you can see clearly the property is “NOT PROMOTED

outgoing message context

You can download the entire article as a PDF document.
Property Promotion inside Orchestration.

So, how can you promote property within Orchestration for routing

Orchestration got the concept of Correlation, basically which routes the response messages to the correct running orchestration instance that initiated the request message. Within Orchestration we use Correlation Set and Correlation type to archive this type of instance routing.

Correlation type is nothing but a set of Properties, Example in our case it’s “ID” (you can have multiple properties together to form a single correlation type, Example EmployeeId, EmployeeCompany).

Correlation Set is based on Correlation type and its a set of properties with specific values. When we “Initialize a Correlation set” within orchestration, the orchestration instance automatically promotes those properties in Correlation set into the message context.

We can use this mechanism to promote propeties (rather than just writing properties), there is no need to do a follow up of the Correlations sets we initialized, and it NOT going to create unnecessary subscriptions. (In simple terms you create correlation sets, not for correlation but for property promotion.)

The sample code contains an Orchestration called “PromotePropertyUsingDummyCorrelationSet.odx” which is exact replica of our first Orchestration “PromoteProperty.odx”, with one addition. I added a Correlation Type, Correlation Set and Initialized the Correlation set in the Send shape as shown in below figures.

Correlation set in the Send shape Correlation set in the Send shape

Now, if you look at the outgoing message context , it will look like as shown in figure below. Now you can see ID property is PROMOTED. The attached sample clearly explains this concept. Read the Download section for details.

ID property

David Hurtado highlighted this trick on his blog. I expanded his trick with proper sample and more explanation, so that it will be helpful to some one in the future. Or atleast to me if in case I can’t remember.

Download

The download contains the complete source code, sample messages, File drop folders and binding file. Follow the steps to setup the sample.

1. Extract “PropertyPromotionInsideOrchestration” solution to “C:BTSSamples” folder

2. Open it in Visual Studio, Build/Deploy it, it will create a Biztalk Application called “PropertyPromotionInsideOrchestration”. Rectify the errors if something pops up.

3. Open Biztalk 2006 Administration console, right-click on the application “PropertyPromotionInsideOrchestration” and import the binding file “binding.xml”. (Start the application).

Execution

1. Drop the message “NoPromotion.xml” into “FileDropIn” folder, you’ll see the output only in “FileDropOut” folder.

2. Drop the message “PromotionWillHappen.xml” into “FileDropIn” folder you’ll see the output in both “FileDropOut” and “FileDropOut.ByID” folder. (Because message is routed via the second send port to this folder by Content based routing.)

You can download the entire article as a PDF document.
Property Promotion inside Orchestration.
Author: Saravana Kumar

Saravana Kumar is the Founder and CTO of BizTalk360, an enterprise software that acts as an all-in-one solution for better administration, operation, support and monitoring of Microsoft BizTalk Server environments.

  • Simon Young

    Hi Saravanna, useful info as always – yes this is indeed a ‘Black-Belt’ tip used by many experienced BizTalk Dude’s (and Dudette’s).

    The only thing I would ask is that they use the Comment property to indicate that Correlation is being used for property promotion and not correlation…so much kinder to the dude/dudette that follows when they are trying to work out what the hell is flowing where and when routing/correlation is going on rather than just property promotion!! 😉

  • Bhavani singh sikarwar

    Hi Saravanna,

    just wanted know that in Canonical Schema Modal with Map at receive port how promoted properties propagate to Canonical schema message from Original message

One Platform Operations, Monitoring and Analytics Software
BizTalk360

microsoft biztalk

Learn more

Over 500 customers across 30+ countries depend on BizTalk360

ServiceBus360

Azure service bus

Learn more

Start managing your Azure Service Bus namespaces in minutes

One Platform - Operations, Monitoring and Analytics Software
BizTalk360

microsoft biztalk

Learn more

Over 500 customers across 30+ countries depend on BizTalk360

One Platform - Operations, Monitoring and Analytics Software
ServiceBus360

Azure service bus

Learn more

Start managing your Azure Service Bus namespaces in minutes

Back to Top