The Business Rules Framework, supplied with BizTalk Server 2004, is a technology that enables you to build, test, and deploy flexible rules that support your business processes. This article takes a hands-on, "how-to" approach and gives you some background regarding the Business Rules Framework before walking through the component parts of an example solution. The business scenario presented here is just an example – the technology and principles discussed throughout this article are applicable to a very wide range of applications and scenarios.

This article assumes that the reader is reasonably familiar with BizTalk Server 2004 and Visual C#. Code samples in this article are presented in C# but the code that accompanies the article includes both C# and Microsoft® Visual Basic®. No familiarity with the Business Rules Framework is assumed. This article explores an example risk-scoring process that we need to integrate into a larger BizTalk Server application. A fictional insurance company uses this risk-scoring process to create a view of each potential insurance applicant. This view is called a risk profile and it categorizes and scores different types of risk based on what is known about the applicant. The insurance company could then use this risk profile to calculate how much to charge for an insurance policy.

Our BizTalk Server application will provide an input XML document that contains information about an applicant that they provided when they first applied for insurance. We need to apply a set of business rules to this document to identify a set of risk factors that we can then use to build our risk profile. A risk factor identifies a category of risk with a score against it to indicate how significant that particular risk appears to be. For example, we might have a risk factor for health with a score that indicates the extent to which the applicant's health appears to be a risk. Our output risk profile is built as an XML document that will subsequently be processed by the rest of our BizTalk Server application.

Flexibility is an important requirement for our system. Business rules change frequently, so we need a way to rapidly put new or modified rules into production. We also need to enable our business analysts to work directly with our business rules – we don't want to tie up developers for a long time just to change a parameter value for one of our rules.

A key point to recognize at this early stage is the need to work with two different XML documents - input details about the applicant and an output risk profile - and the need to dynamically modify the contents of the risk profile document as we apply our business rules. We need to do something more than simply assigning values to pre-existing elements in an XML document. Dynamically modifying an XML document usually requires knowledge about things like XPath and DOM objects and so is typically in the developer's domain. We need to enable business analysts to do this by encapsulating the XML manipulation functionality that we need inside something that lets them focus on the business process.

The Business Rules Framework is a technology supplied with BizTalk Server 2004 aimed at the kind of scenario described above. It is made up of a number of .NET components, tools, and wizards that provide design-time support for building business rules as well as a runtime environment for executing your rules. After you have defined and tested a set of rules, it is easy to integrate them into a BizTalk orchestration or even call them directly from your own .NET applications.

Before digging into the technology, I want to say a little about the motivations behind the Business Rules Framework. Every business process needs rules. When you' apply for a loan, pay for groceries at your local supermarket, or check in at an airport, you are part of a business process that uses specific criteria to decide an appropriate outcome. Traditionally, these rules have been developed as procedural code in languages like Microsoft® Visual Basic®. Unfortunately, this approach can have some significant downsides.

Developing and testing this kind of procedural code requires developers to translate the requirements identified by business analysts into a form that their chosen language can understand. Coding complex, interrelated rules can be a tricky business and once your rules are encapsulated in code they can be hard for non-developers to understand. After it is deployed, it is very likely that your business rules will need to change over time. The effort involved in modifying, re-testing and then redeploying your business rules can be significant and doesn't fit well with today's vision of the agile business.

The Business Rules Framework takes a very different approach. The business rules that it executes are defined declaratively without a need for procedural instructions. As a result, the rules that you define are much closer to the way that they were originally envisioned by a business analyst. To make rule development accessible to more people in your organization, a straightforward graphical user interface is provided for rule creation and management. This tool allows you to focus on what your rules need to achieve rather than dealing with complex implementation detail. At runtime, a sophisticated forward-chaining inference engine processes your rules and takes the actions that you specified.

