BizTalk Messages

I a previous post I described a way to deal with untyped messages in the Business Rule Engine. This allows for flexibility in scenarios where you want to use a single set of rules (lets call it an “untyped policy”) on multiple types of messages.

Untyped policies work great when tested directly in the Business Rules Composer interface or when executed from .Net code. Unfortunately I stumbled across a nice issue when I wanted to call the rules from an orchestration using the call rules shape.

In my first design of the orchestration I received a message of type System.Xml.XmlDocument. After that I used a call rules shape to execute the policy. Because this is an untyped policy it will only accept a message of System.Xml.XmlDocument as input.

Easy! Well, not exactly. While testing this orchestration I did not encounter an exception but found out my rule also did not fire. I enabled rule tracking and saw that my message was not asserted as a fact into the BRE. The tracked information was ‘fact not recognized’.

I tried some things to fix this without success. I ended up viewing the generated C# code for the orchestration and noticed a difference in the code generated for the call rules shape when using untyped and typed policies. For typed policies a new instance of Microsoft.RuleEngine.TypedXmlDocument is created  as a fact wrapper around the orchestration message. This TypedXmlDocument is then passed on to the BRE. For untyped policies this is different. There is no TypedXmlDocument created and the XmlDocument message is passed directly on to the BRE.

So in pseudo C# code, for a typed policy:

