Wonka Rules Engine : Introduction to Wonka Markup XML

The markup language for the Wonka rules engine is very basic and meant to be readable by most users.

General Structure

In general, Wonka rules are collected into a logical unit called a Ruleset, and Rulesets can be nested within one another, much like any conditional path for programming. Any entire collection of Rulesets, with one node as its root, is called a Ruletree.

Take the following example:

<?xml version="1.0"?>
<RuleTree xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

   <if description="Set the status for the incoming record">
      <criteria op="AND">
         <eval id="pop1">(N.BankAccountName) POPULATED</eval>
         <eval id="dom1">(N.BankAccountName) == ('JohnSmithFirstCheckingAccount')</eval>
      </criteria>

      <if description="Validating Account Type">
         <criteria op="AND">
            <eval id="pop3">(N.AccountType) POPULATED</eval>
            <eval id="dt1">(N.CreationDt) IS AFTER (06/09/1996)</eval>
         </criteria>

         <validate err="severe">
            <criteria op="AND">
               <eval id="dom4">(N.AccountType) IN ('Checking', 'Savings', 'Tax Haven in Cayman')</eval>
            </criteria>

            <failure_message/>
            <success_message/>
         </validate>
      </if>
   </if>        
</RuleTree>

The first <if> tag (with the description starting with "Set the status...") is the root node (i.e., root Ruleset) of the Ruletree. The <criteria> tag acts as the container for the rules of a Ruleset, and their collective evaluation (applying either AND/OR to the rules) will determine if we will follow the path deeper into this branch. (Each rule within the <criteria> composite is represented by an <eval> tag.) A <if> tag is a Ruleset that acts like a branch node, while a <validate> tag indicates a Ruleset acting as a leaf node.

In addition, a <validate> Ruleset also potentially carries additional responsibility. When a Ruletree is invoked, its execution can be evaluated on a whole as a success or failure. This type of functionality exists for users who might want to know simply if something truly consequential has happened which isn't favorable. In the event of a failure with a <validate> Ruleset, where "err" is set to "severe" (instead of the default "warning" value), the failure of that Ruleset can result in the Ruletree's execution as being evaluated with the status of failure.

Rule Operators

These are the codes that indicate the operation of a single rule (i.e., ). The grammar of a rule resembles the following:

<eval id="shorthand_name_of_rule1">(DataSourceId.AttributeName) OPERATOR ('LiteralVal')</eval>

<eval id="shorthand_name_of_rule2">(DataSourceId.AttributeName) OPERATOR (DataSource.OtherAttributeName)</eval>

<eval id="shorthand_name_of_rule3">(DataSourceId.AttributeName) OPERATOR ('LiteralVal', DataSourceId.OtherAttributeName)</eval>

Where the LHV (i.e., left-hand value) of a rule is always an AttributeName and the RHV (i.e., right-hand value) of the rule can be a literal value, an Attribute, or a set of values that can be combination of literal values and Attributes.

The value represented by DataSourceId.AttributeName is the primary focus of the rule. The DataSourceId represents a data provider (i.e., a C# delegate, a table, a Solidity contract, etc.) and the AttributeName represents a particular data point that can be given by the data provider. Both Sources and Attributes are defined with the data domain, which should be instantiated before the Wonka rules engine is instantiated with the rules (i.e., markup XML).

Below is a list of available operators that are ready to use:

• POPULATED --> Detects whether the data point is populated.
• != --> Indicates whether the data point does not equal the string value of the RHV.
• == --> Indicates whether the data point does equal the string value of the RHV.
• IN --> Indicates whether the data point is found within the set of values in the RHV.
• GT --> Indicates whether the LHV numeric value is greater than the RHV numeric value.
• LT --> Indicates whether the LHV numeric value is less than the RHV numeric value.
• GE --> Indicates whether the LHV numeric value is greater than or equal to the RHV numeric value.
• LE --> Indicates whether the LHV numeric value is less than or equal to the RHV numeric value.
• EQ --> Indicates whether the LHV numeric value is equal to the RHV numeric value.
• IS BEFORE --> Indicates whether the LHV date value is less than the RHV date value.
• IS AFTER --> Indicates whether the LHV date value is greater than the RHV date value.
• IS AROUND --> Indicates whether the LHV date value is 24 hours before or 24 hours after the RHV date value.
• IS ALMOST --> Indicates whether the LHV date value is within 24 hours before the RHV date value.
• ASSIGN --> Assigns the LHV to the value of the RHV.
• ASSIGN_SUM --> Assigns the LHV to the sum of the values in the RHV, which should be a set of numeric values.
• ASSIGN_DIFF --> Assigns the LHV to the arithmetic difference of the values in the RHV, which should be a set of numeric values.
• ASSIGN_PROD --> Assigns the LHV to the arithmetic product of the values in the RHV, which should be a set of numeric values.
• ASSIGN_QUOT --> Assigns the LHV to the arithmetic quotient of the values in the RHV, which should be a set of numeric values.

The "NOT" operator can be used in front of the following operations, to test the negation of the comparison: (POPULATED, IN, GT, LT, GE, LE, EQ). The "NOT" operator can be used in the date comparisons as well, but it should be placed in the middle for better legibility (i.e., IS NOT BEFORE).

These operators are not yet supported, but there are tentative plans to support them:

• EXISTS AS
• DEFAULT

Using the extensibility of the Wonka engine, one can also create their own custom operators, which are then attached to a C# delegate (or, in advanced cases, a method on a Solidity contract). Let's say that one defines a custom operator called 'DoSomethingSpecial', which then accepts a parameter list of 3 values. The usage of the operator would then result in a rule resembling the following:

<eval id="shorthand_name_of_rule4">(DataSourceId.AttributeName) DoSomethingSpecial ('LiteralVal1', DataSourceId.OtherAttributeName, 'LiteralVal2')</eval>