IT tutorials
Applications Server

BizTalk Server 2009 : Executing Business Rules (part 1) - Returning a Value from the BRE to the Calling Orchestration

6/20/2013 7:57:17 PM
- How To Install Windows Server 2012 On VirtualBox
- How To Bypass Torrent Connection Blocking By Your ISP
- How To Install Actual Facebook App On Kindle Fire

Application developers can call upon the BRE to execute business policies from within their .NET code or through the Call Rules shape in their BizTalk orchestrations. At runtime, the Business Rules Framework provides a caching mechanism for RuleEngine instances. Each RuleEngine instance contains an in-memory representation of a specific policy version.

According to the BizTalk Server 2009 documentation (Microsoft, 2009), when a new policy instance is instantiated, either through a direct call from a .NET application through the API or the execution of the Call Rules shape in an orchestration, the following happens:

  1. The Policy object requests a RuleEngine instance from the rule engine cache.

  2. If a RuleEngine instance for the policy version exists in the cache, the RuleEngine instance is returned to the Policy object. If a RuleEngine instance is not available, the cache creates a new instance. When a RuleEngine instance is instantiated, it does, in turn, create a new fact retriever instance if one is configured for the policy version.

Likewise, when the Execute method is called on the Policy object, the following steps occur:

  1. The Policy object calls the UpdateFacts method on the fact retriever instance if a fact retriever exists. The fact retriever's implementation of the method may assert long-term facts into the working memory of the RuleEngine.

  2. The Policy object asserts the short term facts contained in the Array that was passed in the Execute call.

  3. The Policy object calls Execute on the RuleEngine.

  4. The RuleEngine completes execution and returns control to the Policy object.

  5. The Policy object retracts the short term facts from the RuleEngine. The long term facts asserted by the fact retriever will remain in the working memory of the rule engine.

After the Dispose method is called on the Policy object, the RuleEngine instance is released back to the rule engine cache.

The rule engine cache will have multiple rule engine instances for a given policy version if the load requires it, and each rule engine instance has its own fact retriever instance.

1. Calling the Engine from Within an Orchestration

Orchestration developers can use the Call Rules shape to call upon the Business Rule Engine to execute a business rule policy. They can assert facts to the policy that they wish to execute by passing them as parameters to the Call Rules shape. This is done by double-clicking the Call Rules shape, which brings up the parameters dialog depicted in Figure 1.

Some logic might require an Orchestration Designer to use the Call Rules shape in a loop. If the loop executes quickly—i.e., it takes only seconds or minutes—then this is fine. If the loop spans days and the logic is hanging on to a specific policy instance, then "policy version updates will not be picked up by the rule engine instance executing the policy..." and "the overall application performance may suffer as the rule engine instance held onto by the policy will be tied up and not returned to the pool to be reused by other orchestrations".

Figure 1. CallRules policy configuration dialog in the Orchestration Designer

Parameters to an orchestration's Call Rules shape are implicitly defined in the policy. These facts can be XML schema instances, .NET classes, or database elements. If a schema is referenced in a policy's rule, the Orchestration Designer is required to pass in an instance of that schema as a parameter as a fact that will be evaluated.

In their orchestrations, the developers will have to select a message that matches the same type from the drop-down list in the Call Rules shape. Oftentimes developers run into the issue where they are not allowed to add any parameters in the Call Rules shape. This means there are no messages defined in the orchestration with the same type as the schema used in the policy. The problem is that the document type in the Business Rule Engine and the message type in the schema do not match, so the designer cannot find any messages with the appropriate type to populate the drop-down lists in the parameter selection dialog.


We mentioned this before, but so many developers run into the issue that it is worth mentioning again. If you expect to be able to assign messages as parameters to a Call Rules shape in an orchestration and the Orchestration Designer is not allowing you to do so, then most probably the document type defined in the Facts Explorer is not fully qualified; you need to fix that before you add the fields to your rules.

2. Referencing a .NET Class from a Policy That Is Being Called from an Orchestration

A developer might want to reference and use a .NET class in the business policies. The class could provide helper functions to add nodes to an XML document, the ability to store rule results in an array or a hash table, or make calls to another set of libraries (Moons, 2005).

If the policies are using a .NET class member as a fact in the business rules, and you need to call these policies from within an orchestration using a Call Rules shape, you need to do two things:

  • At design time, reference the assembly in the Business Rule Composer to use the methods and/or properties in the policy rules, so that you can create vocabulary items based on that class, or simply use properties and member functions of that class in your rule's conditions and actions.

  • Pass an object instance of that class into the policy at runtime. This needs to be done even if you are just referencing static members of the class.

    1. Add a reference to your .NET class in the BizTalk project that contains the orchestration making the call to the business rule policy.

    2. Add a variable to the orchestration of that .NET class type.

    3. Create an instance object of the class in an Expression shape.

    4. Select the policy in the Call Rules shape and select the variable you defined previously in the orchestration as a parameter to that policy. "The messages or variables that are available to you in the rules shape parameter list are determined by the XML Schemas or classes referenced in the policy. When you select the .NET class variable you will be asserting the class instance into the rules engine at runtime" (Moons, 2005).

