Rule Engine Actions
What is an Action in the Rule Engine
As described in the Rule Engine Getting Started, an action is an operation performed after a rule is executed and returned a value. An action is attached to a rule. The same action can be attached to none, one, or many rules.
There are two types of actions: Positive and Negative.
Positive actions are executed if the rule returns true or any other value except false, null, or undefined.
Negative actions are executed if the rule returns false.
No actions are executed at all if the rule returns null or undefined.
Action Types
- Alert Activation: Activates an alert.
- Alert Resolution: Resolves an alert.
- Command Invocation: Invokes a command on an endpoint.
- Data Sample: Posts a data sample for an endpoint.
- Metadata Update: Updates metadata for an endpoint.
- Rule Execution: Executes another rule.
- Send Email: Sends an email.
- Time Series: Posts a data point in a particular endpoint’s time series.
- Webhook: Performs an HTTP POST request with a body to a specified URL.
To create an action of a specific type, go to Rules → Actions tab → select the desired action type from the dropdown → click Add Action. Fill in the configuration fields in the popup window and click the Create button.
Let’s review each action.
Alert Activation Action
Activates an alert on an endpoint or tenant.
Consider the fields other than Name and Description.
Severity Level
Can be defined via Value or Script.
Value- one of possible values from dropdown.Script- JavaScript code to dynamically determine the severity level during rule execution. Must return one of:CRITICAL,HIGH,MEDIUM,LOW,INFO.
Script example:
const currentTemperature = ctx.endpoint.getTimeSeries("temperature").last().values.value;
if (currentTemperature > 30) {
return "CRITICAL";
} else if (currentTemperature > 20) {
return "HIGH";
} else {
return "INFO";
}
Alert Type
Can be defined via Value or Script.
Value- static alert type, e.g.,HIGH_TEMPERATURE.Script- JavaScript code to dynamically determine the alert type during rule execution. Must return string.
Script example:
if (ctx.trigger.endpointDataSamplesReceived.dataSamples[0].temperature !== undefined) {
return "HIGH_TEMPERATURE";
} else if (ctx.trigger.endpointDataSamplesReceived.dataSamples[0].humidity !== undefined) {
return "HIGH_HUMIDITY";
} else {
return "UNKNOWN";
}
Message
Alert activation text message.
Can be defined via Value or Script.
Value- static message text, e.g.,There is high temperature!.Script- JavaScript code to dynamically determine the message during rule execution. Must return string.
Script example:
const currentTemperature = ctx.endpoint.getTimeSeries("temperature").last().values.value;
return `Current temperature is ${currentTemperature} degree!`;
Entity Type
Alert is always assigned to some entity. This field determines the type of the entity that the alert is assigned to.
- Endpoint - assign raised alert to an endpoint.
- Tenant - assign raised alert to the tenant.
Assign Alert To
Endpoint ID to assign alert to if the Entity Type is selected as Endpoint.
Can be defined via Current endpoint or Script.
Current endpoint- endpoint for which rule is executed.Script- JavaScript code to dynamically determine the endpoint ID. Must return string.
Script example:
return "c3fa0b8c-96e4-4d4f-a354-7386f8f0c0e1";
Started At
Timestamp of when alert was started for the first time.
Can be defined via Auto or Script.
Auto- timestamp is determined by Rule Engine at the moment of rule execution.Script- JavaScript code to dynamically determine the timestamp. Must return UNIX time in milliseconds.
Script examples:
return Date.now();
return 1724830799831;
const lastDataPointTimestamp = ctx.endpoint.getTimeSeries("temperature").last().values.timestamp;
return lastDataPointTimestamp;
Last Active At
Timestamp of when alert was last active.
Can be defined via Auto or Script.
Auto- timestamp is determined by Rule Engine at the moment of rule execution.Script- JavaScript code to dynamically determine the timestamp. Must return UNIX time in milliseconds.
Script examples:
return Date.now();
return 1724830799831;
const lastDataPointTimestamp = ctx.endpoint.getTimeSeries("temperature").last().values.timestamp;
return lastDataPointTimestamp;
Alert Resolution Action
Resolves earlier activated alert.
Consider the fields other than Name and Description.
Alert Type
Can be defined via Value or Script.
Value- static alert type, e.g.,HIGH_TEMPERATURE.Script- JavaScript code to dynamically determine the alert type to resolve during rule execution. Must return string.
Script example:
if (ctx.trigger.endpointDataSamplesReceived.dataSamples[0].temperature !== undefined) {
return "HIGH_TEMPERATURE";
} else if (ctx.trigger.endpointDataSamplesReceived.dataSamples[0].humidity !== undefined) {
return "HIGH_HUMIDITY";
} else {
return "UNKNOWN";
}
Message
Alert resolution text message.
Can be defined via Value or Script.
Value- static message text, e.g.,Temperature is back to normal.Script- JavaScript code to dynamically determine the message during rule execution. Must return string.
Script example:
const currentTemperature = ctx.endpoint.getTimeSeries("temperature").last().values.value;
return `Temperature is back to normal. Current temperature is ${currentTemperature} degree!`;
Entity Type
Alert is always assigned to some entity. This field defines the type of the entity that the earlier raised alert that should be resolved is assigned to.
- Endpoint - resolve alert that is assigned to endpoint.
- Tenant - resolve alert that is assigned to tenant.
Resolve assigned alert to
Endpoint ID that the alert must be resolved on if the Entity Type is selected as Endpoint.
Can be defined via Current endpoint or Script.
Current endpoint- endpoint for which rule is executed.Script- JavaScript code to dynamically determine the endpoint ID. Must return string.
Script example:
return "c3fa0b8c-96e4-4d4f-a354-7386f8f0c0e1";
Command Invocation Action
Invokes a command on an endpoint or tenant.
Consider the fields other than Name and Description.
Endpoint
Endpoint ID to invoke command on.
Can be defined via Current endpoint or Script.
Current endpoint- endpoint for which rule is executed.Script- JavaScript code to dynamically determine the endpoint ID. Must return string.
Script example:
return "c3fa0b8c-96e4-4d4f-a354-7386f8f0c0e1";
Command type
Command type.
Command payload expression
JavaScript code to dynamically determine command payload to send to the endpoint. Expression must return any JavaScript type.
Examples:
return 'on';
return {switch: 'on'};
Data Sample Action
Posts a data sample on behalf of endpoint.
Consider the fields other than Name and Description.
Endpoint
Endpoint ID to post data sample on behalf of.
Can be defined via Current endpoint or Script.
Current endpoint- endpoint for which rule is executed.Script- JavaScript code to dynamically determine the endpoint ID. Must return string.
Script example:
return "c3fa0b8c-96e4-4d4f-a354-7386f8f0c0e1";
Data samples expression
JavaScript code to dynamically determine data sample payload. Expression must return either JavaScript array or object.
Examples:
return {temperature: 30};
return [{temperature: 20}, {humidity: 40}];
Metadata Update Action
Updates metadata of a specific endpoint.
Consider the fields other than Name and Description.
Endpoint
Endpoint ID to update metadata of.
Can be defined via Current endpoint or Script.
Current endpoint- endpoint for which rule is executed.Script- JavaScript code to dynamically determine the endpoint ID. Must return string.
Script example:
return "c3fa0b8c-96e4-4d4f-a354-7386f8f0c0e1";
Metadata key
Metadata key to update.
Can be defined via Value or Script.
Value- static metadata key, e.g.,city.Script- JavaScript code to dynamically determine metadata key. Must return string.
Script example:
return "location";
Metadata value expression
JavaScript code to dynamically determine metadata value payload. Expression must return any JavaScript type.
Examples:
return "Kyiv";
return {city: "Kyiv"};
Rule Execution Action
Executes another rule. This action allows you to build a chain of rules to keep your rules small, granular and reusable.
This action has only one Rule field other than Name and Description. From the dropdown, you can select the rule that must be executed by this action.
Send Email Action
Sends email.
Consider the fields other than Name and Description.
Recipients
List of email recipients.
Note that in order for the recipient to receive emails, it must be verified. For that, go to Rules → switch to Recipients tab → click Add recipient button and enter the recipient email. After clicking Add Recipient button the verification email will be sent.
Can be defined via Static or Script.
Static- static list of emails, e.g.,admin@acme.com,support@acme.com.Script- JavaScript code to dynamically determine list of email recipients. Must return an array of strings.
Script example:
return ['admin@acme.com', 'support@acme.com'];
Email subject
Email subject.
Can be defined via Static or Script.
Static- static email subject, e.g.,High temperature.Script- JavaScript code to dynamically determine the email subject. Must return a string.
Script example:
return `High temperature in room ${ctx.endpoint.getMetadata().roomNumber}`;
Content type
Content type of the email body. Can be either Text or HTML.
Email body
Email body.
Can be defined via Static or Script.
Static- static email body, e.g.,High temperature detected!.Script- JavaScript code to dynamically determine the email body. Must return a string.
Script example:
const endpointRoom = ctx.endpoint.getMetadata().roomNumber;
const currentTemperature = ctx.endpoint.getTimeSeries("temperature").last().values.value;
return `High temperature detected in room ${endpointRoom}. Current temperature is ${currentTemperature}.`;
Refer to the Template Engine section to find out how to dynamically assemble email text using Mustache template engine.
Time Series Action
Posts data point for the specified time series.
Consider the fields other than Name and Description.
Endpoint
Endpoint ID to post time series data point for.
Can be defined via Current endpoint or Script.
Current endpoint- endpoint for which rule is executed.Script- JavaScript code to dynamically determine the endpoint ID. Must return string.
Script example:
return "c3fa0b8c-96e4-4d4f-a354-7386f8f0c0e1";
Time series name
Time series name to post data point for.
Can be defined via Value or Script.
Value- time series name, e.g.,temperature.Script- JavaScript code to dynamically determine the time series name. Must return string.
Script example:
return "temperature";
Time series expression
Time series data point expression.
Expression must return JavaScript object or array.
Example:
return {value: 10};
return [{temperature: 10, humidity: 40}];
Webhook Action
Performs HTTP POST request with a body to a specified URL.
Consider the fields other than Name and Description.
Webhook URL
URL to perform POST request to.
Example: https://example.com/kaa-webhook-callback
Headers
JavaScript code to dynamically determine HTTP headers to send in POST request. Expression must return JavaScript object.
Example:
return {'Content-Type': 'application/json'};
Webhook payload expression
JavaScript code to dynamically determine request body. Expression must return any JavaScript type.
Example:
const currentTemperature = ctx.endpoint.getTimeSeries("temperature").last().values.value;
return {
temperature: currentTemperature,
endpointId: ctx.endpoint.getId()
};