At this point we need to introduce some terminology and fundamental concepts. The Business Rules Framework is based on facts, vocabulary, definitions, and policy. Facts are the entities that your rules consume and manipulate – examples include an element that appears in an XML document, a column in a database table, or even a method exposed by a .NET component. A vocabulary is a collection of facts, and its purpose is both to apply meaningful, user-defined definition names to those facts and to provide a unit of versioning. Vocabulary definitions provide a neat level of abstraction that keeps procedural detail (for example, the SQL statement needed to provide a value from a database) separate from the definition names you refer to when writing your rules. You can use the same vocabulary across many different rules and rule sets.

We've referred to 'rules' many times so far without really defining what they are. In terms of the Business Rules Framework, a rule is a statement that defines the behavior of one aspect of a business process. For example, you might have a rule that says "If the loan applicant has a credit rating of 'good' then immediately approve the loan." This example rule shows us that rules are made up of facts, conditions and actions.

Fact: loan applicant's credit rating

Condition: credit rating is equal to 'good'

Action: immediately approve the loan

Conditions always evaluate either to true or false based on one or more predicates being applied to facts. In this case, the predicate is "is equal to". You can combine predicates with the logical conjunctions AND, OR, and NOT to build up complex conditions. Actions define what happens when your condition evaluates to true.

The last term that we need to define is policy. A policy is a set of rules, packaged and versioned as a unit. Policies are what you develop, test, and deploy when working with the Business Rules Framework. When you publish a version of your policy it can not be changed. This makes it easy to manage well-defined versions that contain consistent, predictable behavior. One final - and really important - thing that about policy is that you can update a policy in your production environment without needing to recompile and redeploy the BizTalk orchestrations that make use of it. Your BizTalk Server application will start using the new version in near real-time without any downtime.

Here's a brief rundown of the software pieces that make up the Business Rules Framework:

Business Rules Composer: This application enables you to define vocabularies and build and test rules. The rule-building experience is as simple as dragging and dropping facts and setting properties. You can also publish and deploy policies from here.

Rules Engine Deployment Wizard: Vocabularies and policies are stored in a SQL Server rule store database. To help you move a vocabulary or policy to another computer, this wizard provides import/export functionality. You can also deploy or undeploy a policy.

Rules Engine: This is the runtime engine that processes your policies. The engine evaluates rules, based on their facts, and decides which actions need to be executed. It also supports complexities like dealing with forward chaining. Forward chaining refers to the situation where your rule conditions modify the facts used in your policy; as the underlying facts change, the engine determines when it needs to re-evaluate your rule conditions.

The rules engine is implemented as a standalone .NET component. It can be called from inside BizTalk Serveror loaded into a process of your choice via a comprehensive API. With this is mind, you can install the rules engine on its own using the BizTalk Server 2004 installer or as part of a larger BizTalk Server installation.

This paper does not go into too much more technical detail about the Business Rules Framework because the SDK documentation does a great job of providing that. See http://go.microsoft.com/fwlink/?LinkId=42042 for more detail.

Building Our Vocabulary

Input XML Document

<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns="http://RiskScoring" xmlns:b="http://schemas.microsoft.com/BizTalk/2003" elementFormDefault="qualified" targetNamespace="http://RiskScoring" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="ApplicantDetails">
    <xs:annotation>
      <xs:appinfo>
        <b:properties>
          <b:property distinguished="true" xpath="/*[local-name()='ApplicantDetails' and namespace-uri()='http://RiskScoring']/*[local-name()='ApplicationID' and namespace-uri()='http://RiskScoring']" />
        </b:properties>
      </xs:appinfo>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="ApplicationID" type="xs:long" />
        <xs:element minOccurs="1" maxOccurs="1" name="PersonalDetails">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Name" type="xs:string" />
              <xs:element name="Age" type="xs:int" />
              <xs:element name="CurrentHealth" type="HealthStatus" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element minOccurs="1" maxOccurs="1" name="Interests">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="LionTaming" type="xs:boolean" />
              <xs:element name="Reading" type="xs:boolean" />
              <xs:element name="ExtremeSports" type="xs:boolean" />
              <xs:element name="WatchingTV" type="xs:boolean" />
              <xs:element name="BearWrestling" type="xs:boolean" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element minOccurs="1" maxOccurs="1" name="FinancialDetails">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="NumTimesBankrupt" type="xs:int" />
              <xs:element name="AnnualIncome" type="xs:int" />
              <xs:element name="AnnualExpenditure" type="xs:int" />
              <xs:element name="OwnProperty" type="xs:boolean" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:simpleType name="HealthStatus">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Great" />
      <xs:enumeration value="OK" />
      <xs:enumeration value="Poor" />
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

