You want to understand the process for creating business rule policies. These policies are core components to all business rule development.

The business rules framework consists of policies, rules, vocabularies, and facts. A business policy is the container in which business rules are defined, versioned, tested, deployed, and executed. From within the business policy editing window, the first step before creating rules is to create a policy. The policy then may contain one or more rules for deployment. To create a policy, take the following steps:

Figure 7.2. The Policy Explorer frame within the Business Rules Composer

Creating a business rules policy is a relatively simplistic exercise but is the foundation to the business rules framework. Once you have created the policy, you can add rules and facts to the policy for testing and deployment. When calling the policy from BizTalk, the latest version will be selected for execution, unless you specify a specific version. The rules engine detects and deploys new versions of a policy, allowing changes to be made to the business policy in a live, deployed process. This creates a powerful environment to apply a dynamic business policy to deployed solutions with minimal work. The recipes in this chapter will guide you through adding rules, facts, and vocabularies to your business rules policy.

You need to create and test a simple business rule that a business process can use. The business process needs to validate a document and receive the result.

You need to perform a number of basic steps to create a rule. These include the following:

The first step to creating a rule is determining the logic of the rule. This example will use the logic in Listing 7-1 to construct the rule.

If Age < Minimum Age Then Deny Application
If Age > or = Minimum Age Then Accept Application

We will show how to execute the rule in Listing 7-1 against an XML document containing the data that will be validated. For this example, we will use the NewHire schema (Figure 7-3) with the schema and XML instance (Listing 7-2).

Figure 7.3. NewHire schema

<ns0:NewHireList xmlns:ns0="http://CreatingAndTestingRules.NewHire">
  <DateTime>2010-08-04T18:00:00</DateTime>
  <Person>
    <ID>1</ID>
    <Name>Mary</Name>
    <Role>Office Manager</Role>
    <Age>31</Age>
  </Person>
  <Person>
    <ID>2</ID>
    <Name>Windy</Name>
    <Role>Organist</Role>
    <Age>38</Age>
  </Person>
</ns0:NewHireList>

The next step in this solution is to output a document. The document that is sent to the rules engine will be modified and returned to the calling entity. If the applicant's age is not a valid age, the document will be modified to display the text "INVALID APPLICANT" in the <Role> element (this element must exist in order for it to be set).

The following steps describe how to create the vocabulary using the Business Rule Composer:

The steps up to this point have been putting into place the components needed to create a business rule. A rule (or set of rules) is defined within a policy and references preexisting functions, predicates, and any custom-defined constants (such as what you defined in the previous steps). The following steps show how to create the actual business rule and policy and use the vocabulary created previously:

The rule is complete at this point. Save the rule (right-click Version, and select Save). You can now test the rule (and policy). Use these steps to validate and test the rule:

You can now call the rule and policy from an orchestration. To call the rule and policy from an orchestration, perform the following steps:

The XML instance shown in Figure 7-11 represents the generated output from testing the business rule created in this solution.

Figure 7.11. Final XML

There are additional uses of the rules engine, including the ability to store parameters that can be accessed from orchestrations. Similar in nature to a configuration file that stores parameters that may need to change (such as connection strings) once a solution is in production, these constants allow for runtime modifications. Benefits to using the rules engine to store configurable parameters include ease of access, simple user interface, and enhanced read/write permissions (compared with a text file containing configurable parameters).

To add parameters that can be accessed from an orchestration, there are two basic steps: create the parameters, and access the constants through the rules engine API.

The first step is to create the parameters in a vocabulary in the rules engine and save them. You don't need to publish them unless versioning would be helpful. If they are not published, it is easier to modify them at runtime, because all that is required is to right-click the value that needs to be changed and select Modify. Once you have saved the vocabulary, running instances of orchestrations that reference these parameters will pick up the new values.

The second step is to add .NET code to a BizTalk Helper class to access the vocabulary through the rules engine API. The code shown in Listing 7-3 can be placed into a .NET assembly and should be referenced by a BizTalk project. The method can then be called from an Expression shape within an orchestration. This code also allows for a specific version to be called, if desired.

