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:
- Greater than (gt)
- Less than (lt)
- Equal to (eq)
- Greater than or equal to (geq)
- Less than or equal to (leq)
- 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
- Create a ramjet product at your solution listing page
- Create a temp resource for your ramjet product
- Create a 123 device for your ramjet product
- 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
- Create a ramjet application at your solution listing page
- 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
- Click Services
- Click Ramjet
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)
- 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.
- Click Endpoints
- Create an endpoint
Click + NEW ENDPOINT
Select POST from Select Method
Fill
/Rule/create
in Path Click CREATE - Paste the following in the code editor:
print("[POST /Rule/create] Rule.create(" .. to_json(request.body) .. ")") response.message = Rule.create(request.body)
- 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.
- Go to the 123 ramjet device page from your device listing page for your ramjet product.
- Click the pen to see the popup for reporting data to your 123 ramjet device.
- Input 28 in the text field
- Click SET
- Click the pen again to see the popup for reporting data to your 123 ramjet device.
- Input 27 in the text field
- Click SET
Verify the result from Rule Service
Now check your mailbox, you should see two emails with their result
s 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.
- Click Services
- Click Ramjet
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)
- 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.
- Click Endpoints
- Create an endpoint
Click + NEW ENDPOINT
Select POST from Select Method
Fill
/Rule/create
in Path Click CREATE - Paste the following in the code editor:
print("[POST /Rule/create] Rule.create(" .. to_json(request.body) .. ")") response.message = Rule.create(request.body)
- 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.
- Go to the 123 ramjet device page from your device listing page for your ramjet product.
- Click the pen to see the popup for reporting data to your 123 ramjet device.
- Input 28 in the text field
- Click SET
- Click the pen again to see the popup for reporting data to your 123 ramjet device.
- Input 27 in the text field
- Click SET
Verify the result from Rule Service
Now check your mailbox, you should see two emails with their result
s 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.