A rules engine for large business applications¶

• Table of contents
• A rules engine for large business applications
  • Background
  • What is a rule?
    • The pattern
    • The actions
  • Some refinements
    • A “class of entity” attribute
    • When many rules match
    • Rulesets
    • Conditional rules
    • RETURN and EXIT actions
    • Values of attributes
  • Rules engine as flow engine
  • Implementation
    • Representing the schema of patterns
    • Representing the schema of actions
    • Representing a pattern
    • Representing an action
    • An entire rule
    • The schema manager
    • The rule manager
    • The matching engine

Background¶

We need to have a business rules engine. All the good open source rules engines we are seeing seem to prefer putting the rules in code. This means that a change in rules will require a build and deploy to propagate. Therefore, these products are for a quasi-static rules context. We need to support a more dynamic rules scenario, plus we need to provide a GUI to edit rules. In this scenario, if we are to use the popular rules-as-code category of BRE, we will have to generate code from the admin GUI, and then build a new release with the new rules code. This can be done, but is messy. Elegant people like us don’t like messy. Unless it’s spelt Messi.

So we are faced with the prospect of having to design our own rules engine. This rules engine will have absolutely nothing specific to the current project.

What is a rule?¶

A rule has two “parts”

• A pattern specifying which entities the rule will apply to
• A what-to-do part, or action section, which specifies what we can do or not do with the matching entities

The pattern¶

The first part will have a pattern notation against which we will match entities. For example, these are patterns:

• Items in the inventory
• Textbooks in the inventory
• Textbooks more expensive than INR 2,000 in the inventory
• Textbooks in stock for longer than 30 days in the inventory
• Vendors who owe us more than INR 100,000
• Vendors who supplied us more than INR 5,000,000 worth of goods in the last financial year
• Vendors who owe us less than INR 50,000 AND who supplied more than INR 2,000,000 worth of goods to us this year
• Vendor with the ID “APZ00133”

The rules engine may allow us to define such patterns, so that we can decide which items the rule will apply on. The last example specifies an explicit vendor instance, by specifying (presumably) its unique ID. Therefore, some rules may be defined for just one object instance. In other words, that rule is not a rule – it’s a codified exception to the general rules.

One can extend the pattern to have a negation operation. The rule will then apply to all entities which do not match the pattern.

The actions¶

The second part of the rule is an action or a set of possible actions. Examples are:

• Discount equals 7% (for old stock items, or expensive items, or all items)
• Set credit limit to INR 200,000 (for vendors who owe us more than INR 100,000)
• Accept orders without a written PO (for vendors who have supplied goods more than INR 5,000,000 in the last year)
• Include in the Diwali Special Sale (for vendors who owe us less than INR 100,000)
• Accept orders without a written PO and include in the Christmas Sale (two actions in one rule – why not?)
• Use Fedex to ship out the item (for textbooks above a certain value)

Implementation challenges will be covered later. It’s just concepts at this point.

Some refinements¶

A “class of entity” attribute¶

A pattern has various attributes. In the items in the inventory examples, the following attributes were seen:

• Type of inventory item: e.g. textbook
• Price: e.g. INR 2,000
• Age of stock: e.g. 30 days

It becomes clear that attributes apply to a broad class of entities, but lose meaning across classes. Attributes which make sense to items in the inventory do not have any meaning when applied to vendors. Some attributes, like “full name”, or “date on which the entity was added to the system”, might apply to most items, but such attributes are very few. Therefore, it is perhaps necessary to define one fundamental attribute of each pattern: what broad class of entities does the pattern apply to? In database parlance, this is a mandatory non-NULL field, whose values will be from an enumerated set.

Another way to view this is to say that rules are partitioned into separate subsets or namespaces based on the value of this primary attribute. Rules which apply to one class do not have any overlap or engagement with rules which apply to another class. A rule can only apply to one class.

When many rules match¶

When many rules match an entity, there must be a way to get an unambiguous result. The designer who is managing the rules must know exactly which rules will match for which entity. For example, if we have the following two rules:

• All textbooks
• All textbooks with price higher than INR 3,000

then the order in which matching is attempted will decide whether a book costing more than INR 3,000 will match the first rule or the second. And once one rule matches, the matching engine will need to decide whether to continue matching or to exit the matching loop.

One typical solution to the many-match problem is to break out of the matching process on first match. We call this the FIRST-MATCHING-RULE algorithm. This allows for only very simple rulesets, because only one rule can possibly match an entity. Also, the ordering of rules in the rulebase becomes important in deciding which rule will match.

