CSV Identities

The CSV Identities connector directly attaches org-scoped ExternalIdentity values to entities in the Mapped Graph through a spreadsheet import. This way, you can unify entities in bulk via shared Identities. Read more about Identities and how unification works in the Mapped Graph.
Use Cases
- Unification for work order synchronization
- Connect BMS imports to internal digital twin system Ids
Configuration
Prepare your data
Identify which entities need to be united, and check their External Identities. If one of them already has an org-scoped External Identity, such as one from another connector, add that same value to the other entity in your file. If neither has one, see What if neither entity has an org-scoped identity?.
Tip for future validation: Take note of which of the entities to be united has the older dateCreated value in GraphQL. This entity has the Id that will persist after unification. See example queries below for how to check dateCreated.
Map the entities that do not yet have the target External Identity in a CSV or spreadsheet with the following columns:
- Mapped Entity Id: Mapped ID for the entity to which you are applying the External identity
- External Identity: The value of the External Identity. Note that this should match exactly to the External Identity value of the entity you're trying to merge it with.
- Entity Type: The target entity's base type: BUILDING, SUBBUILDING, FLOOR, SPACE, ZONE, THING or POINT
Example Import: Add External Identity to a Building
| Mapped Entity Id | External Identity | Entity Type |
|---|---|---|
| BLDGmY5Uk9R6cP2sDfXHqvE7Lb | urn:connector:value:123 | BUILDING |
Optional: Identity Options
- Identity Prefix: This will be used to add a prefix to the unique identifier for the entity
For example, if all the identity values you want to add share the same prefix:
- urn:connector:value:123
- urn:connector:value:456
- urn:connector:value:789
You have the option to add this prefix in the Identity Options:
urn:connector:value
Then, you could import the values without the prefix:
| Mapped Entity Id | External Identity | Entity Type |
|---|---|---|
| BLDGmY5Uk9R6cP2sDfXHqvE7Lb | 123 | BUILDING |
| BLDGQ3nWp7LsJkVxE2mRZaC8Ty | 456 | BUILDING |
| BLDG8vTqLMr2XfYpZc9uHsA5Kd | 789 | BUILDING |
Upload CSV File
Import the CSV or XLSX file in the Mapping tab. The file requires:
- entityType must be BUILDING, SUBBUILDING, FLOOR, SPACE, ZONE, THING or POINT
- entityId must exist in Mapped Graph
- entityExternalId must be unique within the file and within the scope of this connector instance - create a new CSV Identities connector to re-use the ExternalIdentity
- All fields are required
Select File or drag and drop to import your file, then follow the prompts to Submit the file.
Validate success in GraphQL
Note that it may take the connector some time to import your changes. You can validate success by querying on the entityId you entered, and confirm that the ExternalIdentity you added is available on the entity.
If the other entity you were trying to merge in with this identity still exists in the Graph, then those two entities were not unified. Double check the ExternalIdentity value on both entities to confirm they match exactly.
Sample Queries
Get External Identity from a Building
This query syntax would be interchangeable with floors, spaces, zones, or things - just swap buildings out for one of those and update the Mapped Id.
{
buildings(filter:{id:{eq:"BLDGF7xQpR2LmNeV8kYcTzH4Sa"}}) {
id
name
identities {
... on ExternalIdentity {
__typename
dateCreated
dateUpdated
id
scope
scopeId
value
}
}
}
}
Buildings by Date Created
The below query can be used to compare two different buildingIds by their dateCreated. This query syntax would also be interchangeable with floors, spaces, zones, or things.
{
buildings(filter:{id:{in:[
"BLDGmY5Uk9R6cP2sDfXHqvE7Lb",
"BLDGF7xQpR2LmNeV8kYcTzH4Sa"
]}}) {
id
name
exactType
dateCreated
}
}
Troubleshooting
Most unification problems come back to one rule: entities merge only when they share an identical External Identity value at the same scope, and the merged entity keeps the Mapped Id of the entity with the oldest dateCreated.
Identities you add with CSV Identities are always scoped to your organization, so they only match other organization-scoped identities.
Why didn't entities merge after the import?
Unification needs a shared identity value. Importing a file doesn't link two entities unless both of them end up with the same org-scoped External Identity value.
A common gap is using each entity's Mapped Id as the other's External Identity. For example, adding space B's Mapped Id to space A, and space A's Mapped Id to space B. The two values are different, so nothing matches and nothing merges.
Instead, pick one identity value and attach it to the entity that doesn't have it yet:
| Mapped Entity Id | External Identity | Entity Type |
|---|---|---|
| SPACEq4Rt7LmN2xKcV8wZpYe3Ha | urn:vendor:id:EX-BLDG-L01-101 | SPACE |
If the other space already carries urn:vendor:id:EX-BLDG-L01-101 (for example, from another connector), the two spaces will share a value and unify.
Imports usually finish within a few minutes, but can take longer when the org is busy or when the entity is a high-level one like a large Building with many child entities. Give it time before concluding the merge failed.
To check, query both entities and compare their identities. If they don't share a value, they won't merge.
Values must match exactly
Matching is exact, and there is no wildcard, regex or "close enough" matching. A difference as small as a hyphen or space keeps entities apart:
| Source A | Source B | Merge? |
|---|---|---|
asset-123 | asset 123 | No |
asset-123 | asset_123 | No |
asset-123 | asset-123 | Yes |
What if neither entity has an org-scoped identity?
Each value can appear only once per CSV Identities connector instance, so one connector can't give the same value to both entities. Use two:
- In the first connector instance, add the new value to the first entity.
- In a second connector instance, add the same value to the second entity.
Both entities now carry the same org-scoped identity and unify. Remember that the entity with the older dateCreated keeps its Mapped Id.
Why did the Mapped Id change?
When entities unify, the merged entity keeps the Mapped Id of the entity with the oldest dateCreated. You can’t choose which Id survives, and there’s no way to override it.
Before you import, compare dateCreated on the entities you plan to merge so you know which Id will persist. If a system depends on a particular Id, check which entity is older first. If you have any questions, contact Mapped Support.
Checklist before you import
-
The value you’re adding exactly matches an organization-scoped identity on the entity you want to merge with. It’s an identity value, not a Mapped Id used as a stand-in.
-
Each file lists a value only once. If neither entity has the identity yet, you'll need two connector instances (see What if neither entity has an org-scoped identity?).
-
You've checked which entity is older, and are fine with its Id persisting.
-
The Entity Type column is one of BUILDING, SUBBUILDING, FLOOR, SPACE, ZONE, THING or POINT.