oeCloud Business Rules Engine

oeCloud business rule engine is a framework to write pre-defined and custom rules for business validations and decision making. oeCloud business rule engine is developed based on DMN (Decision Model and Notation v 1.1) specification and use FEEL (Friendly Enough Expression Language) to write expressions for rules.

What you’ll build

  • Business rules using excel.
  • Upload business rules using DecisionTable model.
  • Execute business rules using DecisionTable model.

What You’ll need

  • You should know js-feel.
  • You should know DMN 1.1.
  • You should have an idea about DecisionTable model.

Please Note

The usage of business rule engine mentioned in this guide is HIGHLY EXPERIMENTAL and may change in the future. Some of the APIs elaborated in this guides will be available for backward compatibility but the usage of which will be highly discouraged when better alternatives (work in progress) are made available. The current implementation makes use of business rules defined in excel(.xlsx) format. The future implementations will encourage users to use a Rule Designer(work in progress) to create and publish rules. The usage of excel formatted business rules will be highly discouraged in the future releases.

How to complete this guide

You can start from scratch and complete each step, or you can bypass basic setup steps if you are already familiar with it.

To start from the scratch go to Getting Started

Building Rules using excel and js-feel

The rules are built following a specific convention in an excel sheet. To understand different aspects of the convention, let’s analyze the attached excel sheet Holidays.xlsx.

Holidays

  1. Title of the decision table. This is used internally in the execution and caching of the decision table.
  2. Rule Table annotation acts as a cue to the parser to identify the xlsx formatted text as a Decision Table.
  3. Condition annonation marks the column as an input condition.
  4. Action annotation marks the column as an output action.
  5. Hit Policy - Please refer to Hit policy wiki
  6. Row index is marked by an ever increasing integer to denote a rule number.
  7. Input condition Rule written in FEEL. Please refer to js-feel.
  8. Output action Rule written in FEEL. Please refer to js-feel.

Each rule in the decision table is matched using a matching algorithm, information on which can be found in [Decision Table wiki] (https://github.com/EdgeVerve/feel/wiki/Decision-Table). Based on the matched rule/s and the hit policy output action/s can be determined.

Upload Rules using DecisionTable model

Let’s start with the Decision Table model. Decision Table model is a framework model which can be used to upload and execute business rules in excel(.xlsx) format.

Let’s take a look at the model definition,

{
  "name": "DecisionTable",
  "base": "BaseEntity",
  "description": "This model is used to business rule",
  "options": {
    "validateUpsert": true,
    "isFrameworkModel": true
  },
  "properties": {
    "name": {
      "type": "String",
      "required": true,
      "unique": true
    },
    "decisionRules": {
      "type": "String",
      "hidden": true
    }
  },
  "evValidations": [],
  "validations": [],
  "relations": {
    "document": {
      "type": "belongsTo",
      "model": "DocumentData",
      "foreignKey": ""
    }
  },
  "cacheable": true,
  "acls": [],
  "methods": {}
}

As we observe from the schema, the above model contains;

  • Properties
    • name : Name of the decision table
    • decisionRules :
      • Collection of the parsed decision rules as found in the decision table(uploaded as excel).
      • This field should not be handled in the application POST requests.
      • This is handled by the framework after excel document has been parsed by js-feel :)
  • Relation
    • document: Relation to the DocumentData model. The excel document saved in this model.

Sample POST

{
    "name": "Holidays",
    "document": {
        "documentName": "Holidays.xlsx",
        "documentData": "the base64 encoded data goes here. Described further in the text"
    }
}

In above JSON data, field documentData of property document should contain the base64 encoded data for the corresponding excel to be uploaded(here in the above example the excel file is Holidays.xlsx). Field documentName contains the excel file’s name to be uploaded and property name can contain any name to identify the uploaded file.

For this example, to encode excel(.xlsx) to base64encoded string base64encoder has been used. Feel free to use any encoder of your choice.

Please note that the encoding will be taken care of in the UI (using oe-studio) as we will see in the further guides.

Execute Rules

DecisionTable model exposes a REST API named exec i.e. /api/DecisionTables/exec/{documentName}.

This API takes two parameters,

  • documentName : Name of the document, which in our case is Holidays
  • data : Sample payload on which business rules will be applied.

Let’s execute the decision table with the below sample data,

{
 "Age" : 50,
 "Years of Service": 28
}

DecisionTable exec

The /api/DecisionTables/exec/{documentName} is a generic API and can be used in any flow. Some of the popular use cases include,

  • remote or operation hooks - (e.g. with Node Red),
  • with workflow - (e.g. with oeCloud workflow engine).