public bool blnGetVocabularyConstantValue(string strVocabularyName,
                                    string strConstantName,
                                    string strVersion,
                                    ref string strConstantValue,
                                    ref string strConstantType) {

   RuleStore rlsRuleStore;
   VocabularyInfoCollection vicVocabInfo;
   Vocabulary vocVocab;
   RuleSetDeploymentDriver rsdDriver = new RuleSetDeploymentDriver();
   Hashtable hshTable;
   LiteralDefinition litDef;
   Boolean blnConstantFound = false;

   rlsRuleStore = rsdDriver.GetRuleStore();

   if((strVersion == null) || (strVersion == "")) {
    vicVocabInfo = rlsRuleStore.GetVocabularies(strVocabularyName,
                               RuleStore.Filter.Latest);
   }
   else {
    vicVocabInfo = rlsRuleStore.GetVocabularies(strVocabularyName,
                               RuleStore.Filter.All);
   }

   // check to see that the vocabulary searched on has returned data
   if(vicVocabInfo.Count > 0) {
    for(int x=0;x<vicVocabInfo.Count;x++) {

    vocVocab = rlsRuleStore.GetVocabulary(vicVocabInfo[x]);

    // Check to see that the version equals the version being searched for
    // or that the version passed in was a wildcard (Null)
    if((strVersion == null) || (strVersion == "") ||
    ((vocVocab.CurrentVersion.MajorRevision + "." +
      vocVocab.CurrentVersion.MinorRevision) == strVersion)) {

     // Initialize the hashtable to the number of definitions on the vocabulary

hshTable = new Hashtable(vocVocab.Definitions.Count);
     hshTable = (Hashtable)vocVocab.Definitions.SyncRoot;

     // check that the constant being searched for exists in the vocabulary
     if(hshTable.ContainsKey(strConstantName)) {
      litDef = (LiteralDefinition)hshTable[strConstantName];

      strConstantType = litDef.Value.GetType().ToString();
      strConstantValue = litDef.Value.ToString();

      blnConstantFound = true;

      // exit loop
      break;
     }
    }
   }
  }
 return blnConstantFound;
}

You can use the code in Listing 7-4 to invoke the previous class from an orchestration Expression shape. This allows for an alternate method of access to the rules engine without needing the standard call using the Call Rules shape and is useful when getting the value of a constant or other scalar value.

// the following string is the name of the vocabulary
strVocabularyName = "Project.BizTalk.Constants";
objVocab.GetVocabularyConstantValue(strVocabularyName, "ConstantName", "",
                                                  "10", ref strValue,ref strType);

You need to understand how to use the Facts Explorer to create a vocabulary that will be used within a business rule fact. You want to be able to store constants, predicates, and so on, that can be changed easily without redeploying code.

This solution will demonstrate how to create a vocabulary using a node in an imported XML schema. Facts are those items that are used to create rules. The Facts Explorer has four tabs, as follows:

Use the following steps to import an XML schema and create a new vocabulary:

You can add the Database and .NET Assembly facts to the Vocabulary tab in a similar manner as described in this solution. Additionally, you can drop all facts in the condition or action (IF...THEN) of a rule. Once you have added a fact to a rule, right-clicking the condition or action allows you to browse to the original fact, as shown in Figure 7-12. Complex rules will have many facts referenced in them, and this allows you to keep track of all the disparate definitions.

Figure 7.12. Action with fact

You need to control the order in which the BizTalk rules engine executes rules. The order BizTalk executes rules in determines which rules take precedence, with the results of the last rule executing and potentially overwriting the results of the previous rules.

In many real-world scenarios, multiple business rules must execute in a predetermined order. In these situations, the second rule may overwrite the result of the first rule. Control the order in which the BizTalk rules engine executes rules by assigning a priority to each rule.

The following steps demonstrate how to set the priority of a business rule:

Figure 7.13. Setting the Priority property

The BizTalk rules engine executes high-priority rules first. Consequently, lower-priority rules execute after higher-priority ones and potentially can override the results of higher-priority rules. The BizTalk rules engine may execute rules with the same priority in any order. Remember that the priority of rules will affect the order BizTalk executes them in and has no direct effect on the importance of the rule's actions.

