You can use the rules engine of IoT Platform to forward data from a specified topic to other topics or other Alibaba Cloud services. This topic describes how to configure a data forwarding rule. To configure a data forwarding rule, follow these steps: create a rule, write an SQL statement for data processing, set a data forwarding destination, and set a destination for error messages when data forwarding fails.

Procedure

  1. In the left-side navigation pane of the IoT Platform console, choose Rules > Data Forwarding.
  2. On the Data Forwarding page, click Create Rule.
  3. Set the parameters and click OK.
    Parameter Description
    Rule Name The name of the rule. The rule name is used to identify a rule and must be unique. The name must be 1 to 30 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). Each Chinese character is counted as two encoding characters.
    Data Type The data format that the rules engine can process. Valid values: JSON and Binary.
    Note
    • The rules engine processes data based on topics. You must select the format of the data in the topics that you want to process.
    • If you select Binary, the rules engine cannot process messages from system-defined topics, and cannot forward data to Table Store or ApsaraDB for RDS.
    Rule Description The description of the rule.
  4. After the rule is created, the Data Forwarding Rule page appears. You must edit the SQL statements for data processing, set a data forwarding destination, and set a destination to which error messages are sent.
    1. Click Write SQL to write an SQL statement for processing message fields.

      For more information about how to write SQL statements, see SQL statements and Functions.

      Parameter Description
      Rule Query Expression The SQL statement. It is automatically generated based on the values that you specify for the Field, Topic, and Conditions parameters.
      Field

      The field of the message to be processed. This parameter follows the SELECT keyword in the SQL statement.

      For example, if you enter deviceName() as deviceName, the deviceName field in the message is selected. For information about the functions that can be used in the field, see Functions.

      Note Data in system-defined topics is in the Alink JSON format. The data is parsed based on Thing Specification Language (TSL) before being forwarded to the rules engine. For more information about data parsing, see Data forwarding procedure. For information about the data formats after parsing, see Data formats. When you write an SQL statement, specify the fields based on the data format after parsing.
      Topic

      Select the source topic of the message to be processed. This parameter follows the FROM keyword in the SQL statement.

      Valid options:

      • Custom: Custom topics support wildcard characters, such as plus signs (+) and number signs (#).
        • All equipment (+): all devices of the specified product.
        • /user/#: all topics of the specified device.

        If you specify a custom topic, you must set the topic permission to Publish for the device. For more information about topics and wildcards, see Custom topics.

      • Device Status Change Notification: indicates the topic that is used to send notifications when the device goes online and offline. This option is available when the data type of the rule is JSON.
      • TSL Data Report: indicates the topics that are used to submit device properties and events. This option is available when the data type of the rule is JSON.

        Valid values:

        • thing/event/property/post: the topic for the device to submit property data.
        • thing/event/${tsl.identityId}/post: the topic for the device to submit event data.
        • thing/downlink/reply/message: the topic for the device to respond to commands that are issued from IoT Platform.
      • Device Changes Throughout Lifecycle: indicates the topic that is used to send notifications when the device is created, deleted, disabled, and enabled. This option is available when the data type of the rule is JSON.
      • Sub-Device Data Report Detected by Gateway: indicates the topic that is used to submit the information of a new sub-device when the gateway detects the sub-device. This option is available when the data type of the rule is JSON.
      • Device Topological Relation Changes: indicates the topic that is used to send notifications when topological relationships between sub-devices and the gateway are created and deleted. This option is available when the data type of the rule is JSON.
      • Historical TSL Data Report: indicates the topic that is used to submit historical properties and events of the device. This option is available when the data type of the rule is JSON.
      • Firmware Upgrade Status Notification: indicates the topic that is used to submit firmware update results. This option is available when the data type of the rule is JSON.
      • Edge Plug and Play Message: indicates the topic that is used to submit pass-through data from Link IoT Edge. This option is available when the data type of the rule is JSON.
      Conditions (Optional) The trigger condition of the rule. This parameter follows the WHERE keyword in the SQL statement.
    2. In the Data Forwarding section, click Add Operation to set the Alibaba Cloud service to which you want to forward the processed data. For more information about how to forward data to different Alibaba Cloud services, see the Data Forwarding Examples topic.
      Note You can create up to 10 data forwarding operations for each rule.

      If the data forwarding process fails due to exceptions in the destination cloud service, IoT Platform retries three times with an interval of 1 second, 3 seconds, and 10 seconds, respectively. The retry policy may vary based on the scenarios. If all of the three retries fail, the message is discarded. If you require high reliability for messages, you can proceed to the next step: Add Error Operation. You can add error operations to forward error messages to other Alibaba Cloud services after all retries fail.

    3. Click Add Error Operation in the Forward Error Data section. Set the parameters to forward error messages to the specified destination after all retries fail.
      Note
      • A normal operation and an error operation cannot forward messages to the same destination. For example, normal data and error data cannot be forwarded to Table Store at the same time.
      • If a message fails to be forwarded to a cloud service, the system tries again. If the retry fails, an error message is forwarded based on the configurations of the error operation for data forwarding.
      • If an error message fails to be forwarded, no retry is performed.
      • The error messages are applicable only to errors caused by problems of other cloud services.
      • You can add only one error operation for each rule.

      Error message format:

      {
            "ruleName":"",
            "topic":"",
            "productKey":"",
            "deviceName":"",
            "messageId":"",
            "base64OriginalPayload":"",
            "failures":[
              {
                "actionType":"OTS",
                "actionRegion":"cn-shanghai",
                "actionResource":"table1",
                "errorMessage":""
              },
              {
                "actionType":"RDS",
                "actionRegion":"cn-shanghai",
                "actionResource":"instance1/table1",
                "errorMessage":""
              }
            ]
      
      }

      The following table lists the parameters of error messages.

      Parameter Description
      ruleName The name of the rule.
      topic The source topic of the message.
      productKey The key of the product.
      deviceName The name of the device.
      messageId The ID of the message that is received from IoT Platform.
      base64OriginalPayload The raw data after Base64 encoding.
      failures The error details. Multiple errors may occur.
      actionType The type of the operation that failed.
      actionRegion The region in which the error occurred.
      actionResource The target service in which the error occurred.
      errorMessage The error message.
  5. After you complete all settings, return to the Data Forwarding page. Find the required rule, and click Start. Data is forwarded based on the rule.
    You can also perform the following operations:
    • Click View to go to the Data Forwarding Rule page, and modify the settings of the rule.
    • Click Delete to delete the rule.
      Note You cannot delete a rule that is running.
    • Click Stop to disable the rule.