How it works: CMCI GraphQL API

A simple GraphQL query request looks like this:

{
  cicsplexes {
    name
  }
}

Query responses are returned as JSON objects, with the requested data enclosed in the value of the data field. The structure of the response follows that in the query.

{
  "data": {
    "cicsplexes": [
      {
        "name": "CICSPLX01"
      },
      {
        "name": "CICSPLX02"
      }
    ]
  }
}

In an SMSS region, the structure of a GraphQL query is different and looks like this:

{
  smssRegion {
    name  
  }
}

{
  "data": {
    "smssRegion": {
      "name": "IYCWENSS"
    }
  }
}

In CICS TS, the GraphQL API has support for:

• Basic system topology (CICSplexes, Regions, System Groups)
• Querying regions for the resources installed in them
• Querying BAS repositories and CSD repositories for definitions
• Aggregating and grouping resources
• Navigating links between resources

The GraphQL API endpoint is at:

https://host:port/graphql

where host and port are the host name and the port number of your CMCI JVM server.

The GraphQL API accepts GET and POST requests.

For GET requests:

A Content-Type: application/json header must be sent. The query is supplied by the query query parameter. The operation is supplied by the optional operationName query parameter.

For example, the simple query in Figure 1 can be sent by using the following URL:

https://host:port/graphql?query={cicsplexes{name}}

Likewise, for the simple query in Figure 3, a GET request is similar, and can be sent by using the following URL:

https://host:port/graphql?query={smssRegion{name}}

For POST requests:

A Content-Type: application/json header must be sent. The body of the request must be a JSON-encoded object.

{
    "query": "query_body",
    "operationName": "operation_name"
}

where only the query field is mandatory.

Alternatively, a Content-Type: application/graphql header can be sent on POST requests. In this case, the body of the request must be the GraphQL query itself, and no operation name can be specified.

The GraphQL API can provide a more responsive experience in user interfaces such as CICS Explorer. Take the CICSplex Explorer view of CICS Explorer as an example, consider what information is needed in CICS Explorer to build the CICSplex Explorer view:

Here’s how to ask for the information you need to populate the CICSplex Explorer view in the GraphQL API:

{
  cicsplexes {
    name
    regions {
      name
    }
  }
}

And here’s the response:

{
  "data": {
    "cicsplexes": [
      {
        "name": "DUMMY907",
        "regions": []
      },
      {
        "name": "CICSEXCD",
        "regions": [
          {
            "name": "IYCWEZW2"
          },
          {
            "name": "IYCWEZG1"
          },
          {
            "name": "IYCWEZW1"
          },
          {
            "name": "IYCWEZH1"
          },
          {
            "name": "IYCWEZI1"
          },
          {
            "name": "IYCWEZJ1"
          },
          {
            "name": "IYCWEZZ1"
          }
        ]
      }
    ]
  }
}

You can use GraphiQL, an online GraphQL visualization editor, to test your GraphQL queries or the samples. The URL to GraphiQL is:

https://host:port/graphiql

where host and port are the host name and the port number of your CMCI JVM server.

The following example queries the count of local files of all regions in all the connected CICSplexes, and the name of each CICSplex and region. It also has a query name LocalFilesInRegionsInCICSplexes.

query LocalFilesInRegionsInCICSplexes {
  cicsplexes {
    name
    regions {
      name
      cicsResources {
        locfile {
          count
        }
      }
    }
  }
}

You can add more attributes to be queried. This example queries all CICSplexes and all the regions in each CICSplex. Within each region, it retrieves the name, useCount, and status fields of all the local transactions.

{
  cicsplexes {
    name
    regions {
      name
      cicsResources {
        loctran {
          records {
            name
            useCount
            status
          }
        }
      }
    }
  }
}

You can specify which CICSplex or CICS region to be queried. This example queries Region AORRGN in CICSplex PLEX1, retrieving the name, useCount, and status fields of all the local transactions in the region.

{
  cicsplex(name: "PLEX1") {
    name
    region(name: "AORRGN") {
      name
      cicsResources {
        loctran {
          records {
            name
            useCount
            status
          }
        }
      }
    }
  }
}

Removing the CICSplex and region specifications, this example queries all connected CICSplexes and the name, useCount, and status fields of all the local transactions in those CICSplexes.

{
  cicsplexes {
    name
    cicsResources {
      loctran {
        records {
          name
          useCount
          status
        }
      }
    }
  }
}

This example is similar to the previous one, except that it uses a filter to retrieve only transactions starting with CED.

{
  cicsplexes {
    name
    cicsResources {
      loctran(filter: {name: {value: "CED*"}}) {
        records {
          name
          useCount
          status
        }
      }
    }
  }
}

You can also query CICS definitions. This request queries the name and update attributes for all file definitions in the CICSplex data repository.

{
  cicsplex(name: "PLEX1") {
    drep {
      cicsDefinitions {
        filedef {
          records {
            name
            update
          }
        }
      }
    }
  }
}

Similarly, this request queries the name for all pipeline definitions in the CSD for Region AORRGN in CICSplex PLEX1.

{
  cicsplex(name: "PLEX1") {
    region(name: "AORRGN") {
      csd {
        cicsDefinitions {
          pipedef {
            records {
              name
            }
          }
        }
      }
    }
  }
}

This query performs aggregation of all local files in each CICSplex, grouping them by common values of the name attribute and retrieving the count of aggregated records within each aggregation group, the name of each group, and the average, minimum, and maximum readCount within each group.

{
  cicsplexes {
    name
    cicsResources {
      locfile {
        groupBy(attribute: "name") {
          count
          aggregateRecord {
            name {
              value
            }
            readCount {
              average
              min
              max
            }
          }
        }
      }
    }
  }
}

The following example queries the current local transactions connected to the SMSS region. It retrieves records and displaying name, priority, status, tracing, purgeability, and deadlock timeout under each SMSS region name.

{
  smssRegion {
    name
    cicsResources{
      loctran{        
       records{
          name
          priority
          profile
          status
          tracing
          purgeability
          deadlockTimeout
        }
      }
    }
  }
}