Overview

What is Rule?

Rule Service provides a solution the capability to trigger events when a piece of data matches some predefined user criteria.

Application developers can configure this service with rules and then pass incoming data to the service. If the incoming data meet the condition of the configured rules, the service will trigger an event to inform the solution context that a rule has been triggered

What Rule Service does

Rule service supports the following rule types currently.

• Simple
• Regex
• Timeout
• Duration

Simple

Required parameters: (comparison(string), constant(number), repeat(boolean))

Values received by this rule are compared to a numerical constant defined in the rule.

In the event when this rule receives a non-number value, a toNumber() function will be applied to it. The output of that conversion will then be checked against the constant. If the output of the conversion is not a number, it's behaviour is undefined.

The available boolean comparators are:

1. Greater than (gt)
2. Less than (lt)
3. Equal to (eq)
4. Greater than or equal to (geq)
5. Less than or equal to (leq)
6. Not equal to (neq)

If repeat is true, the rule will keep triggering for every dataset that meets the defined conditions. If false, the event will only be triggered when the rule goes from triggered to untriggered or the other way around. The repeat option only affects the triggered state of the rule. The untriggered state will never repeat.

regex

Required parameters: (comparison(string), repeat(boolean))

The service will return an error code at rule create time if a user of the service tries to define a rule with invalid regex.

Values received by this type of rules are examined by the regex defined in the rule.

In the event when this rule receives a non-string value, a toString() function will be applied to it. The output of that conversion will then be checked against the regex.

If repeat is true, the rule will keep triggering for every dataset that meets the defined conditions. If false, the event will only be triggered when the rule goes from triggered to untriggered or the other way around. The repeat option only affects the triggered state of the rule. The untriggered state will never repeat.

timeout

Required parameters: (timeout(integer), repeat(boolean))

Triggers if no input value is received within a timeout period. The timer is restarted when an input value is received, when the timeout elapses, and when the script is first started. A timeout of 0 is not valid and will be rejected by the service.

If repeat is true, the rule will keep triggering every timeout until a matching data event is received. If false, the event will only be triggered when the rule goes from triggered to untriggered or the other way around. The repeat option only affects the triggered state of the rule. The untriggered state will never repeat.

Duration:

Required parameters: (comparison, constant, timeout, repeat)

When a value is received, it is immediately compared against the defined Comparison conditions. If the conditions are met, a timer is started. If the conditions are not met, the timer is stopped. When the rule is created, its timer is stopped and set to 0.

If the timer elapses, the rule will be triggered. If repeat is set to true, the timer will reset back to 0 and start over. It will keep triggering until it receives a dataset that causes the comparison to be false. If false, the event will only be triggered when the rule goes from triggered to untriggered or the other way around. The repeat option only affects the triggered state of the rule. The untriggered state will never repeat.

Preparation

1. Create a ramjet product at your solution listing page
2. Create a temp resource for your ramjet product
3. Create a 123 device for your ramjet product
4. Provision your 123 device following http://docs.exosite.com/tutorials/provisioning/#provision-a-whitelisted-device-token-authentication- and store the returned device token for later use
5. Create a ramjet application at your solution listing page
6. Connect your ramjet product to your ramjet application in the Product Setup service config page

Quickstart

Add Rule Service to your Business

Subscribe to Rule Service in Exchange for your Business. If you are not familiar with Murano’s Exchange Element, you can refer to this doc: Adding Exchange Elements.

Configure Rule Service

Copy and paste the following Lua code code to Rule Service Event Handler

print("[Rule Event Handler] data === " .. to_json(data))

args = {
  to = {
    "ramjet@example.com",
  },
  subject = "ramjet.apps.exosite.io",
  text = to_json(data),
}
print("[Rule Event Handler] Email.send(" .. to_json(args) .. ")")
Email.send(args)

You should be able to start using Rule Service APIs in your application. Below we provide an example to use this service.

Example using Rule Service APIs

Simple Rule

Forward your ramjet device data to Rule Service

1. Click Services
2. Click Ramjet

3. Copy and paste the following lua code

   print("[Ramjet Event Handler] event === " .. to_json(event))
   
   inputData = {
     metrics = {
       temp = event.payload[1].values.temp
     },
     tags = {
       device_id = 123,
       location = "door"
     }
   }
   print("[Ramjet Event Handler] Rule.inputData(" .. to_json(inputData) .. ")")
   Rule.inputData(inputData)
   

4. Click SAVE

Create an Endpoint to use Rule Service APIs to create a rule

This step adds a new application endpoint to use Rule Service APIs to create a rule.

1. Click Endpoints
2. Create an endpoint Click + NEW ENDPOINT Select POST from Select Method Fill /Rule/create in Path Click CREATE
3. Paste the following in the code editor:

   print("[POST /Rule/create] Rule.create(" .. to_json(request.body) .. ")")
   response.message = Rule.create(request.body)
   