<ns0:ApplicantDetails xmlns:ns0="http://RiskScoring">
  <ns0:ApplicationID>10</ns0:ApplicationID>
  <ns0:PersonalDetails>
    <ns0:Name>John Dangerlover</ns0:Name>
    <ns0:Age>99</ns0:Age>
    <ns0:CurrentHealth>Poor</ns0:CurrentHealth>
  </ns0:PersonalDetails>
  <ns0:Interests>
    <ns0:LionTaming>true</ns0:LionTaming>
    <ns0:Reading>true</ns0:Reading>
    <ns0:ExtremeSports>true</ns0:ExtremeSports>
    <ns0:WatchingTV>true</ns0:WatchingTV>
    <ns0:BearWrestling>true</ns0:BearWrestling>
  </ns0:Interests>
  <ns0:FinancialDetails>
    <ns0:NumTimesBankrupt>10</ns0:NumTimesBankrupt>
    <ns0:AnnualIncome>1000</ns0:AnnualIncome>
    <ns0:AnnualExpenditure>10000</ns0:AnnualExpenditure>
    <ns0:OwnProperty>false</ns0:OwnProperty>
  </ns0:FinancialDetails>
</ns0:ApplicantDetails>

Output XML document

<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns="http://RiskScoring" xmlns:b="http://schemas.microsoft.com/BizTalk/2003" elementFormDefault="qualified" targetNamespace="http://RiskScoring" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="RiskProfile">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="ApplicationID" type="xs:long" />
        <xs:element name="OverallRisk" type="xs:int" />
        <xs:element name="DateCreated" type="xs:dateTime" />
        <xs:element name="RiskElements">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Personal" type="RiskElement"/>
              <xs:element name="Financial" type="RiskElement" />
              <xs:element name="Interests" type="RiskElement" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:complexType name="RiskElement">
    <xs:sequence>
      <xs:element name="Details">
        <xs:complexType>
          <xs:sequence minOccurs="0" maxOccurs="10">
            <xs:element name="Detail" type="xs:string" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="Score" type="xs:int" />
  </xs:complexType>
</xs:schema>

<?xml version="1.0" encoding="utf-16"?>
<RiskProfile xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://RiskScoring">
<ApplicationID>10</ApplicationID>
<OverallRisk>1000</OverallRisk>
<DateCreated>2004-11-26T16:22:01.2775888-08:00</DateCreated>
<RiskElements>
<Personal Score="0">
<Details />
</Personal>
<Financial Score="1000"> 
<Details>
<Detail>Applicant failed credit check</Detail>
</Details>
</Financial>
<Interests Score="0">
<Details />
</Interests>
</RiskElements>
</RiskProfile>

RiskProfileHelper Component

public void AddRisk(RiskCategory category, int scoreAdjustment, string detail)

CreditCheck Component

Putting the Vocabulary Together

As discussed earlier, rules are grouped into policies. Our policy will contain six rules that we want to run against every set of applicant details to produce a risk profile. Over time, we expect these rules to be modified – not just tweaks to parameters, but also new rules added and existing rules removed. The Business Rules Composer makes this easy to achieve without becoming involved in software development.

The code for this article includes a completed policy file – if you don't want to build the rules for yourself, you can import the policy using the Rules Engine Deployment Wizard.

Before we start adding rules, we need a policy to contain them.

To create a new policy:

1. Open the Business Rules Composer.
   
2. Connect to your local BizTalk rules engine database (default name is BizTalkRuleEngineDb).
   
