5. Understanding Rules

Introduction

This document continues from 4. Simplifying Payments tutorial. Please complete it before starting this tutorial.

PM-POS Rule

In this tutorial I'll give more information about PM-POS rules. To operate PM-POS features such as Creating Cards or Tagging Cards we need to execute actions. Rule engine monitors executed actions and evaluates rule constraints to trigger related rules. When a rule constraint matches it executes additional actions. That triggers rules again until no more rule constraint matches to current conditions.

Language

PM-POS rules implemented with nools-ts. nools-ts is a typescript implementation of Drools langauge.

Rule Structure

rule RuleName {
    when {
       // When this happens
    }
    then {
       // do this
    }
}

A rule contains two parts. when section contains the variable definitions and constraints. then section contains rule execution code. It generally contains actions to execute.

Rule Constraints

The constraint section of the rule useful to test the currently executed actions and capture variables we want to use.

We need to define at least 2 variables on constraint section.

• r:Result: We'll use result to add actions we need to execute.
• s:State: Gives access to current state of the application.

Here are some useful State Properties & Functions.

• s.action: Last executed action.
• s.card: Card the action executed for.
• s.root: Root card of the card.
• s.state: Global key value list. Useful to pass values between rules.
• s.load('type','name'): function to load a card by name.

This example rule executes SELECT_CARD action when Select Table command executes.

rule SelectTable{
  when {
    r: Result;
    s: State;
    a: Action a.type == 'EXECUTE_COMMAND' && a.data.name == 'Select Table' from s.action;
  }
  then {
    r.add('SELECT_CARD',{type:'Table', selected:s.card.getTagValue('Table')});
  }
}

You'll notice constraint section contains a third variable called a. We'll use it to test if last executed action is a Select Table Command or not.

a: Action a.type == 'EXECUTE_COMMAND' && a.data.name == 'Select Table' from s.action;

This line contains 3 parts.

• a: Action: Variable type definition.
• a.type == 'EXECUTE_COMMAND' && a.data.name == 'Select Table': Constraint expression.
• from s.action: Variable value. It is taken from s variable's action parameter.

A variable definition may contain a constraint expression or not. All variable expressions should be true in order to Rule to execute.

Executing Actions

Rules generally executes one or more actions. To be able to define which actions we want to execute we'll add them to Result object by using r.add() method.

Syntax:

r.add('COMMAND_NAME',{Command Parameter Object});

Example:

r.add('SELECT_CARD',{type:'Table', selected:s.card.getTagValue('Table')});

Select Card action needs a type and selected card value. On this example card type is Table and currently selected value read by s.card.getTagValue('Table') function. s.card is the card action executed for. getTagValue('Table') is a card function to read a value of a tag. We're reading value of Table tag on this example.

You can execute multiple actions by adding more actions by using r.Add() method.

Current Actions

Action	Type	Parameters
CREATE_CARD	mutation	type
SET_CARD_TAG	mutation	name,value,quantity,unit,amount,rate,source,target
CLOSE_CARD	mutation	id
SELECT_CARD	ui	type,selected
ASK_QUESTION	ui	question,parameters
SET_STATE	mutation	name,value

• mutation actions makes a change on current state of the application.
• ui actions displays a dialog to user and updates app state with the user inputs.