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 article describes how to configure a data forwarding rule. To configure a data forwarding rule, perform the following steps: create a rule, write an SQL statement for data processing, set a data forwarding destination, and set a destination for error messages if data forwarding fails.

Procedure

  1. Log on to the IoT Platform console.
  2. In the left-side navigation pane, choose Rules > Data Forwarding.
  3. On the Data Forwarding page, click Create Rule.
  4. Set the parameters as required and click OK.
    Parameter Description
    Trigger Name The name of the rule. The rule name must be 1 to 30 characters in length, and can contain letters, digits, underscores (_), and hyphens (-).
    Data Type The data format that the rules engine can process. Valid values: JSON and Binary.
    Note
    • The data forwarding feature 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 rule cannot be used to process messages from basic communication topics and Thing Specification Language (TSL) communication topics. The rule also cannot be used to forward data to Tablestore or ApsaraDB RDS.
    Rule Description The description of the rule.
  5. After the rule is created, the Data Forwarding Rule page appears. You must write an SQL statement to process messages, set a data forwarding destination, and set a destination to which error messages are forwarded.
    1. Click Write SQL to write an SQL statement. This SQL statement allows you to process 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 (Optional) parameters.
      Variable

      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 more information about the functions that can be used in the field, see Functions.

      Note Data of basic communication topics and TSL communication topics is in the Alink JSON format. The data is parsed based on the corresponding TSL model before the data is forwarded to the rules engine. For more information about data parsing, see Data forwarding procedure. For more information about the formats of parsed data, see Data formats. When you write an SQL statement, specify the fields based on the format of parsed data.
      Topic

      The source topic of the message to be processed. This parameter follows the FROM keyword in the SQL statement. For more information about optional topics, see the following Topics table.

      Notice If the Data Type parameter of the rule is Binary, set this parameter to Custom.
      Conditions (Optional) The trigger condition of the rule. This parameter follows the WHERE keyword in the SQL statement.
      Table 1. Topics
      Topic Description References
      Custom The topic that is used to forward data of custom formats. The topic format is the same as that of a custom topic. Format: /${productKey}/${deviceName}/user/${TopicShortName}.

      ${TopicShortName} specifies a custom topic category, which indicates the suffix of the custom topic.

      The value can contain wildcard characters, including plus signs (+) and number signs (#).

      • All equipment (+): indicates all devices of the specified product.
      • /user/#: indicates all topics of the specified device.
      Custom topics
      Device Status Change Notification The topic that is used to forward notifications when the status of a device changes between online and offline. Format: /as/mqtt/status/${productKey}/${deviceName}. Submit device status
      TSL Data Reporting The following topics are available:
      • /${productKey}/${deviceName}/thing/event/property/post: This topic is used to forward device properties.
      • /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post: This topic is used to forward device events.
      • /${productKey}/${deviceName}/thing/downlink/reply/message: This topic is used to forward messages that a device sends to respond to IoT Platform commands.
      The preceding topics correspond to the following device topics:
      • /sys/{productKey}/{deviceName}/thing/event/property/post: This topic is used to submit device properties.
      • /sys/{productKey}/{deviceName}/thing/event/{tsl.event.identifier}/post and /sys/{productKey}/{deviceName}/thing/event/{tsl.functionBlockId}:{tsl.event.identifier}/post: These topics are used to submit device events.
      Device Changes Throughout Lifecycle The topic that is used to forward notifications when a device is created, deleted, disabled, or enabled. Format: /${productKey}/${deviceName}/thing/lifecycle Submit lifecycle changes
      Sub-Device Data Report Detected by Gateway The topic that is used to submit and forward the information about a new sub-device when a gateway detects the sub-device. This topic is specific to gateways. Format: /${productKey}/${deviceName}/thing/list/found Submit information about detected sub-devices
      Device Topological Relation Changes The topic that is used to forward notifications when topological relationships between sub-devices and the gateway are created or deleted. This topic is specific to gateways. Format: /${productKey}/${deviceName}/thing/topo/lifecycle. Submit topology changes
      The preceding topic corresponds to the following topic that is used to submit device data: /sys/{productKey}/{deviceName}/thing/topo/change. Notify gateways of changes of topological relationships
      Device tag change The topic that is used to forward notifications when device tags are changed. Format: /${productKey}/${deviceName}/thing/deviceinfo/update. Submit device tag changes
      The preceding topic corresponds to the following topic that is used to submit device data: /sys/{productKey}/{deviceName}/thing/deviceinfo/update. Report tags
      TSL Historical Data Reporting The following topics are available:
      • /${productKey}/${deviceName}/thing/event/property/history/post: This topic is used to forward historical properties.
      • /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/history/post: This topic is used to forward historical events.
      The preceding topics correspond to the following topic that is used to submit historical TSL data: /sys/{productKey}/{deviceName}/thing/event/property/history/post. Submit historical TSL data
      Device status notification The following topics are available:
      • /${productKey}/${deviceName}/ota/upgrade: This topic is used to forward over-the-air (OTA) update results.
      • /${productKey}/${deviceName}/ota/progress/post: This topic is used to forward update progresses.
      The preceding topics correspond to the following topic that is used to submit update progresses: /ota/device/progress/${YourProductKey}/${YourDeviceName}. Submit the update progress to IoT Platform
      Submit a module version number The topic that is used to forward notifications when the version number of an OTA module for a device is changed. Format: /${productKey}/${deviceName}/ota/version/post. Submit OTA module versions
      The preceding topic corresponds to the following topic that is used to submit the version number of an OTA module: /ota/device/inform/${YourProductKey}/${YourDeviceName}. Submit OTA module versions to IoT Platform
      Batch status notification The topic to which IoT Platform sends notifications when the status of an OTA update batch changes. Format: /${productKey}/${packageId}/${jobId}/ota/job/status. Submit the status data of OTA update batches
    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 configure the data forwarding feature, see related topics in the Data forwarding examples directory.
      Note You can create a maximum of 10 data forwarding operations for each rule.
      If data forwarding fails due to exceptions in the destination cloud service, IoT Platform performs one of the following operations:
      • When IoT Platform forwards data to cloud services such as Message Queue for Apache RocketMQ, ApsaraDB RDS, and Time Series Database (TSDB), these cloud services may be inaccessible due to the changes of their resources. In this case, IoT Platform stops forwarding data and changes the status of the related rule to Abnormal. Then, you must set a new destination for data forwarding.
      • For other exceptions, IoT Platform retries three times with intervals of 1 second, 3 seconds, and 10 seconds. The retry policy may vary based on the scenarios. If all the three retries fail, the message is discarded. If you have high requirements for message reliability, you can add an error operation and forward error messages to other cloud services.
    3. In the Forward Error Data section, click Add Error Operation. Set the parameters to forward error messages to the specified destination after all retries fail.
      Notice
      • You can add only one error operation for each rule.
      • 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 Tablestore at the same time.
      • If an error message fails to be forwarded, no retry is performed.
      • Error messages are generated only if the rules engine fails to forward data due to the issues of other cloud services.
      If a message fails to be forwarded to a cloud service, IoT Platform tries again. If the retry fails, an error message is forwarded based on the configured error operation for data forwarding.

      Sample error message:

      {
            "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 describes the parameters of error messages.

      Parameter Description
      ruleName The name of the rule.
      topic The source topic of the message.
      productKey The ProductKey of the product.
      deviceName The deviceName of the device.
      messageId The ID of the message that is sent from IoT Platform.
      base64OriginalPayload The Base64-encoded raw data.
      failures The error details. Multiple errors may occur.
      actionType The type of the failed operation.
      actionRegion The region in which the error occurred.
      actionResource The destination service in which the error occurred.
      errorMessage The network error message.
  6. Go to the Data Forwarding page. Find the rule that you configured and click Start in the Actions column. After the rule is enabled, data is forwarded based on the rule.
    You can also perform the following operations:
    • Click View to go to the Data Forwarding Rule page. Then, modify the settings of the rule.
    • Click Delete to delete the rule.
      Note You cannot delete a rule that is in the Running state.
    • Click Stop to disable the rule.