This page will guide you through the steps necessary to obtain and operate your own Kinetic Rules Engine (KRE).

Learning Objectives

After completing this quickstart lesson, you will:

• understand important concepts about programming in KRL including ruleset structure^*
• know how to install and operate the node pico-engine
• know how to use the "Engine Rulesets" page to register a ruleset
• know how to add a ruleset to a pico
• become familiar with using the "My Picos" page to work with your picos

Concepts

^*This section is copied verbatim from Quickstart (the one for the original KRE system)

Getting started with KRL can be a big leap because there are so many things that are different about programming in KRL:

• KRL is a rule-based language. 
• KRL primarily follows an event-based programming model. 
• KRL programs execute with a cloud-based model; there is no way to execute them from the command line.
• KRL programs are loaded from the cloud using HTTP. 
• KRL programs execute in a system where identity is pervasive; all events are raised on behalf of a specific entity.
• KRL programs have built-in, entity-specific persistent storage; there is no need for external databases.

The result of these properties is a programming model that more closely resembles programming cloud-based persistent objects than anything else. We call these persistent computational objects "picos". 

KRL is executed by your instance of the node pico-engine, an open-source, cloud-based rule processing system. All of the properties listed above are present in any KRE system. 

Install and run the node pico-engine

Prerequisite: you will need to install node (also known as Node.js) on your machine. It includes npm, the node package manager.

$ npm install -g pico-engine
$ PORT=8084 pico-engine
http://localhost:8084

In the example above, port number 8084 was chosen. By default, if you run the command `pico-engine` without setting the environment variable, port 8080 will be used. The node pico engine will spend some time initializing internal data structures before it starts its web server.

When you first run the node pico-engine, it does some initialization work, which may take some time. After doing this, it starts a web server on the port you selected, if any, or on port 8080.

Note that the web server displays the URL of its document root, ex. "http://localhost:8084" and then continues to run. As we will see later, messages will be logged to this console.

Create a primary, or owner pico

Visit the default web page of your web server. As this page loads, it will perform a bootstrap sequence, which creates a pico, naming it "Owner Pico" and then registers and installs two rulesets.

Image Removed

Subsequent visits to the same page will short-circuit the bootstrap (because it's already been done).

Image Removed

In the console window in which the node pico-engine is running, there will be some logging concerning the two events sent during intial bootstrapping. You may find it interesting to try to make sense of these log messages.

Writing KRL

Here is a sample KRL ruleset:

...

Pre-requisites

The pico-engine is implemented in Node.js and consists of packages managed by npm, so you will need to install both node and npm on your machine. Some suggestions for this are located in the pico-engine code repository and in “npm Docs”. Once you have npm installed on your machine, continue with the installation of the pico-engine.

You may find these topics of interest once you’ve got your engine running.

Installation Video

Installation

Normally, this will be a single command, shown here:

npm install -g pico-engine

To do this you will need to first install node. You may need to upgrade your version of node to the latest version if it is already installed.

If you experience permission problems, consult this page of the npm Docs. Depending on your OS, you may need to install as root. There is also a troubleshooting section in the pico-engine code repository.

Operation

Running the pico-engine is also a single command:

pico-engine

Now, go to your browser and visit this page:

http://localhost:3000

Developer Interface

The pico-engine starts with a primary, or root pico.  This Pico is set up with the minimum required rulesets for running a pico in the developer UI. You can visit the developer UI at http://localhost:3000 and see the Pico.

...

The root pico is represented by a rectangle which is placed on a canvas, allowing you to change its size and placement. Keep this browser open as we will use it later to install a ruleset. We will start with a simple ruleset designed to echo a “Hello World” message, described in the next section.

When you single click on the name of the Pico, its rectangle opens up, giving you access to information about it, with a tabbed interface.

...

The "About" tab will be used in subsequent lessons. For now, notice that the pico is identified by a unique identifier, called an event channel identifier (which also appears as part of the browser’s location bar), and that it has no children. You can change the pico’s name and color from this tab.

Hello World KRL Ruleset

The hello world ruleset is an example of basic KRL ruleset structure.

ruleset hello_world {
  meta {
    name "Hello World"
    description <<
A first ruleset for the Quickstart
>>
    author "Phil Windley"
    logging on
    shares hello
  }
   
  global {
    hello = function(obj) {
      msg = "Hello " + obj;
      msg
    }
  }
   
  rule hello_world {
    select when echo hello
    send_directive("say") with
      something =, {"something": "Hello World"})
  }
   
}

Open the "Engine Rulesets" page (linked from the "Pico Bootstrap" page), and paste the ruleset above into the big text area, and click the "validate" button. When your KRL compiles correctly, you will see a result of "ok" beneath the buttons, with the page looking like this screenshot.

