Grule Rule Engine

When working with JSON facts in Grule, keep the following behaviors in mind:

• Decoupled Data: Modifying a JSON fact within the DataContext does not modify the original JSON byte array/string used to create it. Similarly, changes to the original JSON string after it has been added will not affect the facts already in the DataContext.
• Persistence: If you need modifications made in the then clause to persist back to your original data source, you should parse the JSON into a Go struct first and add that struct to the DataContext instead of using AddJSON.
• Missing Array Helpers: There is currently no built-in function to easily check array contents, such as a Contains(value) method.

When creating custom functions to be called from GRL, you must adhere to these three laws:

1. Visibility: Functions must be exported (start with a capital letter). Private functions cannot be executed by the engine.
2. Single Return Value: Functions must return exactly one value type. Returning multiple values is not supported and will cause rule execution to fail.
3. Numeric Types: Grule treats number literals specifically:
   • Integers are always treated as int64.
   • Reals are always treated as float64. You must define your Go function signatures to match these types exactly.

Grule operates on a model where a KnowledgeBase contains sets of rules that are evaluated against Facts.

• Fact: The basic information or collected data used as the basis for evaluation. Facts can come from various sources like databases, trigger processes, or sales systems. For example, a Purchase Transaction fact might contain Item Name, Quantity, and Price.
• Rule: A specification of how to evaluate a Fact. A rule consists of a condition (IF) and an action (THEN). If the condition is met by the Fact, the action is executed.
• Knowledge: A collection of rules that together represent a specific domain of logic (e.g., a set of rules for "calculating the final price of an item").

GRL allows calling functions that are visible and return zero or one value.

Key Features:

• Direct Calls: Fact.FunctionA() == "text"
• Method Chaining (v1.6.0+): You can chain calls and field access, e.g., Fact.Function().StringField or Fact.Function("arg").ObjField.OtherFunction().
• Constant Method Calls (v1.6.0+): You can call methods directly on literal constants, e.g., "AString ".Trim().ToUpper().

Example:

when
    "AString   ".Trim().ToUpper().HasSuffix("ING")
then
    Fact.Result = Fact.ReturnStringFunc().Trim().ToLower();

Since version 1.6.0, GRL supports accessing and assigning values to arrays, slices, and maps within facts.

Accessing: You can use standard index or key notation. Warning: If an array index is out of bounds, the rule execution will cause a panic.

Assigning: You can assign values to valid indices or keys.

// Accessing
Fact.AnIntArray[1] == 12
Fact.SubMaps["Key"].AnIntArray[0] == 1000

// Assigning
Fact.AnIntArray[10] = 12;
Fact.SubMap["AKey"].AStringArray[1] = "New Value";

// Example of complex access in a 'when' block
when 
   Fact.AnIntArray[1] == 12 &&
   Fact.AStringArray[12] != "SomeText" &&
   Fact.SubFacts[1].SubFacts[2].AnIntArray[12] > 100 &&
   Fact.SubMaps["Key"].AnIntArray[0] == 1000
then
   ...

A Decision Table in Grule is defined by a metamodel that describes the structure of the table, including its items (columns) and decision rows. Each item in the table must define its role, data type, and constraints.

Key metamodel components for each item include:

• name: The identifier for the information item.
• function: Specifies if the item is an input (used for matching conditions) or an output (the result of a rule hit).
• type: The data type (e.g., int, string, bool, float).
• label: A human-readable description.
• allowed_values: Constraints on what values the item can hold (e.g., specific sets or numeric ranges).
• default_value: The value used if no specific value is provided.

When using JSON facts in Grule, be aware of the following data flow limitations:

1. One-way initialization: Once a JSON byte array is added to the DataContext, changes to the original byte array will not affect the facts in the engine.
2. No back-propagation: Changes made to a JSON fact within the GRL then scope will not reflect back to your original JSON string/byte array.

Recommendation: If you need changes made by the rule engine to persist back to your original data structure, parse your JSON into a Go struct first and add that struct to the DataContext using the standard Add() method instead of AddJSON().

The then block contains an array of operations. Similar to condition objects, each operation's root element must be either a set or a call operator.

• Use set to assign values: {"set": [target, value]}.
• Use call to invoke functions: {"call": ["FunctionName", arguments]}.

A rule in Grule is a fragment of knowledge expressed as a "When-Then" structure. It consists of a name, an optional description, an optional salience (priority), a when block containing conditions, and a then block containing actions.

Basic syntax structure:

rule <rule_name> <rule_description>
   <attribute> <value> {
   when
      <conditions>
   then
      <actions>
}

rule SpeedUp "When testcar is speeding up we increase the speed." salience 10  {
    when
        TestCar.SpeedUp == true && TestCar.Speed < TestCar.MaxSpeed
    then
        TestCar.Speed = TestCar.Speed + TestCar.SpeedIncrement;
        DistanceRecord.TotalDistance = DistanceRecord.TotalDistance + TestCar.Speed;
}