XID Best Practices: Naming Conventions for Scalable Deployments

Overview

Every object in Mango by Radix IoT — data sources, data points, dashboards, event detectors, event handlers — has an XID, which Mango labels Export ID (XID) across the interface. XIDs are unique strings used by the REST API, JSON import/export, scripting, and cross-references. Poor XID conventions lead to confusion at scale; good conventions make automation and troubleshooting straightforward.

What Mango Actually Enforces

Mango validates exactly three things about an XID. Everything else in this article is convention, which is precisely why it has to be agreed and written down:

• It cannot be empty — leave the field blank and Mango generates one for you
• 100 characters maximum — longer values are rejected with "Cannot be longer than 100 characters"
• Unique within the object type — a clash is rejected with "This XID is already in use". Uniqueness is checked per type, so a data source and a data point may share an XID

Mango does not police which characters you use, and it will not warn you that an XID is unreadable, inconsistent, or about to collide with another site's. That is your convention's job.

Why XIDs Matter

• REST API — most API endpoints use XIDs to identify objects
• JSON import/export — XIDs determine whether an import creates a new object or updates an existing one
• Scripting — meta point scripts and global scripts reference points by XID
• Duplication — when cloning devices, clear XIDs to generate new ones; leave them to overwrite
• Troubleshooting — a well-named XID tells you what the object is without opening it

Recommended XID Structure

Use a prefix-based convention with segments separated by underscores:

{type}_{site}_{device}_{point}

Type Prefixes

Use the same prefixes Mango itself generates, so hand-named objects sort and read alongside anything created automatically:

Custom pages — what most people mean by a dashboard — are the exception. They are stored in the JSON store and Mango assigns each one a bare random identifier with no prefix, which the page editor does not expose. Name the page deliberately instead; there is no dashboard XID to design.

Site and Device Segments

Include enough context to identify the physical location and device without opening the object:

• Site: BLDG_A, CAMPUS_1, PLANT_NORTH
• Device: RTU_01, GEN_02, METER_03
• Point: TEMP, PRESSURE, STATUS, KWH

Rules for Good XIDs

1. Uppercase with underscores — easy to read, no ambiguity: DS_BLDG_A_RTU_01
2. No spaces or special characters — XIDs are used in URLs and scripts. Stick to letters, numbers, and underscores
3. Keep them short but descriptive — you'll type these in API calls. Balance readability with brevity
4. Be consistent — every object of the same type should follow the same pattern. Don't mix DS_RTU01 with DataSource-RTU-01
5. Plan for growth — use zero-padded numbers (RTU_01 not RTU_1) so sorting works correctly
6. Avoid auto-generated XIDs in production — leave the field blank and Mango builds the XID as the type prefix plus a random UUID, for example EMS_SITE_ef989e9e-e663-455c-a3da-9d8370b43565. They are unique but unreadable, and each one spends at least 39 of your 100 characters before you have said anything about the object. Replace them with meaningful names during initial configuration

When to Set XIDs

Set XIDs during initial configuration, not after. Changing an XID later requires updating every script, dashboard reference, API integration, and JSON template that uses the old XID. It's far easier to name correctly from the start.

Once a publisher is synchronizing points to another Mango instance, a rename stops being a find-and-replace and becomes a data problem. The receiving data source matches incoming points by XID. Rename a point on the publishing side and nothing gets renamed at the far end: the target finds no match and creates a second point, leaving the original behind with all of its history, still wired into that instance's charts, watch lists and reports. Reuniting the two afterwards is manual work, and no import will do it for you. This is the single strongest reason to get XIDs right before the first publisher goes live.

XIDs in Multi-Site Deployments

For deployments with multiple Mango instances (one per site), XIDs should still include the site identifier. This ensures JSON exports from different sites don't collide when reviewed together or imported into a central system.

When a publisher pushes points to a central instance, the receiving data source matches them by XID, and what a collision does depends on where the existing point lives:

• If it belongs to the same receiving data source, it is updated to match the publisher — so two sites publishing the same XID overwrite each other
• If it belongs to a different data source on that host, synchronization aborts with "Data source mismatch in point ... The XID already belongs to a different data source on the host"

There are two ways to keep sites apart, and they combine. Build the site identifier into the XIDs themselves, or set the publisher's XID prefix, which Mango prepends to every point's XID as it synchronizes — that setting exists for precisely this case. Watch the ceiling either way: if the prefixed XID comes out longer than 100 characters the point is rejected and synchronization fails.

Cloud Connect is not part of this picture. It is a remote-access module: it forwards a site's Mango web and SSH ports to a central instance over an SSH tunnel and an HTTP proxy, so you can reach that site's interface from one place. It moves no point values and creates no points, so it cannot cause an XID collision.

XIDs and JSON Duplication

When duplicating a device using JSON export/import, the XID determines behavior:

• Same XID — import overwrites the existing object (destructive)
• No XID — Mango generates a new random XID (creates a new object)
• New XID — import creates a new object with your chosen XID (recommended)

For device duplication workflows, update XIDs in the JSON to follow your naming convention for the new device.

Common Mistakes

Summary

XIDs are the backbone of Mango automation and cross-referencing. Use a consistent, prefix-based naming convention: {TYPE}_{SITE}_{DEVICE}_{POINT}. Set XIDs during initial configuration, keep them uppercase with underscores, and document your convention so everyone on the team follows the same pattern.