3. Select the Policies folder in the Policy Explorer Window.
   
4. Right-click on the Policies folder and select Add New Policy.
   
5. Rename the new policy RiskScoring.
   

This creates version 1.0 of your policy. The first three rules that we need to build are detailed below. The rules appear here as they appear in the Business Rules Composer.

At the moment we have a policy containing six rules that work with facts provided by our vocabulary. What we haven't seen so far is any rule execution. Testing your rules in the Business Rules Composer is straightforward but before we can begin there is one additional piece of code that we need to briefly explore – a fact creator.

At runtime our rules require three different facts to be available - an XML instance document containing applicant details, an instance of our CreditCheck component and an instance of our RiskProfileHelper component. Where do these facts come from? The short answer is that something needs to create them and then supply them to the rules engine. If we're running our rules from within a BizTalk orchestration then we can pass in orchestration variables of the relevant types. Things are slightly different when we're testing our rules inside the Business Rules Composer. The following figure shows the dialog that appears when you right-click on your policy and select Test Policy.

Figure 1 Select Facts dialog box

As you can see, the dialog box allows us to specify an XML file for our ApplicantDetails fact. To supply our .NET components we need to specify a fact creator. As the name suggests, this is a component that will supply instances of the required fact types. Implementing a fact creator is easy enough to do – the requirement is a component that implements the IFactCreator interface. Here's the code for our fact creator:

public class FactCreator : IFactCreator
{
public FactCreator()
{
}
#region IFactCreator Members

public object[] CreateFacts(RuleSetInfo ruleSetInfo)

{
CreditCheck cc = new CreditCheck();
object[] facts = new object[2]{
new RiskProfileHelper(),cc};
return facts;
}

public Type[] GetFactTypes(RuleSetInfo ruleSetInfo)
{
return null;
}

#endregion
} 

As you can see, IFactCreator requires us to implement two methods – CreateFacts supplies an array containing our fact instances and GetFactTypes supplies an array containing corresponding type information. Incidentally, even if you're only calling static members (Shared in Visual Basic) on a .NET class you always need to provide an instance of that class to the rules engine.

After you have an input XML document and have configured your fact creator, testing is as simple as clicking the Test button. As the rules engine processes your rules, details about the execution process are written out to the Output window. The output here shows you events including

• Facts being added into memory for processing (Assert/Update/Retract operations)
  
• Rule conditions getting evaluated
  
• Agenda modifications
  
• Rules that are invoked
  

In addition, when in debug mode, the RiskProfileHelper will save out the risk profile to a file in its finalizer. By default this file is placed in the root of your C: drive. This file gives you a simple way of checking the resulting risk profile alongside the rule execution output that appears in the Business Rules Composer.

When testing your policy, you can selectively enable and disable each rule by modifying its Active property. As discussed earlier, you can also tweak the Priority property if you need to influence the order in which your rules get processed.

When you've finished your testing, you need to publish and deploy your policy. You can perform each of these tasks by right-clicking on your policy inside the Business Rules Composer and then selecting the appropriate option. Publishing locks your policy's interface and deployment makes your policy available to the rules engine runtime outside of the Business Rules Composer.

Now that you have a deployed policy, it's time to integrate it into a BizTalk Server application. As discussed earlier, the rules engine is accessible from BizTalk Server. It is actually a standalone .NET component. As a result, there is more than one way to execute your rules from within an orchestration:

• Add a Call Rules shape.
  
• Execute your policy using the Business Rules API, most likely in an Expression or Message Assignment shape.
  

The second option provides a little more flexibility because it allows you to specify a specific version of your policy rather than automatically using the most recent version. We'll be exploring the more common Call Rules shape in this paper but see the SDK documentation for the Microsoft.RuleEngine.Policy class if you need to dig into the API option.

The Call Rules shape enables us to call out to a specified policy, passing in the facts that the policy consumes as parameters. These parameters are assigned to messages and variables in our orchestration.

