External IDs

When integrating external systems with Senseye, there is often a requirement to map from Senseye's IDs to an ID within the external system. Senseye supports this mapping with External IDs; this allows one or more IDs from external systems to be mapped to Senseye IDs. External IDs can be configured on any node within the hierarchy, including Assets, Sensors and Sub-Levels.

The following describes how to make use of External IDs within the GraphQL API when using a single external system. If you have multiple external systems which you want to map to a given node within the Senseye hierarchy, please contact support to setup the required configuration and provide further API documentation if required for your use case.

Setting an External ID¶

The setExternalID mutation can be used to set an External ID for a given Senseye ID:

mutation SetExternalID($input: SetExternalIdInput!) {
    setExternalId(input: $input) {
        externalId
        id
    }
}

{
    "input": {
        "externalId": "External System's ID",
        "id": "Senseye's ID"
    }
}

As discussed above, the Senseye ID could be any hierarchy node - the node type used will depend on the type of integration and how closely the hierarchies within both systems match.

To set an External ID, you must have write permissions on the node.

Using an External ID¶

Once set, hierarchy nodes can be retrieved using the External ID. The example below uses the hierarchyNodeByExternalID query to gather the Senseye ID and name of the hierarchy node with a given External ID. Furthermore, if the node is an Asset, it will gather its current attention index.

query {
    hierarchyNodeByExternalID(externalID: "External System's ID") {
        id
        name
        ... on Asset {
            currentAttentionIndex {
                value
                timestamp
            }
        }
    }
}

If you are setting External IDs just on Assets, there is an Asset specific query (assetByExternalID) which avoids the type casting seen above:

query {
    assetByExternalID(externalID: "External System's ID") {
        id
        name
        currentAttentionIndex {
            value
            timestamp
        }
    }
}

All HierarchyNode types allow their External ID to be retrieved using the externalId attribute. For example, the following query will gather 10 Cases from within your organization, and for each, return the date when the Case was opened and the associated Asset's External ID:

query {
    organization {
        cases(limit: 10) {
            results {
                openedAt
                asset {
                    externalId
                }
            }
        }
    }
}