A second approach to resolve the ambiguity is to match the more specific rule, i.e. the pattern which carries the larger number of attributes -- MORE-SPECIFIC-RULE algorithm. For instance, in the two rules above, the first rule is more generic, because it matches all textbooks, while the second rule is more specific, because it matches only a subset of textbooks. If there was another rule with both price and weight attributes, that would apply to all matching entities.

What happens when there are two rules which match, each of whose patterns has three attributes? For example:

• All textbooks with price higher than INR 2,000
• All textbooks with quantity in stock greater than 20

If an entity matches all the attributes of both the patterns, which of the rules will apply? In such cases, different attributes may be assigned different weights to break the tie. For instance, price may be given higher weightage than quantity in stock. The pattern with the highest sum of attribute weights overrides the lighter pattern. This becomes complicated.

A third approach is to not choose which rules match, but match all the matching rules, and make a union set of all the actions from all the matching rules. This may be referred to as the MATCH-ALL algorithm.

We will follow the MATCH-ALL strategy till the end or till an EXIT action.

Rulesets¶

Rules may be grouped into named sets. An action of one rule in one ruleset may trigger the equivalent of a subroutine call to a different ruleset, so that the matching algorithm continues with the rules of the second set. When the second ruleset runs to its end, the matching process returns to the point just after the calling rule in the first ruleset.

The matching process will always begin with a main ruleset, and may just end at the end of this main ruleset in some cases. In some specific cases, an entity will match a rule in the main ruleset which will specify a CALL action, naming a second ruleset. In that case, the matching process will continue in the second ruleset immediately after completing the rule which had the CALL action. After the called ruleset completes, the matching continues with the rule just after the one which triggered the call.

If the analogy of subroutine call is to be continued, then it must be noted that these subroutine calls are without any local variables, and the action list accumulated till the point of the CALL are globally visible within the called subroutines.

Conditional rules¶

A rule may have an action which causes branching to one ruleset if the rule matches, and to another ruleset if it does not match. This is specified in the action section by having a THEN=ruleset1 term and an ELSE=ruleset2 term.

If such a rule is encountered, then

• if the pattern matches the entity, the matching engine will trigger a CALL to ruleset1.
• If the pattern does not match the entity, then the engine will trigger a CALL to ruleset2.

In both cases, after the CALL, the engine will return to the point just after the conditional rule and resume from there.

In the context of the conditional rule, there is a special ruleset name, CONTINUE, which is an empty ruleset with zero rules. If the ruleset CONTINUE is called, with, say, a CALL=CONTINUE, then it is the equivalent of a null statement, because a ruleset with zero rules does nothing. This feature is very useful for a THEN=CONTINUE or an ELSE=CONTINUE.

RETURN and EXIT actions¶

When the matching engine is traversing a ruleset other than main, and it matches a rule which has the RETURN action, the engine will immediately exit the ruleset and return to the calling ruleset. If the matching engine encounters the EXIT action, it will immediately exit from the entire matching process and return to the client which had triggered the matching operation.

When the matching engine is traversing the main ruleset, RETURN and EXIT are synonymous.

Values of attributes¶

The action of a rule may not just specify an action, it may set a value of an attribute. Thus the rules matching algorithm may not just specify what action is permitted, but may specify the value of a variable too. For instance, for items in inventory, possible actions, which are actually attribute-value settings, could be:

• shipby=fedex
• shipby=royalmail
• hsncode=9543

Rules engine as flow engine¶

It is possible to use a rules engine to specify flow, as in task flow or work flow. A task flow basically answers the following question: “I am entity X of class ABC, and I have just completed operation PQR. What next, for me?” For example, "I am vendor PAXX8423, and I have just completed the processing step of initial registration. What's the next step I need to execute?" Here, the class is "vendor", the entity is PAXX8423, and the operation PQR is "initial registration".

The basic question which a task flow or work flow answers at every step of a process is: what next for me?

To support this, special types of rules will need to be defined. These rules will have the following special features:

• The repository of flow rules will be separate from the business rules. There is no need for any overlap or mixing between the two sets, therefore they must be disjoint. However, the matching algorithm can be the same.
• Features like rule chaining, named rulesets, etc, may all be present, to allow for expressive power.

All business processes comprise a set of steps. This will reflect in the flow engine. All “flow” rulesets will have two special mandatory terms in their patterns:

• process: which will be one value from an enumerated set of values. Examples of processes could be:
  • Account creation
  • Asset liquidation
  • Identity verification
  • Any other multi-step business process
• step: which will be one value from an enumerated set of values. Examples of step could be (taking the example of account creation in a bank):
  • Initial personal details
  • Identity papers verification
  • Reference check
  • Initial amount deposit

