Configuring Data Forwarding Rules

Overview

A rule engine can subscribe to device topics, obtain data reported by devices, and send parsed data to other cloud services for use. For example, a user can define a rule that requires a device to report its temperature every hour. If the device temperature exceeds the normal range, the device will be shut down and an alarm notification will be sent to the user. LINK transmits the collected data to the big data analysis platform to evaluate the risks of other devices.

Prerequisites

• Each data forwarding rule must belong to an integration application. Before creating a rule, ensure that an integration application is available. Otherwise, create an integration application first.
• To use a rule engine to forward data to DIS, the user must be assigned the DIS Administrator role.

Creating a Rule

1. Log in to the ROMA Connect console. On the Instances page, click View Console of an instance.
2. In the navigation pane on the left, choose LINK > Rule Engine. On the page displayed, click Create Rule in the upper right corner.
3. In the Create Rule dialog box, set rule parameters and click OK.

   Table 1 Parameters for creating a rule

   Parameter	Description
   Rule Name	Enter a rule name. It is recommended that you enter a name based on naming rules to facilitate search.
   Integration Application	Select the integration application to which the rule belongs.
   Description	Enter a brief description of the rule.
   Status	This parameter specifies whether to enable the rule. The rule is enabled by default. The rule takes effect only after being enabled.

4. After the rule is created, click its name in the rule list to access the rule details page.
5. Configure a source for the rule.
   1. Click Create Source in the Source area.
   2. Configure source parameters and click Save.

      Table 2 Parameters for creating a source

      Parameter	Description
      Product Name	Select the product to which a device belongs.
      Device Name	Select the device that needs to forward data. You can select a specified device or all devices.
      Topic Name	Select the topic used by the device to report messages.
      Topic Level	Select the topic level. The value is automatically adapted based on the value of Device Name. If you do not specify Device Name, Topic Level is Product. If you select a specific device from the Device Name drop-down list box, Topic Level is Device.
      Base64 Encoding	This parameter specifies whether Base64 encoding is performed on the forwarded device data.
      Include Device Data	This parameter specifies whether the forwarded device information contains device data.

6. (Optional) Configure data parsing to filter the data to be forwarded.
   For details about the SQL parsing configuration, see SQL Parsing.

   

   After data parsing is applied, the Base64 Encoding and Include Device Data parameters do not take effect.

7. Configure a destination for the rule.
   1. Click Create Destination in the Destination area.
   2. Configure destination parameters and click Save.

      Table 3 Parameters for creating a destination

      Destination Type	Parameter	Description
      ROMA MQS	Connection Address	Select the connection address of ROMA MQS.
      	Topic Name	Select the name of the topic to which data is to be forwarded.
      	Username	This parameter is available only if MQS SASL_SSL is enabled for the ROMA Connect instance. Enter the key of the integration application to which the topic defined in Topic Name belongs.
      	Password	This parameter is available only if MQS SASL_SSL is enabled for the ROMA Connect instance. Enter the secret of the integration application to which the topic defined in Topic Name belongs.
      DMS for Kafka	Connection Address	Select the connection address of DMS for Kafka from the drop-down list box.
      	Topic Name	Select the name of the topic to which data is to be forwarded.
      	Username	This parameter is available only if MQS SASL_SSL is enabled for the ROMA Connect instance. Enter the key of the integration application to which the topic defined in Topic Name belongs.
      	Password	This parameter is available only if MQS SASL_SSL is enabled for the ROMA Connect instance. Enter the secret of the integration application to which the topic defined in Topic Name belongs.
      DIS	Stream	Select the name of the DIS stream to which data is to be forwarded. A DIS stream is a logical unit created by tenants to distinguish real-time data of different tenants. When DIS is used to send or receive data, you need to specify the stream name.
      	Service	Select an entrusted service. The entrusted service allows a user to create an entrustment on IAM and grant ROMA Connect the permission to access DIS.
      Device topic	Product	Select the product to which a device belongs.
      	Device	Select the name of the device to which data is to be forwarded.
      	Topic	Select the name of the topic to which data is to be forwarded.

SQL Parsing

Concepts

After a device is connected to ROMA Connect, the device encapsulates data into a message in JSON format and sends the message to ROMA Connect. JSON contains keys and values. A rule can be viewed as an SQL statement and JSON as a table. A key indicates a column header of the table, and its value indicates the corresponding key value. Device messages are filtered using the SQL statement and then sent to other services.

For example, a temperature sensor is used to control the temperature of devices. It can collect the device type, ambient temperature, ambient humidity, and current time. The format and content of the reported information is shown in the example.

{
"device":"camera",
"temperature":30,
"humidity":65,
"time":"xxx,xxx"
}

If you want to make a rule that requires an alarm message to be sent when the temperature is higher than 20 degrees Celsius or lower than 15 degrees Celsius, enter the following SQL statement: If the preceding conditions are met, LINK reports the device type, absolute value of the device temperature, device humidity, and time for further processing.

SELECT
        device, abs(temperature),
        humidity               ,
        TIME
FROM
        mcxeSR187154/OUT/test
WHERE
        temperature > 20
OR      temperature < 15

In the FROM statement, mcxeSR187154/out/test indicates that the rule engine accepts only messages from the device named test. Your device may be different from that in the example. Modify the device information based on the site requirements.

This rule is triggered when the temperature in reported data is greater than 20°C or less than 15°C. In addition, the temperature, device name, and location in the data will be parsed for further processing. Figure 1 shows the data parsing result.

Figure 1 Data parsing result

Usage Description

An SQL statement consists of three parts: SELECT, FROM, and WHERE. Data in JSON format is classified into two types: constant data with single or double quotation marks and variable data without any quotation marks.

The field in the SELECT statement is the value of the key in the JSON message. Built-in SQL functions are supported. For details about how to use other SQL functions, see Table 5. In addition, the SELECT statement supports not only the combination of asterisks (*) and functions, but also arrays and JSON with nested values. For example, you can use a.color to obtain "color":"red" in {"a":{"temperature":29, "color":"red"}}. Note that the fields without quotation marks are variables, and the fields with single quotation marks and double quotation marks are constants.

The temperature can be a positive number, 0, or negative number. To facilitate management, abs(temperature) in the preceding example uses the abs() function to output the absolute value of the temperature.

The FROM statement contains the device name. You can specify a single device or all devices of a product to report messages. Product name_out_Device name indicates a single device. After the rule is executed, it applies only to this device. Product name_out_+ can match all devices under this product because the plus sign (+) represents all items in this level. After the rule is executed, it applies to all devices under the product.

The WHERE statement contains condition expressions and is used to filter fields and messages that meet conditions. In the preceding example, WHERE temperature > 20 or temperature < 15 is the filter criterion. Messages will be filtered out only when the temperature is higher than 20°C or lower than 15°C. For details about the condition expressions supported by the WHERE statement, see Table 4.

A rule engine also provides a variety of functions that you can use when you write SQL statements to diversify your data processing. You can use functions in SQL statements to obtain or process data. For example, "SELECT service, abs(temperature)" uses the abs(number) function. For details about the condition expression, see Table 5.