How To: Retrieve, Create, and Update Asset Metadata Using the GQL API

ExoSense ExoSense GraphQL API
1

The purpose of this post is to outline the ways in which a user may programmatically interact with ExoSense’s Asset Metadata system. By the end of this post, you should understand the components of a metadata object, how to retrieve metadata associated with an asset, how to create new metadata objects, and how to update existing metadata. To that end, we will be examining two mutations and two queries:

Mutations

  • createMetadata
  • updateMetadata

Queries

  • metadata
  • asset

This post assumes the reader has a basic understanding of GraphQL. For those brand new to GQL, a primer can be found at https://graphql.org/learn/.

What Is Metadata?

Exosite Documentation (found at Metadata - Exosite Documentation) defines asset metadata as follows:

“Metadata are key-value pairs of textual information associated with an asset. They offer the ability to list information about the asset that may be helpful but that won’t change frequently or be sourced from a device. Metadata is an ideal way to store information about hardware, such as serial, model or version numbers, or service information, such as links to resources or contact information for maintenance personnel.

Metadata is stored with the asset and many pairs of metadata can be added to a single asset.”

Creating Metadata

Metadata objects are created using the createMetadata mutation. This mutation takes a single, required argument: an object of type MetadataInput. MetadataInput objects are comprised of 5 attributes:

itemId!
The UUID of the “item” with which to associate the metadata. At this time, the only kinds of items that can be associated with metadata are Assets.

itemType!
A string denoting the type of item with which the metadata is being associated. At this time, this must be ”asset”.

key!
The key part of the metadata’s key-value pair. This must be a string.

type!
The type of metadata being created. This will be either “string” or “URL”.

value
The value part of the metadata’s key-value pair. This must be a string. This is the only attribute that is not required to create a new metadata object. This allows a user to define a metadata object with no value, perhaps to indicate a field which is expected to be filled in at a later time.

The following is an example of the createMetadata mutation:

Body

mutation createMetadata($meta: MetadataInput!) {
  createMetadata(meta: $meta) {
    id
  }
}

Variables

{
  "meta": {
    "itemId": "739b05a6…",
    "itemType": "asset",
    "key": "Serial Number",
    "type": "string",
    "value": "12345-abc"
  }
}

The mutation above will create a metadata object with the key “Serial Number” and the value “12345-abc” associated with the asset whose UUID is “739b05a6…". It will return the ID of the metadata object, not the item associated with the metadata. This ID will be required to either update the metadata or to retrieve the metadata directly (rather than as part of an asset).

It is important to note that each metadata object can have only one key-value pair, and all key-value pairs associated with an Asset are actually individual metadata objects that have the Asset’s ID as the value of their itemId attribute.

Updating Metadata

Updating metadata is accomplished using the updateMetadata mutation. This mutation is used only to make changes to existing metadata objects. It is very similar in form to the createMetadata mutation, except that it takes two arguments: a metadataUpdate object, identical in form to the metadataInput object described above (except that no individual attribute of the metadataUpdate object is required), and the id of the metadata object you wish to update.

In the example below, we will use the updateMetadata mutation to alter the value of the metadata object we just created.

Body

mutation updateMetadata($id: ID!, $meta: MetadataUpdate!) {
  updateMetadata(id: $id, meta: $meta) {
    id
  }
}

Variables

{
  "id": "ab3fe078…",
  "meta": {
    "value": "5678-cdf"
  }
}

Note that the id variable is the id of the metadata object, not the Asset associated with it. This is also the id that will be returned by the mutation.

Retrieving Metadata

There are several ways to retrieve metadata from GraphQL:

  1. Request a metadata object directly using the metadata query. This requires that you have the metadata id in hand.
  2. Request multiple metadata objects directly using the metadatas query. This requires that you have an array of metadata ids in hand.
  3. Request metadata as part of an asset or assets query. This does not require that you already have the metadata ids, and can return the metadata id attributes if you request them.

All approaches return Metadata objects. Metadata objects consist of the following attributes:

byTemplate
A boolean indicating whether a metadata object was created by an Asset template.

id
The UUID of the metadata object.

item
The MetadataItem object with which the metadata is associated. At this time, the item is always an Asset.

itemId
The UUID of the Asset with which the metadata object is associated.

itemType
A string denoting the type of item with which the metadata object is associated. At this time, it is always “asset”.

key
The key part of the key-value pair of the metadata object.

locked
A boolean denoting whether the metadata is “locked”.

type
A string denoting the MetadataType of the metadata object. Either “string” or “URL”.

value
The value part of the metadata’s key-value pair.

As an example of approach number 1, we will construct a query which returns the metadata object we created in the previous section.

Body

fragment assetFragment on Asset {
  name
  id
}

query metadata($id: ID!) {
  metadata(id: $id) {
    key
    value
    item {
      ...assetFragment
    }
    itemType
    type
  }
}

Variables

{
  "id": "ab3fe078…"
}

In the above example, our query body contains two sections: a fragment representing an Asset, and the query itself. To retrieve information about the item, the fragment construction is required. Our query returns the key, value, item name, item id, itemType, and type of the metadata object with the id ab3fe078….

Approach number 3 is perhaps a more common use case. In approach number 3, we request an Asset and its metadata by providing the Asset’s id as a query variable. Such a query might look like this:

Body

query asset($id: ID!) {
  asset(id: $id) {
    name
    metadata {
      id
      key
      value
    }
  }
}

Variables

{
  "id": "739b05a6-3408-42b2-b57e-96abb20c8b05"
}

In the above example, we request the name of the asset and its associated metadata objects. GQL will return an array containing any metadata objects associated with the asset.

In addition to the approaches outlined above, other queries which return asset objects, such as the groups query, can also return metadata objects.