Versions Compared

Old Version 10

changes.mady.by.user Emily Simon

Saved on

compared with

New Version Current

changes.mady.by.user Chandresh Patel

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents
minLevel1
maxLevel3

Basics

Basic auth is supported for accessing FlexDeploy’s GraphQL Endpoint. Username and password or API Token are both supported.

FlexDeploy’s GraphQL Endpoint:

Code Block
http(s)://{{FLEXDEPLOY_SERVER_HOSTNAME}}:{{FLEXDEPLOY_SERVER_PORT}}/flexdeploy/rest/v2/graphql

Example:

Code Block
https://flexdeployserver.hostingservice.com:8000/flexdeploy/rest/v2/graphql

Making a Request

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

  1. Create an HTTP Request

  2. Make sure the Request is a POST request

  3. Set the URL to the format belowendpoint listed above in Basics, 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

  4. Set up security information under the “Authorization” tab. Either Basic Auth (username and password) or an API token can be used here

  5. Under the “Body” tab of the request, switch the body format to GraphQL by clicking on the “GraphQL” radio button

...

To have Postman give suggestions for your query, press Ctrl + Space to bring up the autocomplete box.

...

Writing a Query

After you have created a request and loaded the schema, we can start to write our query. There are a few key parts to a query which we’ll dive into with the example below.

...

The biggest difference between GraphQL and other, more traditional, REST requests are the optional 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 example we can see we have this block of text:

Code Block
languagegraphql
  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:

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

...

There are three main variables to use with that are common across most 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: Name of the GraphQL field being filtered

type: The comparison being performed

  • eq - equal

  • ne - not equal

  • eqi - equal (Ignores Case)

  • gt - greater than

  • lt - less than

  • inc - includes

  • inci - includes (Ignores Case)

  • ninc - does not include

  • empty - empty

  • nempty - not empty

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

value: The value you are filtering by

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

