Skip to main content

CSV Identities

CSV connector logo

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 IdExternal IdentityEntity Type
BLDGmY5Uk9R6cP2sDfXHqvE7Lburn:connector:value:123BUILDING

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 IdExternal IdentityEntity Type
BLDGmY5Uk9R6cP2sDfXHqvE7Lb123BUILDING
BLDGQ3nWp7LsJkVxE2mRZaC8Ty456BUILDING
BLDG8vTqLMr2XfYpZc9uHsA5Kd789BUILDING

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 IdExternal IdentityEntity Type
SPACEq4Rt7LmN2xKcV8wZpYe3Haurn:vendor:id:EX-BLDG-L01-101SPACE

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 ASource BMerge?
asset-123asset 123No
asset-123asset_123No
asset-123asset-123Yes

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:

  1. In the first connector instance, add the new value to the first entity.
  2. 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.