External ID values

External ID values are stored against an Administrate entity.

Update values

In order to store an External ID, three pieces of information are required:

  1. nodeId: the ID of the entity to be tagged.
  2. name: the identifier for this external id, for example ms_dynamics_account_id.
  3. value: the value to set for the external ID
  4. overwrite (optional): if true, any existing value will be replaced by the provided value. If false, an error will be returned instead.

The below stores external ID ms_dynamics_account_id on the specified node:

Example

mutation {
  externalId{
    store(
      nodeId: "Q291cnNlOjE="
      name: "ms_dynamics_account_id"
      value: "01234"
    ) {
      id
      __typename
      externalIds{
        name
        value
      }
    }
  }
}

The response confirms the value has been set, and it returns the corresponding entity which can be queried for further metadata if necessary:

{
  "data": {
    "externalId": {
      "store": {
        "id": "Q291cnNlOjE=",
        "__typename": "Event",
        "externalIds": [
          {
            "name": "ms_dynamics_account_id",
            "value": "01234"
          }
        ]
      }
    }
  }
}

Retrieve values

External ID values can be retrieved for each Entity and can be used to retrieve nodes that match a particular value.

Read entity values

The following returns all external ID values set on the first page of Events:

Example

query {
  events{
    edges{
      node{
        id 
        externalIds{
          name
          value
        }
      }
    }
  }
}

Example response 

{
  "data": {
    "events": {
      "edges": [
        {
          "node": {
            "id": "Q291cnNlOjE=",
            "externalIds": [
              {
                "name": "ms_dynamics_account_id",
                "value": "01234"
              }
            ]
          }
        }
      ]
    }
  }
}

Find entity with matching value

Given the uniqueness constraint on External ID values (no two entities can have the same value for the same external ID), they can be used to find an entity:

Example

query {
  nodeByExternalId(
    type: Event,
    name: "ms_dynamics_account_id",
    value: "01234"
  ) {
    id
    externalIds{
      name
      value
    }
    __typename
    ... on Event{
      code
    }
  }
}

Example response:

{
  "data": {
    "nodeByExternalId": {
      "id": "Q291cnNlOjE=",
      "externalIds": [
        {
          "name": "ms_dynamics_account_id",
          "value": "01234"
        }
      ],
      "__typename": "Event",
      "code": "REACT1"
    }
  }
}

Delete values

An External ID can be removed from a node (for example if no longer required or was added in error):

Example

mutation {
  externalId {
    remove(
      nodeId:"Q291cnNlOjE=",
      name:"ms_dynamics_account_id"
    ) {
      id
        externalIds{
        name
        value
      }
    }
  }
}