--- title: "MQTT System Requests" slug: "mqtt-system-requests" updated: 2026-09-18T16:33:02Z published: 2026-09-18T16:33:02Z canonical: "learn.servitly.com/mqtt-system-requests" --- > ## Documentation Index > Fetch the complete documentation index at: https://learn.servitly.com/llms.txt > Use this file to discover all available pages before exploring further. # MQTT System Requests The Servitly Thing Connector (STC) provides a way to get or update metadata (e.g., Thing, Customer) by using the opened MQTT channel. A predefined set of MQTT messages allows your products to make system requests in order to: - Get the product's local time. - Get the location where the product is installed. - Get the customer to whom the product belongs. - Get the partner who provides the product or service. - Update a recipe. - Update the Connection Status MQTT clients (products, machines) can exchange these special messages along the following MQTT topics: - */_systemRequest:* The topic where to publish requests. - */_systemResponse:* The topic to listen to for the responses. > Note that, the MQTT is a pub/sub protocol, so messages are processed asynchronously. The BASE_TOPIC is structured as follows: ```plaintext // without thing mapping path / // with thing mapping path // ``` ## Get Thing Local Time Gets the local date/time for the thing, taking into account the time zone of the location where the thing is installed. ```json Topic: /_systemRequest { "action": "read", "data": { "property": "thingDate", "format": "yyyyMMddHHmm" } } ``` The cloud will respond with the following message. ```json Topic: /_systemResponse { "action": "write", "data": { "property": "thingDate", "value": "201702121940" } } ``` If the request does not contain the desired *format*, the response value will be in milliseconds. If the location does not define the time zone, the response will be UTC. For more details about how to specify the date *format (e.g.* `yyyy-MM-dd HH:mm`*)*, refer to this [article](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html). ## Get Thing Details Gets the details of the thing registered within the cloud. ```json Topic: /_systemRequest { "action": "read", "data": { "property": "thingDetails" } } ``` The cloud will respond with the thing details. ```json Topic: /_systemResponse { "action": "write", "data": { "property": "thingDetails", "value": { "id": "123456789", "name": "Oven-123", "serialNumber": "123124234", "gpsPosition": "42.56789,23.45645", "properties": { "foo": "bar",                "abc": 123,                "yxz": true }, "timeZone": { "offset": 3600000, "dstStartDay": 89, "dstEndDay": 299, "posix": "CET-1CEST,M3.5.0,M10.5.0/3" } } } } ``` ## Get Location Details Gets the details of the location where the thing is installed. ```json Topic: /_systemRequest { "action": "read", "data": { "property": "locationDetails" } } ``` The cloud will respond with the location details. ```json Topic: /_systemResponse { "action": "write", "data": { "property": "locationDetails", "value": { "name": "Sweet Milan", "gpsPosition": "42.56789,23.45645", "properties": { "address": "via Cairoli 12", "city": "Milan",                "foo": "bar",                "abc": 123,                "yxz": true }, "timeZone": { "offset": 3600000, "dstStartDay": 89, "dstEndDay": 299, "posix": "CET-1CEST,M3.5.0,M10.5.0/3" } } } } ``` ## Get Customer Details Gets the details of the customer who owns the thing. ```json Topic: /_systemRequest { "action": "read", "data": { "property": "customerDetails" } } ``` The cloud will respond with the customer details. ```json Topic: /_systemResponse { "action": "write", "data": { "property": "customerDetails", "value": { "name": "Sweet Bakery", "code": "C56066896", "properties": { "foo": "bar",                "abc": 123,                "yxz": true } } } } ``` ## Get Partner Details Gets the partner providing services to the location where the thing is installed. ```json Topic: /_systemRequest { "action": "read", "data": { "property": "partnerDetails" } } ``` The cloud will respond with the partner details. ```json Topic: /_systemResponse { "action": "write", "data": { "property": "partnerDetails", "value": { "name": "Ovens Maintenance", "code": "P24384", "properties": { "phoneNumber": "+39 02 25689711",                "foo": "bar",                "abc": 123,                "yxz": true } } } } ``` ## Recipe Update In case you are managing [recipes](https://help.servitly.com/hc/en-us/articles/10854999105693), you can trigger the recipe update from the connected product. ```json Topic: /_systemRequest { "action": "saveRecipe", "data": { "recipeName": "Package-1", "recipeDescription": "The recipe description", "sharedRecipe": false, "parameters": { "temperatura": 22, "spessore": 30, "metriDaAvvolgere": 1 } } } ``` The DPS backend searches for a recipe with the given name and, if it is missing, creates a new one. The recipe is updated with the given description and sharing flag (if true, the recipe is saved at the customer level). The node named `parameters` contains the set of parameter names and values to be saved in the recipe. Values are encoded by using the JSON standard encoding. ## Connection Status Update You can force the Connection Status of the thing by providing a status code and the start and end timestamps. ```json Topic: /_systemRequest {  "action":"updateConnectionStatus",  "data": {    "startTimestamp": 123456789,    "endTimestamp": 123456789,    "status": 1  } } ``` When the DPS backend receives the given system requests, the following tasks are performed: 1. Given the period (start/end timestamps), the last connection status value is retrieved. 2. Given the period (start/end timestamps), all the saved connection status values are deleted. 3. The provided status (e.g., 1) is saved to the start timestamp. 4. The last retrieved value (step 1) is stored in endTimestamp if it differs from the provided one (step 3); if it is null, 0 (OFFLINE) is stored instead. Note that any insight or event based on the Connection Status metric is NOT recomputed in case the provided period is in the past.