You need to define business rules using facts that an orchestration cannot provide. The facts may not be available in the orchestration, or you may need to reuse a fact across many instances of the orchestration.

A business rule performs actions when conditions defined in the Business Rule Composer are true. For example, an action may modify a value in a message. The BizTalk developer creates a condition from facts, which are pieces of information the rules engine can examine. Most often, the rules engine will examine facts from the messages BizTalk directly processes. The orchestration invoking the rules engine directly provides these facts. However, sometimes a rule needs to be based on facts that are not available in the orchestration. The rules engine can retrieve these external facts with a custom fact retriever.

In this example, a business rule will schedule a customer's service request only if the customer's address is in the Northwind database. The customer's address may be different each time the orchestration invokes the rules engine. The customer's address is called a short-term fact because the orchestration provides the fact every time it invokes the rules engine. However, instead of opening a new connection to the database each time the orchestration invokes the rules engine, this example reuses the same connection to the Northwind database over and over again. Reusing the database connection makes it a long-term fact. The BizTalk developer must provide long-term facts to the rules engine with the IFactRetriever interface. The custom fact retriever created in this recipe provides the connection to the Northwind database to the rules engine.

Use the following steps to create the custom fact retriever:

The rules engine examines facts provided either directly from an orchestration or from a custom fact retriever. The facts provided directly from an orchestration are called short-term facts, and the orchestration supplies them each time BizTalk invokes the rules engine. The facts provided from a custom fact retriever are called long-term facts, and they can be reused each time BizTalk invokes the rules engine.

A BizTalk orchestration can also treat the DataConnection in this example as a short-term fact. Accomplish this by creating a DataConnection in an Expression shape and including it as a parameter to the Call Rules shape. However, each orchestration instance would create its own DataConnection. You can improve the scalability and performance of the application by treating the DataConnection as a long-term fact and sharing it each time BizTalk invokes the rules engine.

In general, treating a fact as long-term is preferable under the following conditions:

The rules engine invokes the custom fact retriever's UpdateFacts method each time the policy executes. This method decides when to update the facts. In this example, the UpdateFacts method examines the factsHandleIn parameter to check whether the DataConnection was already created. If the factsHandleIn parameter is null, the method creates the DataConnection, inserts it into the rules engine, and completes by returning the DataConnection object. The next time the rules engine invokes the method, the rules engine includes the object returned by the method in the factsHandleIn parameter. If the factsHandleIn parameter is not null, the method knows that it has already inserted the DataConnection into the rules engine, and it simply returns the same object.

Although this solution example uses a simple algorithm to decide when the long-term fact needs updating, the developer can implement a more sophisticated approach. For example, the developer could refresh the facts every hour by returning a DateTime object when the facts are refreshed and decide to update facts by comparing the last refresh time to the current time.

You are building a solution that must execute business rules based on dynamic information. These business rules are likely to change over time, and you want to minimize the impact on the solution when modifications are needed. To do this, you want to be able to call the rules engine from a .NET assembly.

This solution describes the steps necessary to call the business rules engine from a C# assembly. The steps detail how to build a .NET Windows application to process job applications and dynamically determine whether applicants meet a minimum age requirement. If the applicant is younger than a certain age, that person cannot be considered for employment. The minimum age is likely to change over time and needs to be easily configurable. The business rules engine that comes with BizTalk Server captures the business rule determining the minimum working age. Other recipes within this chapter detail the steps for creating rules.

This solution assumes that a rule exists in the business rules engine to determine whether an applicant meets the minimum age requirements. To call this rule from a .NET application, follow these steps:

