GraphQL API Queries

GraphQL is another format to use when making requests to FlexDeploy servers. To get started you will need to download a way to make GraphQL Requests to your FlexDeploy server. Throughout this example we will be using Postman in order to send out GraphQL requests.

Making a Request

First, there are some steps in postman that need to be done before writing a request.

Create an HTTP Request
Make sure the Request is a POST request
Set the URL to the format below, replacing the FLEXDEPLOY_SERVER_HOSTNAME and FLEXDEPLOY_SERVER_PORT with your FlexDeploy server’s hostname and port respectively
1. http(s)://{{FLEXDEPLOY_SERVER_HOSTNAME}}:{{FLEXDEPLOY_SERVER_PORT}}/flexdeploy/rest/v2/graphql
Set up security information under the “Authorization” tab. Either Basic Auth (username and password) or a token can be used here
Under the “Body” tab of the request, switch the body format to GraphQL by clicking on the dot next to “GraphQL”

After that is done we can now start to create our request. An example request is provided below.

query envState($where: [WhereInput], $sort: [SortInput], $page: PageInput) {
    reportEnvironmentState(where: $where, sort: $sort, page: $page) {
        next
        hasMore
        items {
            endTime
            environmentName
            executionStatus
            externalTicket
            instanceName
            objectPath
            packageName
            partialDeployments
            projectName
            projectVersionName
            projectWorkflowType
            relName
            relSnapshot
            scmRevision
            startTime
            streamName
            workflowExecutionId
            workflowRequestId
        }
    }
}

Variables

There are three main variables to use with FlexDeploy GraphQL queries: where, sort, and page.

Variable Name

Description

Object Definition

where: [WhereInput]

This allows you to filter the data like a where clause in an SQL query. Where is an array so multiple individual WhereInput objects can be linked together to filter the query.

field: GraphQL field being filtered

type: The comparison being preformed. For example, ‘eq’ represents equals and ‘eqi’ represents equals ignoring case.

innerWhere: Similar to a subselect in SQL where prefiltering of a query could be done

value: The value you are filtering by

input WhereInput {
  field: String!
  type: WhereTypeEnum!
  innerWhere: [WhereInput!]
  value: String
}

enum WhereTypeEnum {
  eq
  ne
  eqi
  gt
  lt
  inc
  inci
  ninc
  btwn
  rel
  empty
  nempty
}

sort: [SortInput]

This allows you to sort the data like a order by clause in an SQL query. Sort is an array so multiple individual SortInput objects can be linked together to sort the query.

field: GraphQL field being sorted

direction: the direction of sort being preformed with asc meaing ascending order and desc meaning descending order.

input SortInput {
  field: String!
  direction: SortEnum
}

enum SortEnum {
  asc
  desc
}

page: PageInput

Page input contains extra options for the block of data that is returned by the query.

limit: The number of items in the block being returned. By default, a limit of 50 items are returned by the query. This can be overridden by the page limit to return a different amount of items.

offset: Offsets the block of data being returned by the set value. For example, a limit of 20 and an offset of 4 would return items 4 through 23.

input PageInput {
  limit: Int
  offset: Int
}

All of the above variables object above are then bundled together in on variable object. It is not required to always include all three variables in the object. For example, if you wanted to only filter and not sort, you would only need to include the where variable. Below is an example of the combined variable object with all three variables used.

{
    "sort": [
        {
            "field": "projectName",
            "direction": "asc"
        }
    ],
    "where": [
        {
            "field": "environmentName",
            "type": "eqi",
            "value": "QA"
        },
        {
            "field": "projectWorkflowType",
            "type": "eq",
            "value": "DEPLOY"
        }
    ],
    "page": { 
        limit: 20 
    }
}

Selection Set

The biggest difference between GraphQL and REST is the option selection of elements to be returned in a query. This can make queries return faster if only the information that is needed by the query is returned. This is called a subselection set. In our above example we can see we have this block of text:

items {
            endTime
            environmentName
            executionStatus
            externalTicket
            instanceName
            objectPath
            packageName
            partialDeployments
            projectName
            projectVersionName
            projectWorkflowType
            relName
            relSnapshot
            scmRevision
            startTime
            streamName
            workflowExecutionId
            workflowRequestId
        }

Here is where we can control what is being returned in the query. GraphQL will only return fields present in the subselection. For example, If i only wanted Package Name, Project Name and Project Version Name to be returned, I could alter our previous example to something like this:

query envState($where: [WhereInput], $sort: [SortInput], $page: PageInput) {
    reportEnvironmentState(where: $where, sort: $sort, page: $page) {
        next
        hasMore
        items {
            packageName
            projectName
            projectVersionName
        }
    }
}

Example Queries:

Here are are few more examples of queries that you can use with FlexDeploy. To get a full list of queries, some software used to execute queries like postman can give auto correct advice by fetching out GraphQL schema automatically. Otherwise, an Introspection Query can provide a list of queries accessible in our schema.

Environment History Report With File Details

query envState($where: [WhereInput], $sort: [SortInput], $page: PageInput) {
    reportEnvironmentHistoryFileDetails(where: $where, sort: $sort, page: $page) {
        next
        hasMore
        items {
            allFilesRequested
            buildFlexField1
            buildFlexField10
            buildFlexField2
            buildFlexField3
            buildFlexField4
            buildFlexField5
            buildFlexField6
            buildFlexField7
            buildFlexField8
            buildFlexField9
            cmsTicketIds
            endTime
            environmentId
            environmentName
            executionStatus
            flexField1
            flexField10
            flexField2
            flexField3
            flexField4
            flexField5
            flexField6
            flexField7
            flexField8
            flexField9
            folderId
            instanceId
            instanceName
            workItemIds
            objectPath
            packageName
            partialDeployments
            pkgStatus
            poScmRevision
            projectId
            projectName
            projectVersionName
            relDefinitionId
            relName
            relSnapshot
            relSnapshotId
            requestedBy
            requestedOn
            scmRevision
            sequenceNumber
            stageExecId
            startTime
            streamName
            workflowExecutionId
            workflowId
            workflowRequestId
            workflowType
            workflowVersion
        }
    }
}

Environment History Report Without File Details

query envState($where: [WhereInput], $sort: [SortInput], $page: PageInput) {
    reportEnvironmentHistoryNoFileDetails(where: $where, sort: $sort, page: $page) {
        next
        hasMore
        items {
            allFilesRequested
            buildFlexField1
            buildFlexField10
            buildFlexField2
            buildFlexField3
            buildFlexField4
            buildFlexField5
            buildFlexField6
            buildFlexField7
            buildFlexField8
            buildFlexField9
            cmsTicketIds
            endTime
            environmentId
            environmentName
            executionStatus
            flexField1
            flexField10
            flexField2
            flexField3
            flexField4
            flexField5
            flexField6
            flexField7
            flexField8
            flexField9
            folderId
            instanceId
            instanceName
            workItemIds
            objectPath
            packageName
            partialDeployments
            pkgStatus
            poScmRevision
            projectId
            projectName
            projectVersionName
            relDefinitionId
            relName
            relSnapshot
            relSnapshotId
            requestedBy
            requestedOn
            scmRevision
            sequenceNumber
            stageExecId
            startTime
            streamName
            workflowExecutionId
            workflowId
            workflowRequestId
            workflowType
            workflowVersion
        }
    }
}

Executing Queries

Combing everything we talked about this far, we are now able to execute queries.

Once a query is configured inside your software of choice to make HTTP requests, just press the “Send” or “Execute” button to send out your HTTP Request.