Learning Objective

After completing this lesson you will be able to:

• Explain channels and use the Developer Tools console to manage them.
• Send events and queries to a pico on custom channels using curl, the event console and a browser.
• View events and queries in pico logs.

• Log variables inside rules using log() and klog() functions

Prerequisites

• Complete (Classic) Quickstart
• Have a ruleset registered and installed
• Event Console installed in Google Chrome

Create a Channel

Channels are the way picos receive events. Picos can have multiple channels. Best practice is to create a separate channel for each purpose or correspondent.  Each channel can have a name and a type. 

To create a channel using Devtools, navigate to the Channel Manager from the Devtools Home screen: 

The Channel Manager allows you to view existing channels, create new ones and delete them.

Click on New Channel.

Name your new channel Event_Bus_1 with type Pico_Tutorial. Ignore Channel Policy and Channel Attributes for now.

After double checking that you have the correct information, click install.

Channels are grouped by Type. You should now have a Pico_Tutorial group with Event_Bus_1 channel.

Congratulations! You just created your first Channel. Now you have a designated channel to raise events to. You can read more about Channels here.

Raising Events to the Channel

Open the Kynetx Event Console app in a new tab in Google Chrome.

Kynetx Event Console allows you to enter an event domain and type as well as a specific channel and server to raise events to.

Kynetx Event Console also allows you to attach event attributes. Below the Attributes section on the page you will find Response, where Kynetx Event Console will display the results of your raised event.

Let's raise an event to your hello_world ruleset on your newly created channel, Event_Bus_1. Remember the hello_world rule which selects on event domain Echo, and event type hello. (Note: capitalizing "echo" is an intentional bug, we will use this to learn how to debug.)

1. In Kynetx Event Console enter Echo (our intentional bug) as the domain and hello as the type.
2. In the devtools Channel Manager, copy Event_Bus_1 ECI (Event Channel Identifier). You will need to click on the Pico_Tutorial drop down and then Event_Bus_1 drop down to highlight Channel ID. 
3. In the Kynetx Event Console paste Event_Bus_1 ECI into Event Channel Identifier field.

Kynetx Event Console should look like this (except the Event Channel Identifier will be your ECI).

At the bottom of Kynetx Event Console click Raise Event.

Way to go! You just raised your first Event to a Channel you created. But wait!! We don't see the execpted string, "Hello World", in the Response (because of our capitalized domain bug).

View Event in Pico Logs

Let's debug the rule set with Pico Logs in devtools.

Pico Logs allow you to view the events coming into your pico.  Pico Logs display the event domain, type, ECI and information about the creation and execution of the event. 

In devtools navigate back to home directory and click on Pico Logging. To enable logs on your Pico you need to toggle the logging button on and refresh the page.

In Kynetx Event Console Raise your Echo hello world event again.

Refresh your Pico Logs by clicking "Refresh".  You should see a new event log called hello.

  If you look close you can see that our hello_world rule is not catching the event.

We can tell that because no rule get scheduled and run after scheduling starts. 

Let's look at that rule again.

 rule hello_world {
   select when echo hello
   send_directive("say") with
     something = "Hello World";
 }

The hello_world rule is selecting on domain echo, we raised event with domain Echo. Oops. We can see the domain that the pico saw by looking in the log for the event:

In Kynetx Event Console change the domain from Echo to echo and raise the new event.

Congratulations! You just received your first directive from an event you raised.

Directives allow picos to direct endpoints to react a certain way to an event.  Our rule's directive just says hello, but it could be used to do more complex things. Directives allow the program's logic to be placed in the rules, not in the end points.  Placing logic in the rules provides loose coupling with easier scaling and maintenance.  

Logs

The klog() operator allows you to log or print values to your pico logs.

Let's add a klog() to the rule to see what is happening.

We're going to change hello_world rule to print out "Hello" followed by our name ( Hello <name> ). The name to be printed will be given as an event attribute and can be accessed in the event attribute structure.

The prelude block of a rule is the place to set up all your variables and handle any calculations that must be done for the logical turning point of the rule.

Declare a variable named name that contains the value of the name attribute. Use a KRL beesting to place the string Hello with the value of name in the directive.

You can add klog() to any expression in KRL and see the evaluation of the command in pico logs. Place a klog() on the event:attr() expression.

The postlude allows for explicit logging. Add an explicit logging command which puts "LOG says Hello <name>".

Your rule should look like this:

rule hello_world {
  select when echo hello
  pre{
    name = event:attr("name").klog("our passed in Name: ");
  }
  {
    send_directive("say") with
      something = "Hello #{name}";
  }
  always {
      log ("LOG says Hello " + name);
  }
}

You will need to update your code online (i.e. github) as well as flush the ruleset.

Raise event in Event Console with an added attribute, your name. Make sure to use the same key identifier in the event console as you did in your rule.

Here's the response we get. 

Refresh your Logs. You should see the event you just raised. Notice the logs we put in our code are being printed in log.

Awesome Sauce! Armed with a knowledge of logs, now your ready to wage war on KRL bugs.

Raise Event with Sky API

The Sky Event API allows you to raise your event in the form of a web hook. We will raise an event in your browser as well with curl and view the results in Pico Logs.

Sky event URL (sometimes called an ESL) follow this API format, 

/sky/event/<eci>/<eid>/<domain>/<type>?<attrKey>=<attrValue>&..

The only value different from Event Console is the event ID (eid), which is a unique value you can assign your event so you can identify it in your logs, just use 1 for now.

The equivalent webhook to the event we raised using the Kynetx Event Console above would be:

https://cs.kobj.net/sky/event/3EFEEEEE-AF53-11E5-81D4-E8B8D34451B4/45562323625/echo/hello?name=Windley

Copy paste this in your browser and hit enter.

Tickety-Boo! You just created your first webhook for a specific event.

You should see your directive results telling you hello.

Open up terminal and enter curl and your webhook, like so.

curl "https://cs.kobj.net/sky/event/3EFEEEEE-AF53-11E5-81D4-E8B8D34451B4/45562323625/echo/hello?name=Windley"

You should have the same results but in your terminal.

Querying the hello Function

The Sky Cloud API allows you to query a ruleset's functions.

Functions in KRL can only be used to access a pico's variables, never to mutate the pico's state.

Queries follow the API form 

https://cs.kobj.net/sky/cloud/<rid>/<function>?_eci=<eci>&name0=value0&...&namen=valuen

where rid is the ruleset identifier your ruleset received when you registered it.

You will find your RID in registered rulesets.

If you review the code, you'll see there's a function named hello() in the global block of the code. The function takes a single argument named obj. 

In the preceding pattern, function is the name of your function, in our case hello. provide your name as obj parameter. Enter your query in a browser and hit enter.

It should look something like this (your RID and ECI will be different):

https://cs.kobj.net/sky/cloud/b507706x0.prod/hello?_eci=3EFEEEEE-AF53-11E5-81D4-E8B8D34451B4&obj=Windley

You should a result of "Hello" followed by whatever value you provided for obj. 

Now let's use curl to post our query. Open up a terminal and type in.

curl --data "_eci=3EFEEEEE-AF53-11E5-81D4-E8B8D34451B4&obj=Windley" https://cs.kobj.net/sk06x0.prod/hello

Way to go, you just queried your hello() function in hello_world ruleset.

Congratulations!

You have completed Events and Queries lesson ...

Challenges

1. Create a new rule that selects on a custom domain, raise an event to your rule and view your new rule in Pico logs to guarantee its firing.
2. Modify hello function to print, "Im alive", after your name.