public void callSamplePolicy(ref System.Xml.XmlDocument newHireListDoc)
{
    // create the SamplePolicy policy object
    // specify policy name and version
    Microsoft.RuleEngine.Policy policy =
             new Microsoft.RuleEngine.Policy("SamplePolicy", 1, 0);

    // create the facts object array to hold the input parameters for the policy
    object[] facts = new object[1];

    // create the input parameter for the SamplePolicy policy
    // based on a typed BizTalk schema (fully qualified .NET type)
    Microsoft.RuleEngine.TypedXmlDocument typedXmlDoc =
      new Microsoft.RuleEngine.TypedXmlDocument("SampleSolution.NewHireList",
                                                                   newHireListDoc);

    // add the input parameter to the facts object array
    facts[0] = typedXmlDoc;

    // execute the policy against the facts
    policy.Execute(facts);
    policy.Dispose();

    // set the parameter object
    newHireListDoc.LoadXml(typedXmlDoc.Document.OuterXml);
}

Although the business rules engine comes as part of BizTalk Server, this solution shows that .NET assemblies outside the BizTalk environment can call into it. This allows external applications to use the same rule framework that the integration hub does, enabling companies to consolidate their business rules functionality onto one platform.

For a .NET project to call into the business rules engine, it must reference the Microsoft.RuleEngine.dll assembly. This assembly contains the classes used to access the rules framework, including those to execute policies. In this solution, you first create an instance of the policy object, with the appropriate name and version. The name must exactly match the name of the policy you want to execute. This solution specifies SamplePolicy as the policy name, which maps to the highlighted name in Figure 7-18.

Figure 7.18. The name of the policy must match the .NET code exactly