These two attributes will be essential to tell the flow engine which process the entity is executing and what is the current step of the process which the entity has just completed, after which it is asking “what next for me”.

The flow engine will operate just like a rules engine, and will process rules in its repository, and will arrive at a set of actions to be performed as the next step. If a single action emerges from the rule matching algorithm, then that step will need to be performed. If multiple actions emerge, then all those actions may be performed in parallel, asynchronously.

If multiple actions emerge from the flow engine, in some cases a special action may be part of the result set: NEXTSTEP=xyz. When this appears, it indicates that the entity may execute all the listed actions asynchronously, but must wait for all these asynchronous actions to complete before querying the flow engine again. And when all the actions are complete, it must query the flow engine specifying xyz as the value of the step attribute. This is a facility to make the flow re-synchronise after breaking into asynchronous concurrent threads.

Implementation¶

A rules engine implementation must include the following:

• PATTERN SCHEMA. A notation to specify the list of valid attributes in the pattern of a rule. This list will be separate for each class of entities. For instance, for items in inventory, the list of attributes may be:

  • Price
  • Full name
  • Age in stock
  • Quantity in inventory

  For vendors, the list could include:

  • Amount outstanding
  • Total value of business done in the last financial year

• RULE NOTATION. A notation to specify the pattern and actions of a rule.

• THE MATCHING ENGINE. Something which will take an entity with all its attributes, apply each rule to it, and follow the trail of rules to come up with a list of actions which will emerge.

So, if these three can be designed and then implemented, the core of a rules engine or a flow engine can be built.

Representing the schema of patterns¶

If using JSON, the schema of all valid patterns may be represented in structures of this form:

“patternschema”: {
    “class”: “inventoryitems”,
    “attr”: [{
        “name”: “cat”,
        “type”: “enum”,
        “vals”: [ “textbook”, “notebook”, “stationery”, “refbooks” ]
    },{
        “name”: “mrp”,
        “type”: “float”
    },{
        “name”: “fullname”,
        “type”: “str”,
    },{
        “name”: “ageinstock”,
        “type”: “int”
    },{
        “name”: “inventoryqty”,
        “type”: “int”
    }]
}

In this example, the object patternschema is the schema for one category of entities. This schema says that for rules which work on entities of type inventoryitems, there are five attributes available which may be used to make patterns. Each attribute has a type. Enum types, integers, floating point numbers, dates and strings are supported. The example above does not have any attribute of type date.

So, the full schema of the rules engine will be an array of patternschema blocks. Initial examples have discussed inventory items and vendors. The patternschema block above is for inventory items. If the schema of patterns for vendors needed to be specified, there would be a second patternschema with “class”: “vendors”

Representing the schema of actions¶

The schema of the action section of rules is simpler than patterns. Each rule's action section will contain a set of zero or more words, each denoting an action, and zero or more attribute assignments. There is no need for any type specification, etc.

• An example of an action word: invitefordiwali
• An example of an attribute assignment: discount=7

So, the schema of the actions will just specify the valid action names and the attribute names for assignments.

“actionschema”: {
    “class”: “inventoryitems”,
    “actions”: [ “invitefordiwali”, “allowretailsale”, “assigntotrash” ],
    “attribs”: [ “discount”, “shipby” ],
    “tags”: [ “specialvendor”, “tryoverseas” ]
}

The schema of actions above indicates that there are three actions, any or all of which may be present in any rule for this class of entities. There are two attributes which may be assigned values by any rule. And there are two tags for this class of entities – if a rule wishes to tag an entity with one or both of these tags, it may do so.

Putting the patternschema and actionschema blocks together, a better representation for the full schema for a class of entities will be:

"ruleschema": {
    “class”: “inventoryitems”,
    “patternschema”: {
        “attr”: [{
            “name”: “cat”,
            “type”: “enum”,
            “vals”: [ “textbook”, “notebook”, “stationery”, “refbooks” ]
        },{
            “name”: “mrp”,
            “type”: “float”
        },{
            “name”: “fullname”,
            “type”: “str”,
        },{
            “name”: “ageinstock”,
            “type”: “int”
        },{
            “name”: “inventoryqty”,
            “type”: “int”
        }]
    }
    “actionschema”: {
        “actions”: [ “invitefordiwali”, “allowretailsale”, “assigntotrash” ],
        “attribs”: [ “discount”, “shipby” ],
        “tags”: [ “specialvendor”, “tryoverseas” ]
    }
}

There will need to be one such ruleschema block for each class.

Representing a pattern¶

