Updated on 2023-07-26 GMT+08:00

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. The device integration component transmits 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.

Creating a Rule

  1. Log in to the ROMA Connect console. On the Instances page, click View Console next to a specific 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

    Application Name

    Select the integration application to which the rule belongs.

    Rule Name

    Enter a rule name. It is recommended that you enter a name based on naming rules to facilitate search.

    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.

      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. To facilitate understanding, a rule can be considered as an SQL statement and JSON can be considered as a table. Key is the column of the table, and Value is the column value of the table. 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 statement, From statement, and Where statement. 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.

Table 4 Condition expression

Operator

Description

Example

=

Equal

color = 'red'

<>

Not equal to

color <>'red'

and

And

color = 'red' and switch = 'on'

or

Or

color = 'red' or switch = 'on'

( )

Represent a whole.

a>1 and (b<1 or b>5). The judgment of the OR logic is executed first, and then the judgment of the AND logic is executed.

in

Only enumeration is supported. Subquery is not supported.

where a in(1,2,3). The example of where a in(select xxx) is not supported.

+

Addition

a in (3,2,3+8)

-

Subtraction

13 – 2

/

Divide

25 / 5

*

Multiple

2 * 8

%

Obtains the remainder.

10 % 2

<

Less than

1 < 3

<=

Less than or equal to

1 <= 3

>

Greater than

8 > 3

>=

Greater than or equal to

8 >= 3

CASE ... WHEN ... THEN ... ELSE ...END

Case expression (Nested expression is not supported.)

case a when 3 then 'hello' when 4 then 'bye' end FROM item WHERE a >= b+c"

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.

Table 5 SQL functions

Function

Description

abs(number)

Returns the absolute value.

sin(n)

Returns the arc sine of the n value.

cos(number)

Returns the arc sine of the number value.

asin(number)

Returns the arc sine of the number value.

sinh(n)

Returns the hyperbolic cosine of the n value.

cosh(number)

Returns the hyperbolic cosine of the number value.

tan(n)

Returns the tangent of the n value.

tanh(n)

Returns the hyperbolic tangent of the n value.

lower(string)

Returns the lowercase character string.

upper(string)

Returns the uppercase letters.

power(n,m)

Return the value of n raised to the power of m.

rand()

Returns a random number ranging from 0 to 1.

mod(n, m)

Returns the remainder of n%m.

log(n, m)

Returns the natural logarithm. If the value of m does not need to be transferred, log(n) is returned.

exp(number)

Returns the specified power of a number.

floor(number)

Returns the closest integer, whose value is less than or equal to the floating point number.

concat(string1, string2)

String concatenation. For example, concat(field,a) outputs fielda.

replace(source, substring, replacement)

Replaces the value of a target column. For example, replace(field,'iel','oo') outputs food.

topic()

Returns the information about the entire topic. For example, Topic: /abcdef/ghi. Use the topic() function to return /abcdef/ghi.

endswith(input, suffix)

Checks whether the input value ends with the suffix.

timestamp(format)

If no parameter is specified, the default timestamp is returned. If a parameter is specified, the timestamp in the specified format is returned. For example, timestamp() = 1553572557420.

timestampUtc()

Obtains the UTC time of the system. If no parameter is specified, the current system time in milliseconds is returned. If one parameter is specified, the parameter is used as the format parameter for time formatting.

serviceId()

Returns the service ID corresponding to the message. The parameter in this function must be left unspecified.

clientId()

Obtains the client ID of the current topic. The parameter in this function must be left unspecified.