Using the data forwarding feature of the rules engine, IoT Platform can forward specified messages of topics to other IoT Platform topics and other Alibaba Cloud services. This topic describes how to create and configure a rule. The process is to create a rule, write a SQL statement for data processing, configure data forwarding destinations, and configure a forwarding destination for error messages.

Procedure

  1. In the left-side navigation pane of the IoT Platform console, click Rules.
  2. On the Data Forwarding Rules tab, click Create Data Forwarding Rule.
  3. Enter a Rule Name, select a Data Type, and then click OK.


    Parameter Description
    Rule Name Enter a unique rule name, which is used to identify the rule. A rule name can contain Chinese characters, English letters, digits, underscores (_) and hyphens (-), and must be 1 - 30 characters in length. A Chinese character counts as two characters.
    Data Type Select a data type for the data that this rule processes. Options: JSON and Binary.
    Note
    • The rules engine processes data based on topics. Therefore, you must select the format of the data in the topic that you want to process.
    • If the data type is Binary, the rule cannot process data from system-defined topics, and cannot forward data to Table Store and RDS instances.
    Rule description The description of the rule.
  4. After the rule has been successfully created, you are directed to the Data Forwarding Rule Details page. On this page, you must edit a SQL statement to process data, configure data forwarding destinations, and configure a destination for error messages.


    1. Click Write SQL, and then edit a SQL statement for data processing.

      In the following example, the statements can retrieve the contents of the deviceName field from the messages of the custom topics of all the devices under product test0306.

      Note You can use to_base64(*) to convert binary data to a base64 string. Built-in functions and conditions are also supported.


      The parameters to be configured are as follows. For more information, see SQL statements and Functions.

      Parameter Description
      Rule Query Expression The system will display the complete SQL statement here according to the values of Field, Topic, and Condition.
      Field

      Specify the message fields that this rule will retrieve from the message contents. For example, if you enter deviceName() as deviceName, the rule will retrieve the device names from the messages.

      For message content data, see Data Format.

      Topic

      Select the topics whose messages are to be processed by this rule.

      Topic types:

      • Custom: The messages are from custom topics. Wildcards + and # are supported when you specify custom topics. To learn how to use wildcards in topics, see Custom topics.
      • System: Only when the data type is JSON are system topics available. The messages are from system-defined topics, including messages of reporting properties and events, device lifecycle change, topological relationship change, and gateways reporting sub-devices. For message contents, see Data format.
      • Device Status: Only when the data type is JSON can you process device status messages, which are messages about devices connecting to and disconnecting from IoT Platform. For message contents, see Data format.
      Condition The condition for triggering the rule.
    2. Click Add Operation next to Data Forwarding. Configure a destination to which you want to forward the processed data. For more information about data forwarding examples, see the documents in Examples.
      Note A rule can have up to 10 data forwarding destinations.


      Currently, if data forwarding fails due to exceptions in the target Alibaba Cloud services, the rules engine retries three times: after one second, after three seconds, and after ten seconds. If all the retries fail, the message will be discarded. If you do not want to miss the forwarding failed messages, you can proceed to the next step: Add Misoperation. You can then add a destination for error messages.

    3. Click Add Misoperation next to Forward Error Data and then create an action to forward error messages about data forwarding failures to a specified target.


      Note
      • Error messages and device data cannot be forwarded to the same Alibaba Cloud service. For example, you cannot configure Table Store as the destination for both error messages and device data.
      • Rules engine retries three times if data fails to be forwarded to the specified destinations. If all the retries fail, an error message is forwarded according to this configuration.
      • If the error message fails to be forwarded, the rules engine does not retry sending the message.
      • Here, the term "error messages" refers only to messages that relate to errors resulting from exceptions in the target Alibaba Cloud instance.
      • You can add only one destination for error message forwarding.
      • 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":""
        }
        ]
        
        }

        Parameters in error messages:

        Parameter Description
        ruleName The name of the data forwarding rule.
        topic The source topic of the message.
        productKey The unique identifier of the product that the device belongs to.
        deviceName The device name.
        messageId The message ID that is generated by IoT Platform for this message.
        base64OriginalPayload The original data that has been Base64 encoded .
        failures Detailed messages about the failure. There may be multiple error messages if the rule forwards data to multiple destinations.
        actionType The target Alibaba Cloud service to which data fails to be forwarded.
        actionRegion The region of the target Alibaba Cloud service.
        actionResource The target resource.
        ErrorMessage Error message.
  5. After you complete all the configurations, go back to the Data Forwarding Rules tab of Rules page, and click Start corresponding to the rule to start this rule. Data will then be forwarded following this rule.


    You can also perform the following operations:
    • Click View, and then modify the rule configurations on the Data Forwarding Rule Details page.
    • Click Delete to delete this rule.
      Note Rules that are in a running state cannot be deleted.
    • Click Stop to disable this rule.