Skip to main content

What Is the XID?

The XID (Export ID) is a system-wide unique identifier assigned to every configurable object in Mango — data sources, data points, event detectors, users, JSON store entries, and more.

Why XIDs exist​

Every object in Mango also has a numeric database ID that is specific to that installation. If you export a data source from one Mango instance and import it into another, the database IDs will almost certainly be different. XIDs solve this by providing a stable, portable identifier that works across installations.

IdentifierScopeExampleUse case
Database IDSingle installation42Internal database joins, time-series storage
XIDCross-installationDS_a1b2c3JSON config export/import, REST API, dashboard references

How they work​

  • Automatically generated — When you create a new object, Mango assigns a random XID (e.g., DP_f7e2a1).
  • Editable — You can change an XID to something more meaningful (e.g., DS_building_a_modbus). This is recommended for objects you plan to export or reference in custom pages.
  • Must be unique — No two objects of any type can share the same XID within a Mango instance.
  • Used in JSON configuration — When exporting or importing configurations (via the JSON import/export tool or the REST API), all cross-references between objects use XIDs, not database IDs.

Practical examples​

Dashboard references: When you build a custom dashboard page that displays a specific data point, the page markup references the point by XID. If you export and import that page to another Mango instance that has a point with the same XID, the reference resolves automatically.

Configuration migration: To move a complete setup from a development instance to production:

  1. Export the configuration as JSON from development
  2. Import the JSON into production
  3. Mango matches objects by XID — existing objects are updated, new ones are created

REST API: The REST API uses XIDs to reference objects:

GET /rest/latest/data-points/DP_building_a_temp

Best practices​

  • Use descriptive XIDs for objects you reference in dashboards or integrations (e.g., DS_bacnet_hvac, DP_room_101_temp).
  • Keep auto-generated XIDs for objects you don't reference directly — the random format prevents accidental collisions.
  • Document your XID naming convention if multiple people manage the Mango configuration.
  • Never change an XID after other objects or dashboards reference it, unless you update all references.