How it works: CMCI GraphQL API
The CICS® management client interface (CMCI) provides a GraphQL application programming interface (API) for system management clients such as IBM® CICS Explorer®. The CMCI GraphQL API is supported through HTTP. With the GraphQL API, a client can query many types of CICS resources across CICSplexes or regions in a single request. In the single query request, the client can specify exactly what data it needs about multiple CICS resources, with inherent relationships between the CICS resources explicitly expressed. For more information about GraphQL, see Introduction to GraphQL.
- The aggregation function in CICS Explorer is also supported by the CMCI GraphQL API in CICS TS. For more information, see Configuring for CICS Explorer.
- The CMCI GraphQL API is supported in a CICSPlex® SM environment as of CICS TS 5.5, and in a single CICS region (SMSS) environment as of CICS TS 5.6 with APAR PH35122.
- To set up the CMCI GraphQL API in CICS, you need to configure a CMCI JVM server within the WUI region of a CICSplex or a single CICS region. For instructions, see Setting up CMCI.
What is a GraphQL query?
At the root of the query is the cicsplexes
field, which finds all the CICSplexes
that the WUI server is connected to. The name
field nested in the
cicsplexes
field requests the name of each CICSplex.
data
field. The structure of the response follows that in the query.
The structure of the response is similar to the CICSplex, and looks like this:
- 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
To retrieve more information, add more fields to the query, including nested ones. See Sample queries.
How to make GraphQL API requests
https://host:port/graphql
where
host and port are the host name and the port number of your
CMCI JVM server.- For GET requests:
-
A
Content-Type: application/json
header must be sent. The query is supplied by thequery
query parameter. The operation is supplied by the optionaloperationName
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.
where only the{ "query": "query_body", "operationName": "operation_name" }
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.
See Sample queries for sample code of GraphQL queries.
Example: the CICSplex Explorer view of CICS Explorer
At its most basic, you need to know what CICSplexes are in the environment, and which CICS regions are in those CICSplexes. With a REST API, you have to make multiple requests:
- Ask for a list of CICSplexes in the environment.
- For each CICSplex, ask for a list of the regions in that CICSplex.
Even this simple example demonstrates that the number of requests you have to make grows with the complexity of the information you ask for. When you consider adding region groups into the mix, and members of those region groups, even more information needs to be requested.
{
cicsplexes {
name
regions {
name
}
}
}
{
"data": {
"cicsplexes": [
{
"name": "DUMMY907",
"regions": []
},
{
"name": "CICSEXCD",
"regions": [
{
"name": "IYCWEZW2"
},
{
"name": "IYCWEZG1"
},
{
"name": "IYCWEZW1"
},
{
"name": "IYCWEZH1"
},
{
"name": "IYCWEZI1"
},
{
"name": "IYCWEZJ1"
},
{
"name": "IYCWEZZ1"
}
]
}
]
}
}
The GraphQL supplies all the data you require in a single request with explicitly shown relationships between CICS resources. When enabled for the CMCI connection, it can drastically reduce the time you need to retrieve information through CICS Explorer. It also powers the aggregation function in CICS Explorer for Aqua 3.2 to provide aggregation and grouping of CICS resources.
Sample queries
https://host:port/graphiql
where host
and port are the host name and the port number of your CMCI JVM server. - GraphiQL provides auto-completion and a built-in documentation explorer for GraphQL schema reference. You can display available field names by pressing Ctrl+Space.
- To easily differentiate queries in GraphiQL history, you can specify a unique query name by
prefixing the query with
query QueryName
.
LocalFilesInRegionsInCICSplexes
.query LocalFilesInRegionsInCICSplexes {
cicsplexes {
name
regions {
name
cicsResources {
locfile {
count
}
}
}
}
}
name
,
useCount
, and status
fields of all the local
transactions.{
cicsplexes {
name
regions {
name
cicsResources {
loctran {
records {
name
useCount
status
}
}
}
}
}
}
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
}
}
}
}
}
}
name
, useCount
, and status
fields of all
the local transactions in those
CICSplexes.{
cicsplexes {
name
cicsResources {
loctran {
records {
name
useCount
status
}
}
}
}
}
CED
.{
cicsplexes {
name
cicsResources {
loctran(filter: {name: {value: "CED*"}}) {
records {
name
useCount
status
}
}
}
}
}
{
cicsplex(name: "PLEX1") {
drep {
cicsDefinitions {
filedef {
records {
name
update
}
}
}
}
}
}
{
cicsplex(name: "PLEX1") {
region(name: "AORRGN") {
csd {
cicsDefinitions {
pipedef {
records {
name
}
}
}
}
}
}
}
readCount
within each
group.{
cicsplexes {
name
cicsResources {
locfile {
groupBy(attribute: "name") {
count
aggregateRecord {
name {
value
}
readCount {
average
min
max
}
}
}
}
}
}
}
{
smssRegion {
name
cicsResources{
loctran{
records{
name
priority
profile
status
tracing
purgeability
deadlockTimeout
}
}
}
}
}