How to promote properties from the body of the messages

Most BizTalk Server developers have some idea about what Property Promotion is.  In a simple way, we can say that Property Promotion is the process of taking message or system data and putting it into the message context.  The tricky part is to know when and how properties get promoted.

Previously in this blog, I explained How to promote the BizTalk Server Receive Location Name property where we created:

• A custom Property Schema
• A custom Receive Pipeline
• A custom Pipeline Component

This is required to read, in the runtime,  the Receive Location’s name that is being used and to promote it to the context of the message.  

Recently, I also wrote a whitepaper about BizTalk Message Context Properties. However, there were two missing topics that I didn’t yet address on this subject. One of them will be addressed in this blog today: How can we Promote data from the message payload to the context of the message itself, where we can do content-based routing.

There are two crucial things you need to know:

• The properties are always promoted using a property schema.
  • It can be using the out-of-the-box property schemas or custom properties schemas that we can create on your BizTalk Server Visual Studio solutions.
• The promotions typically happen inside the pipelines. Nevertheless, they can happen in the adapter layer.  
  • If you use pass-through pipelines, your properties will not be promoted.

For the data payload, BizTalk Server provides two types of property promotions: Distinguished Fields and Property Fields. You can promote a property as a Property Field in much the same way as promoting a property as a Distinguished Field. However, in a simplified manner, distinguished fields can only be used within an orchestration, whereas Property Fields fields can be accessed through all phases of the BizTalk message processing, either in orchestrations or from custom code, routing, and pipelines. A Property Fields requires the existence of a Property Schema.

You might choose Property Field promotion over Distinguished Field promotion for the following reasons:

• The values you want to promote are shorter than the 255 character limitation that applies to Property Fields.

• You need the values that you promote to be accessible outsides of orchestrations, such as within pipelines or ports.

This topic provides step-by-step instructions for promoting properties as Property Fields.

How to create Property Schemas

If we want to promote fields as property fields, we must define a property schema first. This property schema specifies an unstructured collection of fields into which you can promote fields from within an instance message defined by a schema associated with your property schema.

To do that, we need to:

• In Solution Explorer, right-click a BizTalk project, point to Add and click New Item…
• In the Add New Item dialog box, in the Templates section, select the BizTalk Project Items and then click Property Schema.
  • In the Name box, type a name for the schema, and then click Add.

• The new property schema opens, and it already contains a Field Element node named Property1.
  • We can safely delete that Property1 element

• Add two elements called Nationality and Sex by right-clicking on the Schema node, Insert Schema Node > Child Field Element.

• Save the changes and close the file.
• We could manually add all the fields we want but let’s do it directly from the existing Schemas that we want to promote the fields.

How to promote message data as a Property Field?

If you don’t have a Property Schema as we created above in your solution, the first time we try to promote an element or attribute, it will automatically create that Property Schema for you in your solution.

To promote elements or attributes of the message, you need to:

• In Solution Explorer, open the schema for which you want to promote one or more properties, and then select the (first) Field Element or Field Attribute that you want to promote as a Property Field.
  • In our example, we will be using the Person.xsd schema, and we want to promote the Nationality and Sex elements
• For that, select the Nationality element and right-click the selected node, click Promote, and then click Show Promotions.

• The Promote Properties dialog box opens with the selected node showing as selected in the schema tree on the left side of the dialog box.
• In the Promote Properties dialog box, select the Property Fields tab.
• In the Property Schemas List section, click the Folder icon. The BizTalk Type Picker dialog box appears.
• In the BizTalk Type Picker dialog box, navigate to the appropriate property schema (that you may have created in step 1), select that schema, and then click OK.

• Now from Promote Properties dialog box:
  • Select the Nationality element and click Add>>.
  • Do the same for the Sex element.

• This will automatically set the name correlation correctly for you but make sure to double-check.
• Click OK and save the file.

Now we just need to deploy and create a receive port/location that uses the XMLReceive pipeline.

And that’s it! Now if you go to the tracking of the messages, you will see these two properties promoted to the context:

I mentioned above that you don’t actually need to create the property schema manually. In reality, if you use the Quick Promotion functionality, this will automatically create a Property Schema called PropertySchema.xsd and will also create the properties inside the schema if they already don’t exist. To do that:

• In Solution Explorer, open the schema for which you want to promote the properties, and then select the (first) Field Element or Field Attribute, that you want to promote as a Property Field.
• Right-click on the Field Element or Field Attribute and then click Promote, and then click Quick Promotion.

Simple as that!

You can download the full sample from GitHub here:

• How to promoted properties from the body of the messages

Happy BizTalk coding!