When a device sends a message in a custom format to a custom topic that includes the parsing tag ?_sn=default, IoT Platform invokes a message parsing script. The script transforms the custom data into a JSON struct and then forwards the data to downstream business systems. This topic describes how to submit a message parsing script in the IoT Platform console to parse data that is in a custom format.
Usage and limits
Only devices connected over Message Queuing Telemetry Transport (MQTT) support custom topic message parsing.
The script parses only the data that devices report to IoT Platform. It does not parse data sent from the cloud to devices.
The script parses the payload of an upstream message and returns the parsed payload.
The topic of the message remains unchanged after parsing. For example, a message sent to
/${productKey}/${deviceName}/user/updateremains in the same topic after it is parsed.
Parsing tag
When you configure the device, add the parsing tag ?_sn=default to the end of the custom topic used for publishing messages.
IoT Platform parses only the messages that are published to topics that contain the parsing tag.
For example, if a message sent to the topic /${productKey}/${deviceName}/user/update must be parsed into the JSON format, you must configure the topic as /${productKey}/${deviceName}/user/update?_sn=default when you develop the device-side logic.
When you create a custom topic in the IoT Platform console, do not add the parsing tag to the topic definition.
Procedure
Log on to the IoT Platform console.
On the Overview page, find the instance that you want to manage and click the instance ID or instance name.
In the navigation pane on the left, choose .
On the Products page, find the desired product and click View.
On the Product Details page, click the Message Parsing tab.
Select a scripting language. Then, in the Edit Script section, enter your script in the code editor.
Supported scripting languages
Function to define
Sample code
JavaScript (ECMAScript 5)
transformPayload()
Python 2.7
transform_payload()
PHP 7.2
transformPayload()
NoteIf the Data Format for the product is Pass-through/Custom, you must also write a script to parse Thing Specification Language (TSL) model messages. For more information, see Submit a TSL model message parsing script.
Test the script.
In the Input Simulation section, set Simulation Type to Custom, and then select a device and a topic.
Enter the simulated data that is reported by the device and click Execute.
After you confirm that the script works as expected, click Submit to commit the script to IoT Platform.
Optional: Update the message parsing script
After you submit a message parsing script, you can return to the Message Parsing tab to modify or delete the script. Follow the steps in the Procedure section to test and submit your changes. The changes take effect in about one minute. The updated script applies to all existing and new devices that are associated with the product.
If you modify and resubmit the script, you must also update the related business logic for the message parsing service. Otherwise, your services may be disrupted.
If you delete the script, the message parsing service for devices that are associated with the product becomes unavailable. This may disrupt your services.
Proceed with caution.
References
- To learn basic information such as the message parsing flow, see What is message parsing?.
For information about how to parse TSL model data in Pass-through/Custom format, see Submit a TSL model message parsing script.
- For information about calling an API to send messages to a device, see APIs for TSL models and APIs for message communication.