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, 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 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
• 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 likewise be interchangeable with floors, spaces, zones, or things.

{
    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 be interchangeable with floors, spaces, zones, or things.

{
    buildings(filter:{id:{in:[
      "BLDGmY5Uk9R6cP2sDfXHqvE7Lb",
      "BLDGF7xQpR2LmNeV8kYcTzH4Sa"
    ]}}) {
      id
      name
      exactType
      dateCreated
    }
}