Data expressions

Constructing GraphQL queries for Data Expressions

Site Planner includes a GraphQL UI that runs at: <Site Planner domain>/graphql/. The GraphQL UI can be used to test queries against the Site Planner model, once a query is satisfactory then it can be copied into the Data Expressions field of an Automation Context. When an object matching that Automation Context is built then the graphql query in the Data Expressions field is run and the response is added to the request to IBM Cloud Pak for Network Automation.

Example GraphQL query for all devices

Query for the id and name of all devices:

{
    devices {
      id
      name
    }
}

Response:

{
  "data": {
    "devices": [
      {
        "id": "1",
        "name": "example-device"
      },
      {
        "id": "2",
        "name": "example-device-2"
      }
    ]
  }
}

Example GraphQL filtered query

Query for id, name, device role and site of devices with device role named example-role:

{
    devices (filters: {device_role__name: "example-role"}){
      id
      name
    	device_role {
    	  id
        name
    	}
      site {
        id
        name
      }
    }
}

Response:

{
  "data": {
    "devices": [
      {
        "id": "1",
        "name": "example-device",
        "device_role": {
          "id": "1",
          "name": "example-role"
        },
        "site": {
          "id": "1",
          "name": "example-site"
        }
      }
    ]
  }
}

Example GraphQL tags query

Query for sites with tags including example-tag:

{
    sites (filters: {tags__name: "example-tag"}) {
      id
    	name
    	tags
    }
}

Response:

{
  "data": {
    "sites": [
      {
        "id": "1",
        "name": "example-site",
        "tags": [
          "example-tag"
        ]
      }
    ]
  }
}

Arguments

A GraphQL query may also reference particular arguments which are passed during execution (at the time of the build/teardown of an object). In all cases, the id and name are available (except a few objects which do not have names but some other primary key e.g. Device Type has model).

This makes to possible to query data relative to the object being automated.

For example, to query the Device being automated:

query automationQuery($id: Int!) {
  device(filters: {id: $id}){
      id
      name
  }
}

The query line is added so we may define the argument $id: Int!. Note it must be called $id (or $name, if using name instead). The type for id should be Int whereas name should use String.

The argument variable is then used later, on the second line, passed in the format $id as a value to the filters option of the devices query.