3. Returning a Value from the BRE to the Calling Orchestration

Sometimes a developer needs a return value from the business rules policy for his code to execute a different piece of logic depending on the policy's results. Despite the fact that the BRE doesn't support return values, it still can "share" a common object with a calling orchestration. The shared object could be an XML document; in this case an orchestration simply passes through a message of that document type to be modified and returned by the Business Rule Engine. Or, it could be either a complex structure or a simple single value, for example, a Boolean value. In either case, it is not efficient to use an XML document—a BizTalk message—to pass those values back and forth; using an object instance of a .NET class would be the right approach. The following example of using a .NET class in a policy will illustrate how an object instance of a .NET class can be used to act as a return value from a policy. A policy will be executed and an action fired that sets a Boolean public property on a class.

You start off by writing a simple class that has a public Boolean property:
public class MyReturn
  private bool approved;
  public bool Approved
     get{ return approved; }
     set{ approved = value; }

After compiling this class into a .NET library and deploying its assembly to the GAC, reference that assembly from the Business Rule Composer and set the property of this class in an action to true or false, either by dragging the property from the .NET Class Facts Explorer or by creating and using a vocabulary definition. Your rule should look something like Figure 2.

Figure 2. Setting a Boolean value

Reference that assembly in the BizTalk project hosting the orchestration that will call the policy and create a variable of type MyReturn. Assign a reference of a new object instance of this class to the variable in an Expression shape and pass it as a parameter to the policy in the Call Rules shape as in Figure 3.

hlpr = new RulesHelper.Helper();

The orchestration can access the class's Boolean property in a Decision shape to find out what value it was set to in the Business Rule Engine.

hlpr.Approved == true

To test the policy from the Business Rule Composer, you can write a fact creator[] to cre-ate an object instance of the MyReturn class.

[] For a detailed description of how to create a fact creator implementing the IFactCreator interface, refer to the product documentation.

Figure 3. Call Rules shape
- BizTalk Server 2009 : Playing By The Rules? Use The Business Rule Engine - Going to Production
- BizTalk Server 2009 : Testing Business Rules
- Migrating to Configuration Manager 2007 : Migrating Hardware Inventory Customizations, Troubleshooting Upgrade Issues
- Migrating to Configuration Manager 2007 : Side-by-Side Migrations
- Microsoft Dynamic GP 2010 : System and Company Setup (part 7) - Company setup - Posting setup, E-mail setup
- Microsoft Dynamic GP 2010 : System and Company Setup (part 6) - Company setup - Shipping Methods, Credit Cards
- Microsoft Dynamic GP 2010 : System and Company Setup (part 5) - Company setup - Company setup, Fiscal Periods
- Microsoft Dynamic GP 2010 : System and Company Setup (part 4) - Company setup - Multicurrency, Taxes
- Microsoft Dynamic GP 2010 : System and Company Setup (part 3) - Company setup - Account setup
- Microsoft Dynamic GP 2010 : System and Company Setup (part 2)
Top 10
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Finding containers and lists in Visio (part 2) - Wireframes,Legends
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Finding containers and lists in Visio (part 1) - Swimlanes
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Formatting and sizing lists
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Adding shapes to lists
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Sizing containers
- Microsoft Access 2010 : Control Properties and Why to Use Them (part 3) - The Other Properties of a Control
- Microsoft Access 2010 : Control Properties and Why to Use Them (part 2) - The Data Properties of a Control
- Microsoft Access 2010 : Control Properties and Why to Use Them (part 1) - The Format Properties of a Control
- Microsoft Access 2010 : Form Properties and Why Should You Use Them - Working with the Properties Window
- Microsoft Visio 2013 : Using the Organization Chart Wizard with new data
programming4us programming4us
Popular tags
Video Tutorail Microsoft Access Microsoft Excel Microsoft OneNote Microsoft PowerPoint Microsoft Project Microsoft Visio Microsoft Word Active Directory Biztalk Exchange Server Microsoft LynC Server Microsoft Dynamic Sharepoint Sql Server Windows Server 2008 Windows Server 2012 Windows 7 Windows 8 Adobe Indesign Adobe Flash Professional Dreamweaver Adobe Illustrator Adobe After Effects Adobe Photoshop Adobe Fireworks Adobe Flash Catalyst Corel Painter X CorelDRAW X5 CorelDraw 10 QuarkXPress 8 windows Phone 7 windows Phone 8 BlackBerry Android Ipad Iphone iOS
Celebrity Style, Fashion Trends, Beauty and Makeup Tips.