IoT Platform:Configure a parser

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.
   
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 retries that are performed to forward data fail, error messages are sent to the specified destination.
   Important

   • 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:

   {
         "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 for 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.
   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.
   
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.