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, which entities already have an org-scoped External Identity, and which entities are lacking that org-scoped External 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 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.
• Entity Type: The target entity's type: BUILDING, FLOOR, SPACE, ZONE or THING

Example Import: Add External Identity to a 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:

1
urn:connector:value

Then, you could import the values without the prefix:

Upload CSV File

Import the CSV or XLSX file in the Mapping tab. The file requires:

• entityType must be BUILDING, FLOOR, SPACE, ZONE or THING
• entityId must exist in Mapped Graph
• entityExternalId must be unique within the file
• 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

If you query both of the entities you selected to unify, filtering on the entityId, only one of the entityIds should still exist in the Graph.

Sample Queries

Buildings by Date Created

The below query can be used to compare two different buildingIds by their dateCreated. This query syntax would be interchangeable with floors, spaces, zones, or things.

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
{
  buildings(
    filter: {id: {in: ["BLDGmY5Uk9R6cP2sDfXHqvE7Lb", "BLDGF7xQpR2LmNeV8kYcTzH4Sa"]}}
  ) {
    id
    name
    exactType
    dateCreated
  }
}

Get External Identity from a Building

This query syntax would likewise be interchangeable with floors, spaces, zones, or things.

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  buildings(filter: {id: {eq: "BLDGF7xQpR2LmNeV8kYcTzH4Sa"}}) {
    id
    name
    identities {
      ... on ExternalIdentity {
        __typename
        dateCreated
        dateUpdated
        id
        scope
        scopeId
        value
      }
    }
  }
}