All Products
Document Center

IoT Platform:Submit a message parsing script

Last Updated:Apr 26, 2023

After a device submits a message in a custom format by using a custom topic that has the ?_sn=default parsing tag, IoT Platform runs a message parsing script to convert the custom data of the received message to a JSON struct, and then forwards the converted data to a subsequent business system. This topic describes how to submit a message parsing script to parse messages in a custom format.

Usage notes and limits

  • Parsing custom topics is supported only in the China (Shanghai) and Japan (Tokyo) regions.

  • IoT Platform parses messages only if the messages are submitted by devices that are connected to IoT Platform over Message Queuing Telemetry Transport (MQTT).

  • IoT Platform parses messages only if the messages are submitted by devices to IoT Platform, and does not parse data that is sent from IoT Platform to the devices.

  • IoT Platform parses the payloads of messages that are submitted to IoT Platform and returns the payloads of the parsed messages.

  • When IoT Platform parses messages, the parsed messages reside in the same topic. For example, a device sends messages to the /${productKey}/${deviceName}/user/update topic, and the parsed data still resides in this topic.

Parsing tag

When you configure a device to publish messages to a custom topic, append the parsing tag ?_sn=default.


IoT Platform parses messages only if the custom topic to which the messages are sent has the parsing tag.

For example, to parse the messages that are sent by a device to the /${productKey}/${deviceName}/user/update topic into JSON-formatted data, you must specify the following topic when you configure the device: /${productKey}/${deviceName}/user/update?_sn=default.


When you create a custom topic in the IoT Platform console, do not append the parsing tag to the topic.


  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.


    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 Devices > Products.

  4. On the Products page, find the product and click View in the Actions column.

  5. On the product details page, click the Message Analysis tab.

  6. Select a script language and write a script in the Edit Script field.


    Required function

    Sample code

    JavaScript (ECMAScript 5)


    JavaScript sample script

    Python 2.7


    Python sample script

    PHP 7.2


    PHP sample script


    If you set the Data Type parameter of the product to Custom, you must also write a script to parse Thing Specification Language (TSL) data. For information about how to write a script to parse TSL messages, see Submit a script to parse TSL data.

  7. Test the script.

    1. On the Input Simulation tab, set the Simulation Type parameter to Custom and select a device and a topic.

    2. Enter the simulated data that a device reports and click Run.

  8. After you confirm that the script is valid, click Submit to submit the script to IoT Platform.

(Optional) Update the message parsing script

After the message paring script is submitted, you can modify or delete the script on the Message Analysis tab, and then test and submit the new script according to the steps described in this topic. After the script is submitted, it will take effect on all the existing devices of the product in about a minute. It will also take effect on newly added devices of the product.

  • After the script is modified and resubmitted, make sure that the code related to the message parsing service is also modified. Otherwise, business interruptions may occur.

  • After the script is deleted, the message parsing service becomes unavailable, which may interrupt your business.

Proceed with caution.