Universal Aliases

Your rack is called DC1-R042 in Salesforce, RACK_04_12 in Oracle, PHX1.R04.12 in FNT and something else again in the spreadsheet the capacity team actually uses. Universal Aliases lets Rackvio store every one of those names against the same object, so anyone can search by the name they already know and land in the right place.

This is additive. Recording a foreign name never renames, moves or overwrites anything in Rackvio, which means you can map one system now and another next year without a flag day.

Concepts

Term	Meaning
Source system	A system you are reconciling against — Salesforce, Oracle, FNT, ServiceNow, a CSV export. A managed, named list, not free text.
Foreign name	What that system calls the object. Stored verbatim.
Foreign ID	Optional. That system’s stable record ID, when it has one.
Canonical entity	The object in Rackvio the foreign name points at.

Aliases attach at every level of the hierarchy, not just racks: site, building, floor, room, rack, asset, asset_interface, power_node, equipment_model and customer. Cross-system disagreements are rarely confined to one level, so neither is the mapping.

Availability by edition

	Community	Cloud Starter	Cloud Growth	Enterprise
Store and resolve foreign names	Yes	Yes	Yes	Yes
Search by another system’s name	Yes	Yes	Yes	Yes
Bulk CSV import (unlimited rows)	Yes	Yes	Yes	Yes
Worklist of unmatched rows	Yes	Yes	Yes	Yes
Source systems	1	3	Unlimited	Unlimited
Review queue	—	Yes	Yes	Yes

The Rosetta Stone itself — recording a name and resolving it — is free in every edition, including the self-hosted Community Edition. What the paid tiers add is the labour of reconciling names that did not match exactly, and the ability to track more than one system at once.

1. Register your source systems

Aliases are always scoped to a source system, so create one before importing. Community Edition ships with a single source system, which is enough to map one legacy tool. Cloud Starter raises that to three, and Cloud Growth and Enterprise are unlimited.

Attempting to exceed your tier’s limit returns 402 with alias_source_limit_reached, naming the limit and your current count. Deleting a source system frees its slot — the count is of source systems that exist, not of any ever created.

2. Import the names you already have

Export a CSV from the system you are mapping and upload it. One file covers every entity level, so a single query against your own system usually produces the whole thing.

Download a template with a worked example for all ten entity types from GET /aliases/import/template, or the same button in the import screen.

Columns

Column	Required	Notes
`entity_type`	Yes	One of the ten types listed above.
`rackvio_identifier`	Yes	Either a hierarchy path or the object’s UUID.
`source_system`	Yes	Must match a source system you have registered.
`foreign_name`	Yes	What the other system calls it.
`foreign_id`	No	That system’s record ID, if you have one.

Identifying the Rackvio object

rackvio_identifier accepts a path or a UUID. Paths use > as the separator:


entity_type,rackvio_identifier,source_system,foreign_name,foreign_id
site,Ashburn Campus,Salesforce,DC-ASHBURN,SF-1001
rack,Hall 1 > R042,Salesforce,DC1-R042,SF-1005
asset,R042 > sw-core-01,Salesforce,SWITCH-CORE-01,SF-2001
rack,3f2b9c14-0e6a-4f7d-9a11-6c5b8e2d4a70,Salesforce,RACK-42-OLD,SF-1005

A bare name is deliberately not accepted as an identifier. Most entity types do not enforce name uniqueness, so a bare name can match several objects, and a mapping written against the wrong one is worse than no mapping at all. > is the separator rather than / because real equipment and room names contain slashes.

Preview before you commit

POST /aliases/import/preview reports exactly what a real run would do. The preview performs the same work as the real import against your live data and then discards it, so what it reports is what you will get — not an estimate produced by a lighter code path.

3. What happens to rows that do not match

Only exact matches are written without a human. Everything else is left untouched and listed for review:

Ambiguous — more than one object matches. Nothing is written, and every candidate is recorded so a person can choose.
Not found — no object matches the identifier.
Invalid — a malformed row, an unknown entity_type, or an unregistered source_system.

The unmatched worklist is visible on every edition, including Community. You can always see how much reconciliation is outstanding.

4. The review queue (Cloud Starter and above)

Resolving the leftovers is the part paid tiers automate. The review queue presents each unmatched row with its candidates so an operator can:

Pick between same-named candidates instead of guessing.
Accept a re-point with both the current and proposed entity in view.
Skip or reject a row that should not be mapped.
Undo an accepted mapping for 24 hours.

Every decision is recorded with the person who made it. Read-only users can view the queue — seeing how much work is outstanding is a read — while accepting and rejecting require an operator or admin role.

On Community Edition these routes are not present in the build at all and return 404. This is deliberate: the feature is absent rather than gated, so no configuration change unlocks it.

5. Searching and integrating

Once a name is stored it works everywhere, for everyone, with no further setup.

Search. Paste an identifier from any mapped system into search and land on the object.
Resolve API. GET /aliases/resolve?source_system=&foreign_name= returns the canonical object. Scripts written against your legacy identifiers keep working after the cutover instead of being rewritten alongside it.
Inspect an object. GET /aliases/entity/{entity_type}/{entity_id} lists what every other system calls it.
Link or unlink one name. POST /aliases/entity/{entity_type}/{entity_id} and DELETE /aliases/{alias_id}.

Full request and response schemas are in the published OpenAPI specification.