Kynetx Rule Language (KRL) Documentation

From KynetxDocs

The concepts and terminology explained in the KNS_Lexicon are essential to understanding KRL.

Contents 1 Rulesets 2 Rules 3 Language Components 4 Sample Rules 5 Execution Model 5.1 Initialization 5.2 Evaluation 5.3 Callback

Rulesets

A KRL program consists of one or more rulesets that comprise multiple rules. In addition to rules, rulesets contain

• Name - any alphanumeric name is OK syntactically, but the name should match the ruleset ID you've been assigned. Intersekt ensures this is the case.
• Meta Block - information about the ruleset.
  • description - A textual string that is returned when the describe method in the API is called.
• Dispatch Block - dispatches to other rulesets based on criteria like the domain of the calling page.
• Globals Block - definitions (usually emits) that will be available for all rules

Rules

• Rules
  • Declarations
  • Predicates
  • Actions
  • Callbacks
  • Counters
  • Expressions

Language Components

• Emit
• Page Variables
• Literals

Sample Rules

• Sample Rules

Execution Model

KRL is executed by the KNS service calls to the Kynetx Rules Engine (KRE). The execution is typically initiated by the Kynetx Browser Extension (KBX). The following diagram shows the KNS operations lifecycle and the interplay between KBX and KRE:

KBX has three distinct lifecycle phases:

• Preparation - when it starts or is refreshed, KBX makes an API call to the selector to determine the RIDs of any installed cards and then uses that data to call KNS and determine on which domains those RIDs are applicable, called the dispatch list.

• Wait - KBX exists in a wait state until the browser loads a page with a domain that matches a domain on the dispatch list. When that happens it initiates KRE execution as described below. When the execution is completed, KBX returns to a wait state.

• Finalize - when the browser is closed, KBX completes any clean up tasks and ends.

There are three stages in KRL execution by KRE:

• Initialization
• Evaluation
• Callback

These are described in detail below

Initialization

Initialization configures and initiates the the call.

Configuration is performed by adding a script tag to the page that defines the KOBJ_config object like so:

<script type="text/javascript">
var KOBJ_config ={
   "rids"  : ["kntx_rulealert","kntx_rulealert_2"],
   "init"  : {"eval_host" : "cs.kobj.net","callback_host":"log.kobj.net"},
   "key_1" : "value_1",
   "key_2" : "value_2"
};
</script>

The config object must contain an array names "rids" that contains the RIDs of rulesets applicable to this page. The config object can also contain an optional object named "init" that can override the URLs of the eval and callback host. The "init" object will not be included under most circumstances.

The other components of the config object are parameters that will be passed to the ruleset when it is evaluates. These can be read and tested using the page:env function in KRL (without the namespace designation). Parameter names should be namespaced by prepending RID with a colon (:) separator like so:

var KOBJ_config ={
   "rids"  : ["ruleset_1","ruleset_2"],
   "ruleset_1:ex_param" : "3",
   "ruleset_2:ex_param" : "5",
};

Parameters that aren't namespaced will be treated as global and will be seen in all rulesets identified in the "rids" array.

After the config object as been added to the page, the evaluation is initiated by adding this tag to the page:

<script type="text/javascript" src="http://init.kobj.net/js/shared/kobj-static.js"/>

Evaluation

The initialization process will add tags to the page that cause ruleset evaluation to commence. The process results in a custom Javascript program being returned to the browser that will run on the current page.

Callback

Some rules set events that call back to the server for analytics purposes.