event

The event library provides functions for understanding an event and the environment in which it was raised as well as actions for sending events.

Event Functions

There are three categories of event functions.

Event Environment

For historical reasons, some of these are Web-centric. The following functions are available:

event:env()- returns information about the event's environment. The function takes an argument that determines what will be returned:

caller -return the URL of the Web page on which the event is firing (assumes an event in the web domain)
ip - return the IP number of the endpoint (client).
referer - return the URL of the referring page to the caller (assumes a web event).
title - return the page title of the calling page.
txn_id - return the transaction ID of this ruleset evaluation.

Event Attributes

event:attr() - returns a specific event attribute. The function takes the name of the attribute to be returned as its sole argument.
event:attrs() - returns all the event attributes as a map.

Event Channels

event:channel() - returns information about the event channel. The function takes an argument that determines what is returned:
- id - returns the event channel identifier.

Event Actions

The event library supports sending events to event channels.

event:send(<subscription_map>, <domain>, <name>)

The <domain> and <type> are expressions that evaluate to strings. These arguments are optional. If they are not present, the values with keys _domain and _type from the subscription map will be used.

A subscription map is any map that contains an event channel identifier (identified by the key cid) or an event signal URL (identified by the key esl). The other key-value pairs in the map are optional. The following code sample shows a subscription map:

subscription_map =
 {"name":"Phil",
  "phone":"8013625611",
  "cid":"072a3730-2f8a-052f-2ddb-00553e411455",
  "calendar":"https://www.google.com/calendar/..."
 };

Given the preceding subscription map declaration, we could send a notification:status event to the event channel identified by the CID in the map as follows:

event:send(subscription_map, "notification", "status")

If the subscription map contains both a CID and an ESL, the ESL is used to send the event.

Event attributes can be specified in the optional action parameter attrs. To send a notification:status event with the attributes priority and subject, we would modify the preceding example as follows:

event:send(subscription_map, "notification", "status")
  with attrs = {"priority": "2",
	        "subject" : "urgent message"
               }

Of course, the arguments and parameters of an action can be calculated.

If the ESL or CID have non-standard keys in the subscription map, you can use the parameters cid_key or esl_key to give the key name:

event:send(subscription_map, "notification", "status")
  with attrs = {"priority": "2",
	        "subject" : "urgent message"
               }
   and cid_key = "channel_id"
 
event:send(subscription_map, "notification", "status")
  with attrs = {"priority": "2",
	        "subject" : "urgent message"
               }
   and esl_key = "event_url"