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


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

Create a parser

  1. Log on to the IoT Platform console.
  2. On the Overview page, select an environment, find the instance that you want to manage, and click the instance ID or instance name.
    Important This step is required only if Enterprise Edition instances are available. If the Enterprise Edition instances are unavailable in the region that you selected, skip this step. For information about supported regions and instances, see Overview.
  3. In the left-side navigation pane, choose Message Forwarding > Data Forwarding.
  4. On the Data Forwarding page, click Go to New Version in the upper-right corner to go to the new version.
    Note If you have performed this step, the Data Forwarding page of the new version appears after you choose Rules > Data Forwarding.
  5. On the Parser tab, click Create Parser.
  6. Enter a name and a description for the parser, and then click OK.
    The name must be letters, digits, underscores (_), and hyphens (-)..
    The Parser Details page appears. You can click Edit in the upper-right corner to change 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 data source that you created from the Data Source drop-down list and click OK.
    Associate Data Source
  3. On the Parser Details page, click Data Destination.
    Data destination
  4. Click Associate Data Destination. In the dialog box that appears, select the data destination that you created from the Data Destination drop-down list and click OK.
    Associate Data Destination
  5. In the Error Data Destination section, click Associate Data Destination to specify an error data destination. If retries that are performed to forward data fail, error messages are sent to the specified destination.
    • 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 (OTS) 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 parsing script failures.
    If a message fails to be forwarded to a cloud service, IoT Platform retries to forward the message. If the retry fails, an error message is forwarded based on the error operation that you specify for data forwarding.

    Sample error message:


    The following table describes the parameters of error messages.

    ruleNameThe name of the monitoring rule.
    topicThe source topic of the message.
    productKeyThe ProductKey of the product.
    deviceNameThe DeviceName of the device.
    messageIdThe ID of the message that is sent from IoT Platform.
    base64OriginalPayloadThe Base64-encoded raw data.
    failuresThe error details. Multiple errors may occur.
    actionTypeThe type of the failed operation.
    actionRegionThe region where the error occurred.
    actionResourceThe destination service for which the error occurred.
    errorMessageThe 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.
    For more information about how to use data forwarding functions and scripts, see Data forwarding examples.
  3. Click Debugging. In the dialog box that appears, select a product and a device, specify a topic, and then enter payload data to check whether the script runs as expected.
    • 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. Use the specified conditions in the preceding formula.
      • 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 executed are displayed on the Result tab.

    If 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.

Import previous rules

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

  1. On the Parser tab, click Import Previous Rules.
    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 "connector_" +${Previous rule name} format.

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

    Important The tag value of a device is a string. The attribute() function returns a string. If you want to use the returned result to perform a mathematical calculation, convert the data type of the result to the required data type.

More operations

On the Parser tab of the Data Forwarding page, you can perform the operations that are described in the following table.

Warning If one or more of your applications need to use the device data that is forwarded by using a rule but you delete or disable the parser, or delete the data forwarding destination of the rule, your services may become unavailable or your business may be affected. Proceed with caution.
ViewClick View in the Actions column to go to the parser details page. On parser details page, you can modify the settings of the parser. For example, you can modify or delete the data source topic or data forwarding destination.
DeleteClick Delete in the Actions column to delete the parser.
Important You cannot delete a parser that is in the Running state.
StopClick Stop in the Actions column to disable the parser.