Live Objects - complete developer guide

Simple Event Processing

Concepts

Simple event processing (SEP) service is aimed at detecting notable single event from the flow of data messages.

Simple event processing combines a stateless boolean detection function (matching rule) with a frequency function (firing rule).

It generates fired events as output that your business application can consume to initiate downstream action(s) like alarming, execute a business process, etc.

Figure 1. Simple Event Processing service E2E overview

Processing rules

You can set up Matching rules and Firing rules to define how data messages are processed by the SEP service and how fired events are triggered:

Matching rule

A matching rule is a simple or compound rule that will be applied on each data message to evaluate if a « match » occurs. A matching rule is evaluated as a boolean result. Matching rule supports numeric, string, logic and distance operators and is based on JsonLogic.

Matching context (containing data message and matching rule id, etc.) are processed by the firing rules associated to these matching rules.

Firing rule

A firing rule applies to the matches triggered by one or many matching rules and defines when fired events must be generated.

A firing rule specifies:

the list of matching rules associated to this firing rule – when these matching rules match, the firing rule is applied,
the frequency of firing: once, sleep and always,
optionally, a list of aggregation keys identifying fields to extract from the matching context to identify the firing context.

The firing rule is applied as follow on each matching context:

the firing rule generates the firing context from the matching context, by extracting one or multiple fields defined with the aggregation keys,
the firing rule then applies the frequency parameter to optionally throttle the triggering of fired events belonging to the same firing context.

If the frequency of the firing rule is defined as ONCE or SLEEP then firing guards are created in the system to prevent new generation of fired events for a given firing context. You can manage the firing guards, and for example, remove a firing guard to re-activate a firing rule for a specific firing context.

As an example, by setting the metadata.source field as aggregation key, if a fired event is generated for a device “A”, a firing guard will prevent new fired event for this device “A” and this firing rule. By the way, fired events could occur for devices “B”, “C”, etc… for this rule.

With SLEEP mode, a duration specifies the minimum time between two fired events. When the duration is elapsed, the firing guards is removed and new fired events could occur. This duration is computed for each element of the tuple composed of firing rule id + aggregation keys + value (firingRuleID:metadata.source:deviceId1 , firingRuleID:metadata.source:deviceId2, …)

The sleepDuration is expressed in a iso8601-duration format.

Fired events consumption

Fired events are accessible with the MQTT API. Your business application must connect using MQTT application mode and subscribe to a FIFO. This FIFO should previously be filled with matchingFired events.

References: MQTT Application mode, Event base trigger and Alarm output model.

Example of a fired event data representation

This example shows a fired event object triggered by one matching rule and filtered by a firing rule (that will block any other event from occuring unless the guard is lifted). The matching rule check on all published messages if the device location have more than 6 m from the the coordinates (48.800206,2.296565) and the temperature published is more than 99°. The firing rule then trigger the event and filter all messages selected by the source field "metadata.source".

{
  "matchingContext": {
    "matchingRule": {
      "dataPredicate": "{\"and\":[{\">\":[{\"distance\":[{\"var\":\"location.lat\"},{\"var\":\"location.lon\"},48.800206,2.296565]},6]},{\">\":[{\"var\":\"value.temp\"},99]}]}",
      "name": "compound rule with numeric and distance operators Rule",
      "id": "d5f75f5a-4c43-4b12-81e0-0ddff0083c52",
      "enabled": true
    },
    "data": {
      "metadata": {
        "connector": "mqtt",
        "source": "urn:lo:nsid:mqtt:myTest",
        "transformation": {
          "published": {
            "location": {
              "lon": -122.431297,
              "lat": 37.773972
            }
          }
        },
        "group": {
          "path": "/",
          "id": "root"
        },
        "network": {
          "mqtt": {
            "clientId": "urn:lo:nsid:mqtt:myTest"
          }
        }
      },
      "streamId": "urn:lo:nsid:dongle:00-14-22-01-23-45!temperature",
      "extra": {},
      "location": {
        "lon": -122.431297,
        "lat": 37.773972
      },
      "model": "temperatureDevice_v0",
      "value": {
        "temp": 105
      },
      "timestamp": "2021-06-17T13:15:04.165Z",
      "tags": []
    },
    "tenantId": "5c0a6fb49a927971342aea06",
    "timestamp": "2021-06-17T13:15:04.185Z"
  },
  "tenantId": "5c0a6fb49a927971342aea06",
  "timestamp": "2021-06-17T13:15:04.276Z",
  "firingRule": {
    "name": "firing rule test",
    "matchingRuleIds": [
      "d5f75f5a-4c43-4b12-81e0-0ddff0083c52"
    ],
    "id": "04e30d59-82eb-4fb5-9243-6111d188b131",
    "aggregationKeys": [
      "metadata.source"
    ],
    "firingType": "ONCE",
    "enabled": true
  }
}

Examples

Here are some examples of usage of the simple event processing service.

Data message sent by a device with temperature set to 105 and location set at San Francisco (37.773972,-122.431297)

{
  "streamId":"urn:lo:nsid:dongle:00-14-22-01-23-45!temperature",
  "location":{
    "lat":37.773972,
    "lon":-122.431297
  },
  "model":"temperatureDevice_v0",
  "value":{
    "temp":105
  }
}

Matching rule: numeric (temperature higher than 99) and distance operator (distance between data message and Paris (48.800206, 2.296565) must be higher than 6km)

{
  "id": "d5f75f5a-4c43-4b12-81e0-0ddff0083c52",
  "name": "compound rule with numeric and distance operators Rule",
  "enabled": true,
  "dataPredicate": {
    "and": [
        {
            ">": [
            {
                "distance": [
                {
                "var": "location.lat"
                },
                {
                "var": "location.lon"
                },
                48.800206,
                2.296565
                ]
            },
            6000
            ]
        },
        {
        ">": [
           {
             "var": "value.temp"
           },
          99
        ]
      }
    ]
  }
}

Firing rule with frequency ONCE and aggregationKeys based on the source field :

{
    "name": "firing rule test",
    "enabled": true,
    "matchingRuleIds": ["d5f75f5a-4c43-4b12-81e0-0ddff0083c52 --> {matchingRuleId}"],
    "aggregationKeys":["metadata.source"],
    "firingType":"ONCE"
}

Fired event will be generated once for each source sending data with temperature higher than 99 and not located within a radius of 6km of Paris.

Example with other operators ">", "if", "in", "cat" :

{
  ">":[
    {
      "var":{
        "cat":[
          "value.", {
            "if" : [
              {"in": [{"var":"model"}, "v0"]},
              "temp",
              {"in": [{"var":"model"}, "v1"]},
              "temperature",
              "t"
            ]
          }
        ]
      }
    },
    100
  ]
}

This rule allows to specify the field to be compared to the value "100” based on the model of the data message.

If the model value is:

"v0", the comparison will be made with the field "value.temp”,
"v1", the comparison will be made with the field "value.temperature”,
else it will be made with the field "value.t”.