Image Removed

Click on the "register" button, and then your page will look like this screenshot.

Image Removed

Your ruleset is now registered with the node pico-engine, and its name is highlighted in the list of registered rulesets. Notice the circle beside the ruleset name. This indicates that the source code has been registered with the pico-engine, but is not yet enabled. Click on the "enable" button to take care of this.

Finally, click on the "install" button. This causes the pico-engine to compile the KRL and cache the compiled version in a rulesets folder. Once this has been done, the ruleset can be added to picos.

Adding the Ruleset to your pico

So far, you have installed the ruleset into your pico-engine. But it can't run unless it has been added to a pico.

Adding a ruleset to a pico is properly a user function, but as a developer, you are functioning in both user and developer capacities.

View your Owner Pico by visiting the "My Picos" page (linked from the "Pico Bootstrap" page).

Image Removed

Your owner pico is represented by a rounded rectangle, which is placed on a canvas, allowing you to change its placement.

Click on the rounded rectangle, on your Owner Pico. It expands giving you access to information about it.

Image Removed

The "About" tab will be used in subsequent lessons.

Click on the "Rulesets" tab.

Image Removed

Notice that the name of your ruleset is in a drop-down list. Click the "add ruleset" button to add the ruleset to your pico.

Image Removed

Notice that you are able to delete the ruleset from the picoThe following describes parts of the ruleset shown above:

Line 1: A ruleset starts with the ruleset keyword, followed by the ruleset identifier or RID. In this case, the RID is hello_world. The body of a ruleset is contained within the curly brackets opening at line 1 and closing at line 24. By convention, this ruleset will be stored in a file named hello_world.krl (the RID followed by a .krl file extension).

Lines 2-9: A ruleset usually contains a meta block giving information about the ruleset. This information includes data like the ruleset name and author, as well as pragmas that affect the ruleset's behavior. For example, this ruleset has a shares pragma saying which global functions are shared with the outside world. 

Lines 11-16: A ruleset usually contains a global block which globally binds values to names, some of which may be shared. In this case, the name hello is bound to a function value and is shared.

Lines 18-21: A ruleset usually contains one or more rules. In this case there is one rule named hello_world which will be watching for events with domain echo and name, or type, hello.

Installing Your Ruleset

A recommended workflow for writing KRL is found in KRL Programming Workflow. This example uses the local filesystem of the author to host KRL source code. 

When you install a ruleset, the pico-engine fetches the KRL source code from the URL you provide, parses and compiles the KRL source code, and installs the compiled code inside the pico.

Installing a ruleset in a pico enables the pico-engine to evaluate selected rules for that pico when corresponding events are raised to that pico. All of the computation done by a pico, and all of the data that it stores, is specified by the rulesets which are installed in the pico.

Now, click on the "Rulesets" tab. Enter the URL to the KRL source code in the box indicated and click on that “Install” button. You can ignore the “Config” box for now, but it will be used in subsequent lessons.

Clicking on the "Install" button will cause the pico-engine to get your ruleset using an HTTP GET, compile it, and register it with the engine and install it in this pico. 

...

Your URL will be different from the one shown here.

If you're using something like GitHub to host your rulesets, be sure that you supply the "raw" URL. The raw URL returns the file without any page chrome.  For example, this is a raw and cooked example of the same ruleset.  If you're hosting your rulesets on Amazon S3, be sure the URL is public and can be retrieved using a browser. 

Finally, the ruleset will be installed in this pico, as you can see when the page refreshes. Besides being able to do everything the first three rulesets can do, this pico can now do hello_world kinds of things. We will see more about this in future lessons.

...

One of the rulesets is at version “0.0.0”. You can ignore the version information for now, but this will be discussed in subsequent lessons. Your ruleset doesn’t have a version, and so is considered to be a “draft” at this point. This allows you to edit it and work with it more easily. We will refine the hello_world ruleset in subsequent lessons.

Clicking on the checkbox beside your ruleset’s RID reveals more information about it.

...

Notice that you are allowed to uninstall from the pico any ruleset that you install.

After you have modified the source code (remember that it is stored at the location indicated (in this case in your local filesystem)) you can hit the “flush” button to have the engine update the installed ruleset from your changes.

The line labeled “Hash” indicates the engine’s identifier for the current version of your ruleset source code. When you edit your source code and flush the changes, this identifier will change.

You now own a pico, with a ruleset you coded installed in it.

Next Steps

Having completed this quickstartQuickstart, you should are prepared to continue with Lesson 1. the Events and Queries Lesson