The code that accompanies this paper includes a sample BizTalk Server application with a simple orchestration that makes use of the Call Rules shape. The following figure shows the orchestration.

Figure 2 Example application orchestration

Here's an overview of what's going on in the orchestration.

1. Pick up an applicant's details message from a receive location.
   
2. An orchestration variable contains a reference to a RiskProfileHelper object.
   An Expression shape is used to set the ApplicationID property to match the incoming applicant details message
   
3. Use the Call Rules shape to call into our policy. The facts that our policy needs are tied to messages and variables defined in our orchestration. If you right-click on a Call Rules shape and choose Configure…, you are presented with the dialog box that appears in the following figure.
   
4. Get the completed risk profile from our RiskProfileHelper. This is assigned to a message which is sent out using a send port.
   

Figure 3 CallRules policy configuration dialog box

As you can see, adding and configuring a Call Rules shape to an orchestration is very straightforward. There are a couple of things that you need to be aware of:

• The Call Rules shape must be placed into an atomic scope or orchestration
  
• You need to be careful when configuring your facts to ensure that the Document Type name that you supply in the Business Rules Composer is identical to the message type name as it appears to BizTalk.
  

To see the orchestration above in action, build and deploy the supplied BizTalk Server application and bind the send and receive ports as required on your machine. We used simple file send and receive locations for this. Assuming that you're doing the same, drop an example applicant details file into the receive location to activate the orchestration. The code that accompanies this paper includes sample XML instance files in the XmlInstances folder. After some processing, you should see a new risk profile appear in your file send location.

Rules engine execution can be tracked in the Health and Activity Tracking (HAT) tool alongside orchestrations, messages, and pipelines. To enable tracking for a policy, open up Configuration | Policies on the HAT main menu and select the policy of interest. From here you can specify the type of tracking that you wish to enable or disable for the selected policy. The great thing here is that policy tracking information is available through the regular message flow screen alongside the standard message tracking details. If policy tracking information is available for an orchestration instance, a new link appears that takes you to the relevant tracking information. The categories of data here are governed by the tracking options that you enabled for the policy that got executed. For example, the following figure shows some tracked fact activity.

Figure 4 HAT policy execution tracking

When you work with the Business Rules Composer, you're loading and saving policies and vocabularies from a specified SQL Server database. Typically, this is your local BizTalk development database or a shared development database. You might be wondering how you move those policies and vocabularies from that machine to a new location. For example, you might want to move a policy from a development database to a testing database or maybe export your policy out to a file which you can then check into your source control system. The answer, as you might have guessed, is the Rules Engine Deployment Wizard.

The Rules Engine Deployment Wizard is a simple tool but one that you'll definitely need to use. It offers the following functionality:

• Export a policy or vocabulary from SQL Server to an XML file
  
• Import and publish a policy or vocabulary from an XML file into SQL Server
  
• Deploy a policy
  
• Undeploy a policy
  

The code supplied with this paper contains both a vocabulary and a policy. To make use of these files you'll need to first add the referenced RiskScoringHelper assembly into your GAC. You can do this either by building the assembly (if you're using the C# version of the code) or by running the supplied batch file. You can then use the Rules Engine Deployment Wizard's import functionality to import the vocabulary and policy files into your chosen BizTalk SQL Server rules engine database. Import the vocabulary file (RiskScoring_Vocabulary.xml) followed by the policy file (RiskScoring_Policy.xml). Finally, you need to deploy the policy. You can either do this from the Business Rules Composer (right-click on the policy and choose Deploy) or use the deploy feature that the wizard provides.

The goal of this paper is to give you an insight into the power and flexibility of the Business Rules Framework and maybe given you a few ideas about how you could incorporate business rules into one of your projects. The scenario presented here looked at a specific, fictional business but the requirements that the article explored – run a set of rules against an input document to produce a customized, flexible output document – are pretty common. Finally, the features explored here are by no means all that the Business Rules Framework has to offer; for more information you should fully explore the SDK and product documentation.