“rulepattern”: {
    “pattern”: [{
        “attr”: “cat”,
        “op”: “eq”,
        “val”: “textbook”
    },{
        “attr”: “mrp”,
        “op”: “ge”,
        “val”: 2000
    },{
        “attr”: “ageinstock”,
        “op”: “ge”,
        “val”: 90
    }]
}

If a rule has this pattern, it will match any entity which falls in the class inventoryitems which

• is of type textbook
• has MRP (max retail price) greater than INR 2000
• has been in stock longer than 90 days

For attributes which are of type int or float, the following operators are available for matching:

• Greater than or equal to: ge
• Greater than: gt
• Less than or equal to: le
• Less than: lt
• Equal to: eq
• Not equal to: ne

For other types, only eq and ne are available.

Representing an action¶

A rule just has a set of one or more actions. The following are all examples of the action section of rules:

• invitefordiwali
• discount=7
• shipwithoutpo
• BTAG=”specialvendor”
• CALL=”intlbiz”

The words which identify actions will automatically be converted to lower-case and stored in the system. For an attribute assignment, the value of the attribute will be everything after the first = character till the end of the string, thus supporting multi-word values, e.g.

• reprimand=This cannot go on any longer

An entire rule¶

This is what an entire rule looks like:

“rule”: {
    “class”: “inventoryitems”,
    “ver”: 4,
    “rulepattern”: {
        “pattern”: [{
            “attr”: “cat”,
            “op”: “eq”,
            “val”: “textbook”
        },{
            “attr”: “mrp”,
            “op”: “ge”,
            “val”: 5000
        }]
    },
    “ruleactions”: [
        “christmassale",
        “shipby=fedex”
    ]
}

This structure represents one rule. The rule applies to entities of class inventoryitems. It has a pattern section which tries to match two attributes and an action section which throws up one action and one assignment.

An array of such structures is a set of rules, and will be traversed in the order in which the rules appear in the array. Named rulesets will be represented thus:

"ruleset": {
    "class": "inventoryitems",
    "setname": "overseaspo",
    "rules": [{
        "ver": 4,
        "rulepattern": {
            :
            :
        },
        "ruleactions": {
            :
            :
        }
    }, {
        "ver": 3,
        "rulepattern": {
            :
            :
        },
        "ruleactions": {
            :
            :
        }
    }]
}

The example above shows a ruleset named inventorypo for class inventoryitems which has two rules. This ruleset may be invoked from any other rule with the action CALL=inventorypo.

The schema manager¶

The schema for each class of entities may be written by hand using a text editor. JSON or YAML files are easy to write. It is unlikely that the schema of one class will have more than a dozen attributes, which makes the schema short enough to edit or audit by hand. However, a tool to manage and maintain the schema eliminates typos and enforces various types of consistency, and a second-level implementation of a schema manager may also enforce authorisation policies.

A schema manager will have the following features:

• It will allow the user to create new instances of ruleschema
• It will sharply restrict editing of, and prevent deletion of any patternschema block or actionschema block if there are rules defined in the rules engine for this class of entities. In other words, schema are editable only as long as there are no rules for the class. The only kind of editing it will permit for “live” schema are
  • the addition of additional attributes in a patternschema or
  • additional attributes, action names or tags in an actionschema.
• It will ensure that there is no scope for typos when defining the schema.

The rule manager¶

The rule manager will allow a user to manage rules. Core functionality:

• It will provide a user interface to let the user edit rules.
• It will check each rule against the schema for the class, and will not give the user the opportunity to define any rule inconsistent with the schema.
• It will allow the user to move a rule up or down in the sequence.
• If a rule is being defined with a CALL action, then the rule manager will ensure that a ruleset with that target name exists.
• Most important: it will provide a testing facility by which sample entities may be submitted to the rule engine for testing, and the rule manager will display a full trace showing which rules were attempted to match, which rules actually matched, and how the result set of actions, attributes, etc grew with each step. This feature will be provided without having to save the rule changes.
• Finally, when the editing session is complete and all rulesets need to be saved, it will perform a detailed cross-validation of all rules across each other to ensure consistency. If there is any inconsistency, it will give a very readable explanation of the problem(s) and not permit saving of the updates.

The matching engine¶

The matching engine has a one-line job. It will take a full set of attributes of one entity, apply all the rules which apply to its class, and return with the list of actions, attributes, etc from all the matching rules.

The matching engine must support the following set of operations:

• doMatch(): take an entity, pass it through all relevant rules and rulesets, and respond with the set of final results.
• getAttrSet(): take a class name, pull out from the patternschema all the attributes listed against that class, with full details. This is useful to let the caller know what attributes are to be specified when calling doMatch().