Property Promotion and Property Schemas
In Chapter 2 we briefly demonstrated the use of distinguished fields as a mechanism for promoting properties into the message context. Property promotion is used in a number of places throughout BizTalk, such as custom receive components, message routing, and orchestration. The messaging engine doesn't worry about the internal values of message fields unless you tell it. Messages are merely a chunk of data to be passed along. Property promotion identifies what should be specifically examined for use by the engine. There are two ways to do this. Distinguished fields are the easiest because they do not require a separate schema for promoted properties. Unfortunately, fields promoted through distinguished fields cannot be used for routing. Promotion using property schemas requires more work, but the properties identified therein can be used for routing.
Property schemas are a good deal simpler than message schemas. There is only one level of structure. The Schema node may only contain a series of field elements. They are also shorter. Typically, you specify only one or two fields. Property schemas record only those fields that are being promoted, so you will typically see only a small number of nodes in a property schema.
The easiest way to create a new property schema is to use the Quick Promotion menu item on the context menu inside a message schema. Right-click a node and select this, and the Editor will prompt you to see if you want a property schema. Otherwise, to explicitly create a property schema ahead of time, select the Property Schema template from the Add New Item dialog box. Let's do this, creating a new schema named ContactProperties.xsd. We're going to specify a property for the derived version of the contacts message schema. When the new schema appears, note that the Schema node's Schema Type property is set to Property. If you forgot and selected the basic Schema template, you could recover by setting this property manually.
Next, rename the root node ContactID. We plan to promote a unique identifier for routing purposes. Leave the data type as xs:string. Save the property schema and open DerivedXMLSchema.xsd.
Select the Schema node and scroll down until you find the Promote Properties property for that node. Click the ellipsis button to open the Promote Properties dialog box. This is the same one you saw in Chapter 2. This time, however, we want to click the Property Fields tab. The Property Schemas List is initially empty. Click the Open Folder button, then browse to and select ContactProperties from the Schemas folder. This schema will be prefaced with the name of your BizTalk project. After it is selected, it appears in the Property Schemas List.
Now turn your attention to the tree view to the left. Expand the tree until the SSN field is visible and selected. Click Add, and the field appears on the right in the Property-Fields dictionary. This is a list of all fields in the message schema that have been associated with a field in the property schema associated with the current message schema. Because our property schema has but the one field, ContactID, it is the default for the Property column entry for the newly promoted property. You can inspect the Node path column and see an XPath expression pointing to SSN. Click OK to close the dialog box, and you'll see some annotations added to the message schema to record the association. The SSN field node's graphic changes to add a gold and blue ribbon to indicate the promoted status.
The effect has been to associate the SSN field in the message schema with the ContactID field in the property schema. Any component or pipeline that requires the property in the message context will be configured with the name of the property schema. The value will be pushed into the message context as the message arrives. Anything that needs the information, such as an orchestration, can inspect it there.