The rsm (Ruleset Manager) module provides utilities for registering, validating, and managing KRL rulesets
The repository management structure uses the URI protocol to define from whence the KRE loads the ruleset source code. Currently, the following URI types have implementations in RSM
- HTTP/S
- XDI
- FILE
HTTP/S actually addresses most of the cloud storage solutions,but is limited to Basic Authorization or what can be implemented through headers. FILE is essentially only useful to the operators of a KRE instance (access to local disk storage and configuration), but it is conceivable that it could be used to provide the basis for a custom repository. XDI is still experimental as the specification is still under development
RIDS
RID is shorthand for Ruleset ID. This is a string unique to a KRE instance that identifies a specific ruleset. Rulesets need to be registered on a KRE instance with a URI and any other connection details so the ruleset's KRL can be parsed (collectively called rid info). The RID has historically followed the format of b<developer id>x<N>. The new system will allow the developer to optionally specify an alternate ruleset prefix (other than 'a' or 'b') <prefix><developer id>x<N>. RIDs provide a more compact and flexible id than the URI (Change source hosting service without forcing users to update subscription information).
Versions
Rulesets can have versions. The versioning is freeform and is appended as an extension to the RID. So a RID like b16x29
could have multiple version such as b16x29.prod
, b16x29.dev
, b16x29.imadethisup
and so on. The versions prod
and dev
are treated specially by the system.
History
The rsm (RuleSet Manager) module replaces the ruleset functionality provided by AppBuilder. Historically, the ruleset repository for a KRE has been provided by a proprietary system managed by Kynetx. One of the benefits of providing this service was maintaining a versioning system on the developer's behalf. By allowing external repositories, the developer can utilize external services like GitHub which provide a richer set of versioning and source code control.
Authentication
In order for the functions in this module to work, your ruleset my load system keys.
key system_credentials { "root": "<system key here>" }
You should take care in doing so to ensure that the keys are not checked into a public repository and are accessible via a URL that requires authorization. The best way to do this is to import the keys from a module.
RSM Functions
Ruleset utilities: Persistent variables provide a powerful method of maintaining a user environment across sessions, but by that nature, it is hard to predict whether a particular persistent variable has been initialized other than by making a reference and checking to see if the value is undefined. These two methods return a map of keys defined in the appropriate persistent namespace. As a convenience, the map is structured <Variable Name> : <Data Type>. To simplify the results to a simple list of names, use the .keys() operator return a list of the key names as an array.
entity_keys
entkeys() - return of map of defined variables and corresponding data types for the current entity
justKeys = rsm:entity_keys().keys();
app_keys
appkeys() -returnof map of defined variables and corresponding data types for the current ruleset
kvMap = rsm:app_keys();
new_ruleset
Avoid using this. Preferredmethod is to use the register
action below.
new_ruleset(<prefix>) - create an empty ruleset entry and return a unique ruleset_id
Parameter | Datatype | Required |
---|---|---|
<prefix> | <string> |
Default prefix is 'a'. Supplying a new prefix will reset the counter <n>. Optional flow to producea RIDas a predicate
ruleset_id = rsm:new_ruleset(); // returns a500102x12 a<NID>x<n> ruleset_id = rsm:new_ruleset("myPrefix"); // returns myPrefix500102x0
list_rulesets
list_rulesets() - return an array of RIDs that are marked as belonging to the owner ECI
ridList = rsm:list_rulesets(<eci>)
get_ruleset
get_ruleset(<rid>) - returns the configured information for a ruleset.
Parameter | Datatype | Required |
---|---|---|
<rid> | <string> | √ |
Format for <rid> is <ruleset_name>.<version>
ruleset = rsm:get_ruleset("myPrefix500102x0.prod");
is_owner
is_owner() - return 0|1 if the ECI represents the
ruleset_owner = rsm:is_owner(<eci>,<rid>)
RSM Actions
A note on setting and autoraise
Certain 'actions' generate information that is useful or needful for a program execution (http:postis a typical example). There is no specific method for returning a value from an action block, so there are two special keywords to facilitate this.
setting (<var name>) allows the developer toasign the value returned by an 'action' to a variable that is available in the postlude
http: post("http://someuri/") setting (resp)
..
fired {
raise explicit event http_post with return_value = resp;
}
autoraise= "post_value" This statement in the action modifiers will raise an event (Domain andeventnameare defined by the action internals)
http: post("http://someuri/")
with autoraise = "posted_value";
..
rule catch_event {
select when http post label "posted_value"
..
}
register()
register(<URI>) setting (ridName) - create a new registry/rid_info object with a link to the URI where the KRL source code is stored
Parameter | Datatype | Required |
---|---|---|
<URI> | <string> | √ |
The register action takes the following optional parameters:
Modifier | Datatype | |
---|---|---|
description | <string> | Optional description field for ruleset |
dev_uri | <string> | Optional URI for the dev version of the ruleset. |
prefix | <string> | Optional string to be included at the start of the rid. Defaults to "b" |
flush_code | <string> | Optional code to allow other developers to force the ruleset to reload and to update the rid_info |
header | <hash> | Hash/Map to allow for headers (extra authentication) required by potential repositories |
version | <string> | Optional parameter to support the legacy Kynetx repository. Defaults to "prod" |
username | <string> | Optional parameter to support HTTP basic authentication |
password | <string> | Optional parameter to support HTTP basic authentication |
The RID will have the following format <prefix><userid>x<index>. <prefix> defaults to 'b', <userid> is the account serial number, and <index> is a serial number for rulesets registers in this account.
Two versions will be created:
- <prefix><userid>x<index>.<version> - points to <URI>
- <prefix><userid>x<index>.dev - points to <dev_uri> if defined, otherwise points to <URI>
These versions can be updated separately. Other versions can be created using the fork() action.
There are also special modifiers that can be used with the action:
Special Modifiers | ||
---|---|---|
autoraise | <string> | label for rsm:register event |
target | <rid> | optional ruleset id target for the raised event |
Examples
rsm:register("https://raw.github.com/kre/Kinetic-Rules-Engine/master/t/data/action0.krl") setting(myRid) with description = "Read watchband settings" and flush_code = "4111" and headers = { "Accept" : "text/plain", "Cache-Control" : "no-cache" };
rsm:register("https://raw.github.com/kre/Kinetic-Rules-Engine/master/t/action0.krl") with autoraise = "app_registered";
flush()
flush(<rid>) - Force the KRE to reload and compile the ruleset <rid>
Parameter | Datatype | Required |
---|---|---|
<rid> | <string> | √ |
Modifier | Datatype | |
---|---|---|
flush_code | <string> | Code to allow non-owners to force a KRE re-evaluation of the <rid> |
rsm:flush("watchband500293x0"); rsm:flush("watchband500293x0") with flush_code = "4111";
validate()
validate(<rid>) - validate the source indicated by <rid> by passing it through the parser
Parameter | Datatype | Required |
---|---|---|
<rid> | <string> | √ |
Special Modifiers | ||
---|---|---|
autoraise | <string> | label for rsm:register event |
target | <rid> | optional ruleset id target for the raised event |
rsm:validate("watchband500293x0") setting(myValid)
rsm:validate("watchband500293x0") with autoraise = "app_validated" and target = "otherApp500293x43";
update()
update(<rid>) setting (ridName) - Edit an existing registry/rid_info object and execute the validate and flush operations on the <rid> with the new rid_info. If the <rid> fails to validate, a flush is NOT performed
Parameter | Datatype | Required |
---|---|---|
<rid> | <string> | √ |
Modifier | Datatype | |
---|---|---|
uri | <URI> | Point the <rid> to a new URI |
descriptions | <string> | Optional description for the ruleset |
flush_code | <string> | Required for non-owner developers to modify <rid> information |
header | <hash> | Replaces the entire header info of <rid> with the new hash/map |
version | <string> | Optional parameter to support the legacy Kynetx repository (defaults to "prod") |
username | <string> | Optional parameter to support HTTP basic authentication |
password | <string> | Optional parameter to support HTTP basic authentication |
Special Modifiers | ||
---|---|---|
autoraise | <string> | label for rsm:register event |
target | <rid> | optional ruleset id target for the raised event |
rsm:update("watchband500293x0") setting(myResults) with description = "Read watchband settings" and flush_code = "4111" and headers = { "Accept" : "text/plain", "Cache-Control" : "no-cache" };
rsm:update("watchband500293x0") with autoraise = "source_code_modified";
rsm:update("watchband500293x0") setting(myResults) with uri = "https://raw.github.com/kre/Kinetic-Rules-Engine/master/t/data/fails/fail0.krlb";
fork()
fork(<rid>) setting (ridName) - Create a new branch of <rid>. Though normally modifiers are not required, branch and uri are required modifiers for any fork. Note: the default branch is always prod, it is up to the developer to make sure that any alternative branch is called. This requires system privileges to execute.
Parameter | Datatype | Required |
---|---|---|
<rid> | <string> | √ |
Modifier | Datatype | |
---|---|---|
uri | <URI> | Point the <rid> to a new URI |
branch | <string> | Name a new branch of a rid. |
owner | <eci> | ECI of the developer that has rights to the ruleset |
flush_code | <string> | Required for non-owner developers to modify <rid> information |
header | <hash> | Replaces the entire header info of <rid> with the new hash/map |
version | <string> | Optional parameter to support the legacy Kynetx repository (defaults to "prod") |
username | <string> | Optional parameter to support HTTP basic authentication |
password | <string> | Optional parameter to support HTTP basic authentication |
rsm:fork("myUniqueRid") with uri = "http://www.github.com/solargroovy/foosh/newcode.krl" and branch = "alpha";
Of course, <rid> (ex: "myUniqueRid") needs to already exist. The KRL that is identified byuriis not validated, so it is possible to create a ruleset branch to non-existent or invalid KRL. Generally, withcreate, update, register we don't allow this to happen, but for now, it is not bound by validations.
create()
create(<rid>) setting (ridName) - Create a new ruleset with the exact name of "<rid>.prod". Ruleset version defaults to "prod". This requires system privileges to execute.
Parameter | Datatype | Required |
---|---|---|
<rid> | <string> | √ |
Modifier | Datatype | |
---|---|---|
uri | <URI> | Point the <rid> to a new URI |
description | <string> | Optional description for the ruleset |
owner | <eci> | ECI of the developer that has rights to the ruleset |
flush_code | <string> | Required for non-owner developers to modify <rid> information |
header | <hash> | Replaces the entire header info of <rid> with the new hash/map |
rid_version | <string> | Optional parameter to set version (defaults to "prod") |
username | <string> | Optional parameter to support HTTP basic authentication |
password | <string> | Optional parameter to support HTTP basic authentication |
Special Modifiers | ||
---|---|---|
autoraise | <string> | label for rsm:create event |
target | <rid> | optional ruleset id target for the raised event |
rsm:create("myUniqueRid") setting (isCreated) with owner = <eci> and description = "Read watchband settings" and flush_code = "4111" and headers = { "Accept" : "text/plain", "Cache-Control" : "no-cache" } and uri = "$uri";
Modifiersuriand owner are required. <rid> may not contain any periods '.' If a ruleset named <rid> is already created in the registry, the action will fail.
delete()
delete(<rid>) - remove the rid from the KRE registry
Parameter | Datatype | Required |
---|---|---|
<rid> | <string> | √ |
rsm:delete("watchband500293x0");
import()
import(<rid>) setting (r) - Create a registry entry for a ruleset curated by the old accounts system
Parameter | Datatype | Required |
---|---|---|
<rid> | <string> | √ |
Modifier | Datatype | |
---|---|---|
version | <string> | Optional parameter to set a initial version number |
kinetic_app_version | <string> | Optional parameter to support the legacy Kynetx repository (defaults to "prod") |
force | <string> | Optional parameter to force a reload (flush) from the Kynetx repository |
Special Modifiers | ||
---|---|---|
autoraise | <string> | label for rsm:import event |
target | <rid> | optional ruleset id target for the raised event |
rsm:import("a144x150") with kinetic_app_version = "dev";
rsm:import("a144x150") with kinetic_app_version = "prod" and force = 1;
RSM Predicates
is_valid()
is_valid(<rid>) - Validate function available in the pre block
Parameter | Datatype | Required |
---|---|---|
<rid> | <string> | √ |
is_good = rsm:is_valid("watchband500293x0");