enum WhereTypeEnum {
  eq
  ne
  eqi
  gt
  lt
  inc
  inci
  ninc
  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 meaning ascending order and desc meaning descending order.

Code Block
languagejson
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.

Code Block
languagejson
input PageInput {
  limit: Int
  offset: Int
}

All of the above variables object above objects are then bundled together in one 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.

...

Combining everything we talked about this thus far (creating a HTTP Request, queries, and variables), we are now able to execute a query.

...

Response

...

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.

Response

{
Code Block
Code Block
{
    "data": {
        "reportEnvironmentState": {
            "items": [
                {
                    "packageName": null,
                    "projectName": "RESTDeployProject1",
                    "projectVersionName": "1.0.30566"
                },
                {
                    "packageName": null,
                    "projectName": "RESTDeployProject1",
                    "projectVersionName": "1.0.30577"
                },
            ]
        }
    }
}

Example Queries

Here are are few more examples of GraphQL queries. See Fetching Schema and Introspection above for information on how to get our full schemaschema for a full listing of available queries and mutations.

Environment History Report

...

with File Details

This is running the same query used by the Environment History Report with the Show File Details checkbox selected. It is querying the history of all FlexDeploy executions against an environment called “Build” with file-level details being returned. We have a where variable below being used to only filter for the Build environment, as well as a page variable to limit the response to only the first two items.

Code Block
languagegraphql
query reportHistoryFiles($where: [WhereInput], $sort: [SortInput], $page: PageInput) {
    reportEnvironmentHistoryFileDetails(where: $where, sort: $sort, page: $page) {
        items {
            allFilesRequested
            cmsTicketIds
            endTime
            environmentId
            environmentName
            executionStatus
            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
        }
    }
}
Variables
Code Block
{
    "where": [
        {
            "field": "environmentName",
            "type": "eqi",
            "value": "build"
        }
    ],
    "page": { 
        "limit": 2 
    }
}
Response
Code Block
{
    "data": {
        "reportEnvironmentHistoryFileDetails": $sort, page: $page) {
        items {
  "items":  [        allFilesRequested
        {    cmsTicketIds
            endTime
   "projectName": "RESTDeployProject1",        environmentId
            "environmentName":
"Build",            executionStatus
        "instanceName": "Project Rest Test InstancefolderId
1",            instanceId
        "workflowExecutionId": 6114897,   instanceName
            workItemIds
    "executionStatus": "Success",       objectPath
            packageName
"workflowType": "DEPLOY",            partialDeployments
        "streamName": "trunk",     pkgStatus
            poScmRevision
  "projectVersionName": "1.0.30577",         projectId
           "packageName": "", projectName
            projectVersionName
       "objectPath": null,    relDefinitionId
            relName
   "objectType": null,        relSnapshot
            "poScmRevision": null,relSnapshotId
            requestedBy
        "projectId": 759143,   requestedOn
            scmRevision
    "subComponentName": null,       sequenceNumber
            stageExecId
"subComponentType": null,           startTime
         "requestedOn": 1683228165127,  streamName
            workflowExecutionId
     "pkgStatus": null,      workflowId
            workflowRequestId
 "partialDeployments": "N",          workflowType
          "sequenceNumber": null, workflowVersion
        }
    }
}
Variables
Code Block
{
    "stageExecIdwhere": [
null,        {
            "relNamefield": null"environmentName",
            "type": "eqi",
      "relSnapshot      "value": null,"build"
        }
    ],
      "relStatuspage": null,{ 
        "limit": 2 
    }
}
Response
Code Block
{
    "environmentIddata": {
 10050,       "reportEnvironmentHistoryFileDetails": {
             "instanceIditems": 45664,[
                {
   "scmRevision": null,
                    "workItemIdsprojectName": null"RESTDeployProject1",
                    "cmsTicketIdsenvironmentName": null"Build",
                    "startTimeinstanceName": 1683228167140"Project Rest Test Instance 1",
                    "endTimeworkflowExecutionId": 16832281672346114897,
                    "durationexecutionStatus": 94"Success",
                    "folderIdworkflowType": 759142"DEPLOY",
                    "folderNamestreamName": "SoapUI Testingtrunk",
                    "workflowNameprojectVersionName": "Deploy No Action1.0.30577",
                    "relDefinitionIdpackageName": null"",
                    "relSnapshotIdobjectPath": null,
                    "pipelineNameobjectType": null,
                    "workflowIdpoScmRevision": 83363null,
                    "workflowRequestIdprojectId": 1190158759143,
                    "workflowVersionsubComponentName": "1.2" null,
                    "subComponentType": }null,
                     {"requestedOn": 1683228165127,
                    "projectNamepkgStatus": "RESTDeployProject1"null,
                    "environmentNamepartialDeployments": "BuildN",
                    "instanceNamesequenceNumber": "Project Rest Test Instance 1"null,
                    "workflowExecutionIdstageExecId": 6114898null,
                    "executionStatusrelName": "Success"null,
                    "workflowTyperelSnapshot": "DEPLOY"null,
                    "streamNamerelStatus": "trunk"null,
                    "projectVersionNameenvironmentId": "1.0.30577"10050,
                    "packageNameinstanceId": ""45664,
                    "objectPathscmRevision": null,
                    "objectTypeworkItemIds": null,
                    "poScmRevisioncmsTicketIds": null,
                    "projectIdstartTime": 7591431683228167140,
                    "subComponentNameendTime": null1683228167234,
                    "subComponentTypeduration": null94,
                    "requestedOnfolderId": 1683228163189759142,
                    "pkgStatusfolderName": "SoapUI nullTesting",
                    "partialDeploymentsworkflowName": "NDeploy No Action",
                    "sequenceNumberrelDefinitionId": null,
                    "stageExecIdrelSnapshotId": null,
                    "relNamepipelineName": null,
                    "relSnapshotworkflowId": null83363,
                    "relStatusworkflowRequestId": null1190158,
                    "environmentIdworkflowVersion": 10050,"1.2"
                    "instanceId": 45664},
                    "scmRevision": null,{
                    "workItemIdsprojectName": null"RESTDeployProject1",
                    "cmsTicketIdsenvironmentName": null"Build",
                    "startTimeinstanceName": 1683228167138 "Project Rest Test Instance 1",
                    "endTimeworkflowExecutionId": 16832281672186114898,
                    "durationexecutionStatus": 80"Success",
                    "folderIdworkflowType": 759142"DEPLOY",
                    "folderNamestreamName": "SoapUI Testingtrunk",
                    "workflowNameprojectVersionName": "Deploy No Action1.0.30577",
                    "relDefinitionIdpackageName": null"",
                    "relSnapshotIdobjectPath": null,
                    "pipelineNameobjectType": null,
                    "workflowIdpoScmRevision": 83363null,
                    "workflowRequestIdprojectId": 1190157759143,
                    "workflowVersionsubComponentName": "1.0"null,
                }      "subComponentType": null,
      ]         }     }
}

Environment History Report Without File Details

This is querying the history of an environment called “Development” with file details not being returned.

Code Block
query reportHistoryNoFiles($where: [WhereInput], $sort: [SortInput], $page: PageInput) {"requestedOn": 1683228163189,
         reportEnvironmentHistoryNoFileDetails(where: $where, sort: $sort, page: $page) {     "pkgStatus": null,
  items {             allFilesRequested      "partialDeployments": "N",
      cmsTicketIds             endTime "sequenceNumber": null,
          environmentId          "stageExecId": null,
 environmentName             executionStatus      "relName": null,
     folderId             instanceId  "relSnapshot": null,
         instanceName           "relStatus": null,
workItemIds             objectPath       "environmentId": 10050,
    packageName             partialDeployments   "instanceId": 45664,
        pkgStatus             poScmRevision"scmRevision": null,
            projectId        "workItemIds": null,
   projectName             projectVersionName    "cmsTicketIds": null,
       relDefinitionId             relName
"startTime": 1683228167138,
           relSnapshot           "endTime": 1683228167218,
 relSnapshotId             requestedBy      "duration": 80,
     requestedOn             scmRevision  "folderId": 759142,
         sequenceNumber           "folderName": "SoapUI stageExecIdTesting",
            startTime        "workflowName": "Deploy No Action",
 streamName             workflowExecutionId      "relDefinitionId": null,
     workflowId             workflowRequestId  "relSnapshotId": null,
         workflowType           "pipelineName": null,
workflowVersion         }     } }
Variables
Code Block
{     "whereworkflowId": [
83363,
       {             "fieldworkflowRequestId": "environmentName",1190157,
              "type": "eqi",     "workflowVersion": "1.0"
      "value": "development"         }
    ],     "page": {  ]
       "limit": 2}
     }
}
Response

...

Environment History Report without File Details

This is querying the history of our production deployments that failed with file details not being returned. We also want the most recent failed deployment so we will be sorting by date.

Code Block
languagegraphql
query reportHistoryNoFiles($where: [WhereInput], $sort: [SortInput], $page: PageInput) {
        "reportEnvironmentHistoryNoFileDetails"reportEnvironmentHistoryNoFileDetails(where: {$where, sort:            "items": [
$sort, page: $page) {
               items {
            allFilesRequested
       "allFilesRequested": "N",    cmsTicketIds
            endTime
   "cmsTicketIds": null,        environmentId
            "endTime": 1683228177100,environmentName
            executionStatus
        "environmentId": 10051,   folderId
            instanceId
    "environmentName": "Development",       instanceName
            workItemIds
"executionStatus": "Success",           objectPath
         "folderId": 759142,  packageName
            partialDeployments
     "instanceId": 21888,      pkgStatus
            poScmRevision
 "instanceName": "RESTServer",          projectId
          "workItemIds": null, projectName
            projectVersionName
      "objectPath": null,     relDefinitionId
            relName
  "packageName": "",         relSnapshot
           "partialDeployments": "N", relSnapshotId
            requestedBy
       "pkgStatus": null,    requestedOn
            scmRevision
   "poScmRevision": null,        sequenceNumber
            "projectId": 759143,stageExecId
            startTime
        "projectName": "RESTDeployProject1",   streamName
            workflowExecutionId
    "projectVersionName": "1.0.30577",       workflowId
            workflowRequestId
"relDefinitionId": 27201,           workflowType
         "relName": "REST Release 1",workflowVersion
        }
    }
}
Variables
Code Block
{
    "relSnapshotsort": "05-04-2023 14:22:47",[
        {
            "relSnapshotIdfield": 939685,
        "requestedOn",
            "requestedBydirection": "stepworkerdesc",
        }
    ],
      "requestedOnwhere": 1683228173402,[
        {
            "scmRevisionfield": null,
     "environmentName",
              "sequenceNumbertype": null"inci",
            "value": "prod"
       "stageExecId": 939691},
        {
            "startTimefield": 1683228177087"workflowType",
                    "streamName"type": "trunkeq",
            "value": "DEPLOY"
       "workflowExecutionId": 6115046},
        {
            "workflowIdfield": 83363,
   "executionStatus",
                "workflowRequestIdtype": 1190160"eq",
            "value": "Failed"
      "workflowType": "DEPLOY", }
    ],
}
Response
Code Block
{
    "data": {
        "workflowVersionreportEnvironmentHistoryNoFileDetails": "1.2"{
            "items": [
  },                 {
                    "allFilesRequested": "N",
                    "cmsTicketIds": null,
                    "endTime": 16832281772331683228177100,
                    "environmentId": 10051,
                    "environmentName": "DevelopmentProduction2",
                    "executionStatus": "SuccessFailed",
                    "folderId": 759142,
                    "instanceId": 4566421888,
                    "instanceName": "Project Rest Test Instance 1RESTServer",
                    "workItemIds": null,
                    "objectPath": null,
                    "packageName": "",
                    "partialDeployments": "N",
                    "pkgStatus": null,
                    "poScmRevision": null,
                    "projectId": 759143,
                    "projectName": "RESTDeployProject1",
                    "projectVersionName": "1.0.30577",
                    "relDefinitionId": 27201,
                    "relName": "REST Release 1",
                    "relSnapshot": "05-04-2023 14:22:47",
                    "relSnapshotId": 939685,
                    "requestedBy": "stepworker",
                    "requestedOn": 1683228173402,
                    "scmRevision": null,
                    "sequenceNumber": null,
                    "stageExecId": 939691,
                    "startTime": 16832281771881683228177087,
                    "streamName": "trunk",
                    "workflowExecutionId": 61150476115046,
                    "workflowId": 83363,
                    "workflowRequestId": 1190160,
                    "workflowType": "DEPLOY",
                    "workflowVersion": "1.2"
                }
            ]
        }
    }
}