UUID and TUID Mapping

Map legacy Thingsee TUIDs to Haltian IoT device UUIDs when migrating integrations.

Thingsee IoT uses the TUID to identify a physical device. Haltian IoT uses the device UUID as the canonical identifier in the Service API, Stream API MQTT topics, and Data API exports. Use this guide to map the identifiers while you migrate an integration that still uses TUIDs.

Build Your Mapping List

At the start of the migration, query the Service API for the devices in your organization and store the identifiers needed by your integration. The following query returns a compact mapping list.

query DeviceIdentifierMappings($limit: Int!, $offset: Int!) {
  devices(limit: $limit, offset: $offset, orderBy: { id: ASC }) {
    id
    name
    externalId
    identifiers {
      tuid
      vendorSerial
      customerLabelId
      wirepasNodeId
    }
  }
}

Example variables:

{
  "limit": 100,
  "offset": 0
}

Store the id value as the UUID and use it as the unique key in your mapping store. Store identifiers.tuid as an optional cross-reference; it can be null for devices without a legacy Thingsee identity.

Export All Mappings

Use limit, offset, and orderBy to retrieve a complete, stable mapping list:

  1. Start with offset set to 0.
  2. Store each device mapping returned by the query.
  3. Increase offset by limit for the next request.
  4. Repeat until a response contains fewer devices than limit.
  5. Keep orderBy: { id: ASC } on every request so the result order stays stable.

Run a complete export during a quiet inventory period where possible. Device changes during an export can still cause duplicate or missed rows. De-duplicate results by UUID and refresh the mapping after device inventory changes.

Look Up a Legacy Device

Use this query when you need to resolve a TUID to its Haltian IoT UUID.

query DeviceByTuid($tuid: String!) {
  devices(where: { identifiers: { tuid: { _eq: $tuid } } }) {
    id
    name
    identifiers {
      tuid
      vendorSerial
    }
  }
}

{
  "tuid": "TSPR04EZU31901021"
}

Use the Mapping in an MQTT Migration

In a Thingsee MQTT message, the TUID appears in the topic and payload. In Haltian IoT, the device UUID appears in the MQTT topic path and is not repeated in the payload.

  1. Extract the UUID from the Haltian IoT MQTT topic.
  2. Look up the UUID in your locally stored mapping table when your downstream system requires the TUID.
  3. Process the measurement value and timestamp from the message payload.
  4. Refresh the mapping after device inventory changes, rather than querying the Service API for every incoming MQTT message.

Devices such as device groups or third-party devices may not have a TUID. The Service API returns null for identifiers.tuid. Keep mapping records keyed by UUID and create a TUID cross-reference only when a value exists.

Other Device Identifiers

A device can also have other identifiers, such as a vendor serial, customer label ID, Wirepas node ID, MAC address, or external ID. Use these only when they match an existing operational workflow or external system. For a complete identifier reference and lookup examples, see Device Identity.