typedXDoc = new Microsoft.RuleEngine.TypedXmlDocument("MessageType”, (System.Xml.XmlDocument)orchestrationMessage);
policy.Execute(typedXDoc);

for an untyped policy the code looks like this:

policy.Execute((System.Xml.XmlDocument)orchestrationMessage);

The obvious difference between the two is that the first uses a ‘TypedXmlDocument’ instance to wrap the message. I expected the XLANG code generator to do the same for the untyped version but that is not the case. So what does this mean? Does this mean untyped policies are not supported? Or at least not in orchestrations? Is the only option to use code in an expression shape or helper class to execute untyped policies from within an orchestration?

Because I was completely stuck here I decided to ask BRE (and BizTalk) guru Charles Young for help. 

It turned out that I had to use the special ‘Any’ schema to solve this. As Charles explained to me there are two ways of working with untyped messages in BizTalk. One is the famous XmlDocument approach, the other one is the (undocumented) ‘Any’ schema.

One of the differences between the XmlDocument and ‘Any’ schema is that the latter is treated as a schema type by BizTalk. This means the XLANG code generator will wrap it inside a TypedXmlDocument for a rules call. This exactly like the way it works for a typed policy.

The only two things I had to do was change were the message type from ‘XmlDocument’ to ‘Any’ and accordingly the policy.

This is a picture of the revised orchestration.

The changes needed in the policy are described in a rewritten version of the original post. You can find it here.

A demo solution around this can be downloaded from here. It contains two orchestrations. One which uses the XMLDocument approach without the rules getting fired. The other using the Any approch with the rules getting fired. Remember to change to paths in the binding file before deploying.

Full credits for this solution go to Charles Young. Charles thanks for helping me out.

This blogpost has been superseded by a new version. See: http://biztalkmessages.vansplunteren.net/2010/03/04/untyped-messages-and-business-rules-engine-part-2/

The other day one of my BizTalk buddies asked me if I knew a way to process different messages by the same policy in the Business Rules Engine (BRE). In other words is it possible to create some sort of generic policy that can process different types of messages?

In his scenario the schemas had some fields in common and he needed those fields to be evaluated and optionally set in a single BRE policy.

Of course you can make a policy that depends on different schemas and add rules for each schema. The bad thing about that is that you will get multiple copies of almost the same rule which might lead to a maintenance nightmare.

I created a small sample to show how this can be achieved in a single policy and single rule. Below are three very basic schemas I used in this sample:

<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns:b="<a href="http://schemas.microsoft.com/BizTalk/2003">http://schemas.microsoft.com/BizTalk/2003</a>" xmlns="<a href="http://UntypedBRE.FirstSchema">http://UntypedBRE.FirstSchema</a>" targetNamespace="<a href="http://UntypedBRE.FirstSchema">http://UntypedBRE.FirstSchema</a>" xmlns:xs="<a href="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</a>">
  <xs:element name="FirstSchema">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="FirstName" type="xs:string" />
        <xs:element name="LastName" type="xs:string" />
        <xs:element name="IsJohn" type="xs:string" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns:b="<a href="http://schemas.microsoft.com/BizTalk/2003">http://schemas.microsoft.com/BizTalk/2003</a>" xmlns="<a href="http://UntypedBRE.SecondSchema">http://UntypedBRE.SecondSchema</a>" targetNamespace="<a href="http://UntypedBRE.SecondSchema">http://UntypedBRE.SecondSchema</a>" xmlns:xs="<a href="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</a>">
  <xs:element name="SecondSchema">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="FirstName" type="xs:string" />
        <xs:element name="LastName" type="xs:string" />
        <xs:element name="IsJohn" type="xs:string" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns:b="<a href="http://schemas.microsoft.com/BizTalk/2003">http://schemas.microsoft.com/BizTalk/2003</a>" xmlns="<a href="http://UntypedBRE.ThirdSchema">http://UntypedBRE.ThirdSchema</a>" targetNamespace="<a href="http://UntypedBRE.ThirdSchema">http://UntypedBRE.ThirdSchema</a>" xmlns:xs="<a href="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</a>">
  <xs:element name="ThirdSchema">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="FirstName" type="xs:string" />
        <xs:element name="LastName" type="xs:string" />
        <xs:element name="IsJohn" type="xs:string" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

I my sample policy I want to check the ‘FirstName’ element. If the value is equal to ‘John’ I want to fill the ‘IsJohn’ element with value ‘yes’. The policy (and single rule) should work for all of the above schemas.

The problem is that mentioned schemas belong to a different namespace and have a different root node, hence in BizTalk terms have a different message type. Because XML schema facts in the BRE are by default tightly coupled to a specific schema the consequence is that those facts can only operate on single type of message.

In order to make this generic you have to do the following:

1. Add one of the schemas to the Facts Explorer in the BRE.

2. Make the schema ‘general’

As you can see the Document Type resembles the type of the schema I added. To make this generic I change this value to ‘System.Xml.XmlDocument’. This will make sure that if I use a fact from this schema in a rule it will not be typed to this schema but will be generic.

3. Create the rule

In this step I create rule. The facts will be filled in later.

4. Modify the XML facts.

In the rule I need to evaluate the ‘FirstName’ fact and optionally set the ‘IsJohn’ fact. Because I want this to work on all schemas I need to define the facts in a generic way. If I click on the ‘FirstName’ fact I can see the xpath statements that point to this fact in the property pane:

The ‘Xpath Field’ and ‘Xpath Selector’ properties are directly referring to ‘FirstSchema’ root node and namespace. I change the values to make them generic also:

Note that I’m using ‘self::node()’ here. I described this trick before here.

Now the XML fact is no longer pointing to a specific namespace or root node. It just points to a ‘FirstName’ node somewhere in a Xml document.

There are of course other possible values for ‘XPath Selector’ and ‘XPath Field’ to solve this. It all depends on the schemas. If for example the facts you need all have the same parent node you can make the ‘XPath selector’ select the parent node and the ‘XPath Field’ select the ‘FirstName’ element.

I do the same for the fact I want to update in the action of the rule:

5. Complete the rule by adding the facts.

Finally I can drag the XML facts from the Facts Explorer to my rule to complete the condition and create a new action. Like this:

You can see that the both the condition and the action are not referring (anymore) to any specific schema  but instead to any schema that has ‘FirstName’  and ‘IsJohn’  elements.

Testing the rule with instances from two different schemas shows that this works:

One thing to note about this is that the way I changed the xpath statements for the Xml facts comes with a performance penalty. Using things like ‘//*…….’.  will make the engine go through the whole xml tree which is less efficient then using the original full xpath statement. So if performance is a strict requirement be careful using techniques like these.

Another thing is that I do not check for the existence of the nodes first. The policy will crash when an message is processed that does not contain on of the nodes used in the rule.