4. Click SAVE

Request the Endpoint to use Rule Service to create a rule

The following curl command creates a simple rule that doesn't repeatedly trigger events on every data point from your ramjet devices matching your rule.

    curl -XPOST \
        -H'content-type: application/json' \
        "https://ramjet.apps.exosite.io/Rule/create" \
        -d@<(cat <<JSON
{
  "on": {
    "metric": "temp",
    "tags": {
      "device_id": 123,
      "location": "door"
    }
  },
  "parameters": {
    "comparison": "gt",
    "constant": 27.27,
    "repeat": false
  },
  "tags": ["level1", "root"],
  "trigger": "too hot",
  "type": "simple"
}
JSON
)

The response should look like:

25ae28959b641aa00c4c930e

Report data to your ramjet devices to make your rule publish events

In the previous section, we mentioned that "it doesn't repeatedly trigger events on every data point from your ramjet devices matching your rule."

The implication is that the rule above publish events when the rule goes from untriggered to triggered or the other way around, i.e. on triggered state change.

Let's see that in action by reporting data to your 123 ramjet device from the UI.

1. Go to the 123 ramjet device page from your device listing page for your ramjet product.
2. Click the pen to see the popup for reporting data to your 123 ramjet device.
3. Input 28 in the text field
4. Click SET
5. Click the pen again to see the popup for reporting data to your 123 ramjet device.
6. Input 27 in the text field
7. Click SET

Verify the result from Rule Service

Now check your mailbox, you should see two emails with their results values being true and false indicating that the rule state has changed to triggered then again changed to untriggered

Duration Rule

Forward your ramjet device data to Rule Service

Note: Skip this part if you have done this in the Simple Rule example.

1. Click Services
2. Click Ramjet

3. Copy and paste the following lua code

   print("[Ramjet Event Handler] event === " .. to_json(event))
   
   inputData = {
     metrics = {
       temp = event.payload[1].values.temp
     },
     tags = {
       device_id = 123,
       location = "door"
     }
   }
   print("[Ramjet Event Handler] Rule.inputData(" .. to_json(inputData) .. ")")
   Rule.inputData(inputData)
   

4. Click SAVE

Create an Endpoint to use Rule Service APIs to create a rule

Note: Skip this part if you have done this in the Simple Rule example.

This step adds a new application endpoint to use Rule Service APIs to create a rule.

1. Click Endpoints
2. Create an endpoint Click + NEW ENDPOINT Select POST from Select Method Fill /Rule/create in Path Click CREATE
3. Paste the following in the code editor:

   print("[POST /Rule/create] Rule.create(" .. to_json(request.body) .. ")")
   response.message = Rule.create(request.body)
   

4. Click SAVE

Request the Endpoint to use Rule Service to create a rule

Note: There is a difference in the value of parameters and type than the Simple Rule example.

The following curl command creates a duration rule that doesn't repeatedly trigger events on every data point from your ramjet devices matching your rule after specified timeout elapsed.

    curl -XPOST \
        -H'content-type: application/json' \
        "https://ramjet.apps.exosite.io/Rule/create" \
        -d@<(cat <<JSON
{
  "on": {
    "metric": "temp",
    "tags": {
      "device_id": 123,
      "location": "door"
    }
  },
  "parameters": {
    "comparison": "gt",
    "constant": 27.27,
    "timeout": 1000,
    "repeat": false
  },
  "tags": ["level1", "root"],
  "trigger": "too hot",
  "type": "duration"
}
JSON
)

The response should look like:

25ae28959b641aa00c4c930e

Report data to your ramjet devices to make your rule publish events

In the previous section, we mentioned that "it doesn't repeatedly trigger events on every data point from your ramjet devices matching your rule."

The implication is that the rule above publish events when the rule goes from untriggered to triggered or the other way around, i.e. on triggered state change.

Let's see that in action by reporting data to your 123 ramjet device from the UI.

1. Go to the 123 ramjet device page from your device listing page for your ramjet product.
2. Click the pen to see the popup for reporting data to your 123 ramjet device.
3. Input 28 in the text field
4. Click SET
5. Click the pen again to see the popup for reporting data to your 123 ramjet device.
6. Input 27 in the text field
7. Click SET

Verify the result from Rule Service

Now check your mailbox, you should see two emails with their results values being true and false indicating that the rule state has changed to triggered then again changed to untriggered.

Note that if you change the above example with "repeat": true. Then it will start to send an email every 1000 ms as soon as you set the value to 28, and won’t stop until you set it to 27 (or anything below 27.27). If you want to test out with "repeat" : true, change the “timeout” to something bigger to prevent the system from sending you too many emails.