Following the policy name, you specify the major and minor versions of the policy you want to execute. You specify 1.0, which is the only version of the policy currently deployed. Alternatively, you could specify the name only when creating the policy object (no version parameters supplied to the policy's constructor method), which executes the most recently deployed version of the policy.

Next, you create a collection (array) of fact objects. This array holds all the objects necessary to execute the policy. These objects map to the different types of facts that the Business Rule Composer can create, including XML documents, .NET classes or class members, and database connections. The SamplePolicy policy uses only a single XML document fact, which you create next.

You use the Microsoft.RuleEngine.TypedXmlDocument class to create an XML document fact, specifying the document type (the fully qualified .NET type name) and XML document instance. Add this TypedXmlDocument to the fact collection.

Finally, you execute the policy against the facts collection. The facts collection is passed as a reference parameter, meaning any changes to the facts will be committed to the original instances. In this solution, the XML document fact will have the appropriate minimum age requirement logic applied.

It is also possible to execute a policy directly from an Expression shape within an orchestration. Listing 7-8 illustrates how you would execute the same policy as described in the "Solution" section of this recipe but from an Expression shape.

// create the SamplePolicy policy object
// policy variable has type of Microsoft.RuleEngine.Policy. Create this in Orchestration View Variables
policy = new Microsoft.RuleEngine.Policy("SamplePolicy", 1, 0);

// create the input parameter for the OrderShipping policy
// typedXmlDoc variable has type of Microsoft.RuleEngine.TypedXmlDocument
// NewHireListMessage has type of SampleSolution.NewHireList
typedXmlDoc =
  new Microsoft.RuleEngine.TypedXmlDocument("SampleSolution.NewHireList",
                                                           NewHireListMessage);

// execute the policy against the facts
policy.Execute(typedXmlDoc);
policy.Dispose();

Although the policy executed in this recipe requires only a single XML document fact, facts can also be .NET classes or class members and data connections. By default, BizTalk Server requires you to provide an object instance for each fact used in a policy.

To pass a data connection fact to a policy, initialize a Microsoft.RuleEngine.DataConnection instance and pass it to the policy in the facts collection. If an update is being executed against the underlying database, you must also provide a transaction to the DataConnection object, as shown in Listing 7-9. If data is being retrieved only, no transaction is required.

// create SQL connection object
sqlConnection = new System.Data.SqlClient.SqlConnection("ConnectionString");

// create SQL transaction object
sqlTransaction = sqlConnection.BeginTransaction();

// create Data Connection object
dataConnection = new Microsoft.RuleEngine.DataConnection(
        "SqlDataSetName",
        "SqlTableName",
        sqlConnection,
        sqlTransaction);

The .NET assembly can add this DataConnection object instance to a fact collection and pass it to the policy for execution.

You are building a workflow that must execute business rules based on dynamic information. These business rules are likely to change over time, and you want to minimize the impact on the solution when modifications are needed.

This solution will demonstrate how to call the business rules engine from an orchestration, without using a .NET assembly. The basic problem is similar to the previous recipe. The key points of the problem are as follows:

This solution assumes that a rule exists in the business rules engine to determine whether an applicant meets the minimum age requirements. To call this rule from an orchestration, follow these steps:

Calling the business rules engine from an orchestration is a straightforward task. It allows you to separate the business procedure and process flow from the business rules. This is particularly useful when the rules are used across many process flows, change frequently, or need audit logging and versioning capabilities.

This recipe's solution uses a message instance conforming to the NewHireList schema as an input parameter to the SamplePolicy business rule policy. This policy sets the <Role> element of the message to INVALID APPLICANT if the <Age> element is less than a certain age. You could then enhance the rule to apply different minimum age requirements for different roles or to retrieve real-time minimum age requirements from a government-run data source.

You could easily extend this solution to illustrate how the output from a business rule can facilitate business procedures and process flow within an orchestration. Business rule policies could define a complex set of rules to determine whether an applicant is valid for a role. As opposed to setting the <Role> element to INVALID APPLICANT, you could configure the policy to return a Boolean value indicating whether the applicant meets the minimum age requirements. The orchestration could then use this Boolean value in a Decide shape, allowing separate process flows to determine whether an applicant is valid for a role based on previous work experience, personal references, and salary requirements.

For an orchestration to successfully call a policy, you must make a few settings:

Although this solution uses only an XML message instance as input to the rules policy, policies can accept other types of input parameters as well. The Vocabulary Definition Wizard allows a .NET class or class member or a data table or column to be used as a business term. As previously stated, an initialized instance of all variables referenced in a policy must be in scope at the Call Rules shape in the orchestration. This means that if a .NET class and a data table or column are used in a policy, there must be an initialized instance of the .NET class and rules engine Microsoft.RuleEngine.DataConnection object available in the orchestration to pass into the policy as input parameters.

The policy used in this scenario references vocabulary definitions based on two XML elements in the NewHireList schema: <Age> and <Role>. Take care when creating these vocabulary definitions, or the rule policy won't be able to appropriately handle the orchestration message. Specifically, set the Document Type property of the business term to be the fully qualified type name. If the fully qualified .NET type name is not used to define the BizTalk schema, BizTalk Server will not have enough information to uniquely identify the data field.

A finer point regarding the Call Rules shape is that it treats input parameters as reference parameters, which means rules may modify the objects passed and return them to the orchestration. Given that messages are immutable (once they are created, they cannot be modified) in BizTalk, how does this work? The answer is that, behind the scenes, the policy creates a modified copy of the original message. Although this saves the developer's time when creating their orchestration, it also has an important side effect: all promoted properties on the original message are removed from the message context. If properties on the message need to be maintained, make a copy of the message to allow the message context to be reset after the business rules engine is called.

You want to know the components that make up a rules engine policy and perform the steps necessary to deploy and undeploy a policy to make the rule sets available to business processes.

Deploying a policy requires that several components be in place prior to the deployment. The deployment is quite straightforward, and you can deploy in several ways. This solution describes the prerequisites to the policy deployment and walks through the deployment steps using the Business Rule Composer.

A policy consists of one or more rules. A rule comprises a set of facts. In this solution, we describe the process to deploy and undeploy all the components that make up a policy. Your first task is to define any facts that may need to be used in any rules that are part of the policy:

You have two basic approaches for deploying and undeploying policies. The first is to use the Business Rule Composer. Using the Business Rule Composer, you can define facts and policies that can be modified, published, and deployed. The second is to use the Rules Engine Deployment Wizard (see Figure 7-20). The wizard allows policy files to be exported and imported onto machines where they may not have been created.

Figure 7.20. The Rules Engine Deployment Wizard

Use the following basic steps to deploy a policy in a distributed environment (See Figure 7-21 for all options):

Figure 7.21. Using the Rules Engine Deployment Wizard