IoT Platform:Configure a parser

Create a parser

1. Log on to the IoT Platform console.

2. On the Overview page, click All environment. On the All environment tab, find the instance that you want to manage and click the instance ID or instance name.

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. Configure the Parser Name and Parser Description parameters and click OK.

   The parser name must be 1 to 30 characters in length and can contain letters, digits, underscores (_), and hyphens (-).

   In the dialog box that appears, click Edit to go to the parser details page. In the upper-right corner of the parser details page, you can click Edit 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.

   

3. On the parser details page, click 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.

   

5. In the Error Data Destination section, click Associate Data Destination to specify an error data destination. If data forwarding retries fail, error messages are sent to the specified error data destination.

   Important

   • You can add only one error operation for each data forwarding 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 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:

   {
      "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 monitoring 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 where 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 Script.

2. In the code editor, enter a script. For information about how to modify a script, see Script syntax.

   For information about how to use data forwarding functions and scripts, see Data forwarding examples.

3. Click Debugging. In the panel 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 input data must comply with the data format of the rules engine. Take note of the following items:

     • 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 Thing Specification Language (TSL) communication topics, see Data formats.

   The variables that are 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. After you complete all the settings, go back to the Parser tab of the Data Forwarding page and click Start to the right of the parser that you configured. After you start the parser, data is forwarded based on the parsing script.

Import existing 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 parsing script. To import the data forwarding 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.

   The imported 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 or reconfigure the data source, data destination, and parsing 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.

Additional operations

The following table describes other operations that you can perform on the Parser tab of the Data Forwarding page.