You can use the rules engine of IoT Platform to forward data from specified topics to other topics or other Alibaba Cloud services.This article describes how to create a parser, associate the parser with a data source and a data destination, and then configure the parser script.

Prerequisites

A data source and a data destination are created. For more information, see the following articles:

Create a parser

  1. Log on to the IoT Platform console.
  2. In the left-side navigation pane, choose Rules > Data Forwarding.
  3. On the Parser tab, click Create Parser.
  4. Enter a parser name and description, and then click OK.
    The name must be 1 to 30 characters in length, and can contain letters, digits, underscores (_), and hyphens (-).
    The Parser Details page appears. You can click Edit in the upper-right corner to modify the name and description of the parser.

Associate the parser with the data source and data destination

  1. On the Parser Details page, click Associate Data Source.
  2. In the dialog box that appears, select the created data source from the Data Source drop-down list, and then click OK.
    Associate Data Source
  3. On the Parser Details page, click Data Destination.
  4. Click Associate Data Destination. In the dialog box that appears, select the created data destination from the Data Destination drop-down list, and then click OK.
  5. In the Error Data Destination section, click Associate Data Destination to specify an error data destination. If retries to forward data fail, error messages are sent to the specified destination.
    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 error message.

Configure and start a parser

  1. On the Parser Details page, click Parser.
  2. In the code editor, enter a script. For more information about how to write a script, see Sample script.
  3. Click Debugging. In the dialog box that appears, select a product and a device, specify a topic, and enter payload data to verify whether the script can run properly.
    • Topic: The data format of the topic must match the parsing logic of the script.
    • Payload Data: The format of the input data must match the data format of the rules engine.
      • If you use a custom topic, the payload data is the original data that is submitted by a device.
      • For information about the data formats of basic communication topics and TSL communication topics, see Data formats.
    The variables declared in the script and the data forwarding functions that are implemented are displayed on the Result tab.

    If the debugging is successful, the data is written to the destination cloud service. You can log on to the console of the destination cloud service and view the forwarded data.

  4. Click Publish.
  5. On the Parser tab of the Data Forwarding page, find the parser and click Start in the Actions column. After the parser is started, data is forwarded based on the specified logic of the script.
    You can also perform the following operations:
    • Click View to go to the Parser Details page. On this page, you can modify the settings of the parser.
    • Click Delete to delete the parser.
      Note You cannot delete a parser that is in the Running state.
    • Click Stop to stop data forwarding.

Import previous rules

You can import the data forwarding rules that are configured in the previous version, and then reconfigure the data source, data destination, and parser script. To import previous rules, perform the following steps:

  1. On the Parser tab, click Import Previous Rules.
  2. In the right-side panel, select the rules that you want to import and click OK.
    After the rules are imported, the rules are displayed in the parser list and renamed in the format of "connector_" +${Previous rule name}.

    On the Parser Details page, you can modify the name of the parser. You can also reconfigure the data source, data destination, and parser script.