Remiges Products » Crux: BRE/WFE

# Designing a rules engine for large business applications

{{>toc}}

## 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 of 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.

### If-then

The expressive power of rules will increase if one can specify some rules which will apply only to those entities which match some previous rule. So, Rule A, in addition to specifying actions, will also specify a tag, *e.g*. **“specialvendor”** (for vendors) or **“oldstock”** (for inventory items). Any entity which matches Rule A will be tagged by the tag. Then, there could be other rules B or C which will match only entities which have the **oldstock** tag.

Once an entity is tagged, it will only match rules which have that tag; it will no longer match any rule which does not have that tag.

This facility, of rules chaining, allows for more complex rules to be written more easily. For instance, one can define five different patterns by which one will select special vendors. This means that any vendor which matches any of the five criteria will be tagged **specialvendor**. Then later, other rules will specify the actions which can apply to special vendors. Entities which do not get the **specialvendor** tag will “fall through” to the rules which apply to the rest of the entities.

This chaining facility implements branching in the flow control, somewhat similar to a case statement in C or Go.

### When many rules match

When many rules match an entity, there must be a way to break out of the matching loop. The typical solution is to break on first match.

If this is done, then the ordering of rules becomes important. If we have 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.

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. 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, each of whose patterns has three attributes? 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. The pattern with the highest sum of attribute weights overrides the lighter pattern.

So, a rules engine must decide whether to implement the first-matching-rule algorithm or the more-specific-rule algorithm.

A third approach is to not choose which rules match, but make a union set of all the actions of all the matching rules.

We will follow the strategy of running through the rules 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.

### 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 optional 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 there is an **ELSE** term and 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.

### **`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 attributes:

* `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:

``` json

“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.

``` json

“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:

``` json

"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

``` json

“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:

``` json

“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()`.