Getting started with GraphQL in HCL DevOps Velocity (Velocity)

You can use GraphQL Playground in explore and test APIs interactively before using them in real scenarios. This GraphQL playground provides a convenient environment to use queries and mutations, that helps you understand the available data and how to structure requests effectively.

GraphQL is a flexible and efficient query language for APIs that allows you to request exactly the data you need. Unlike traditional REST APIs that return fixed data structures, GraphQL helps you define the shape of the response, fetch related data in a single request, and interact with data using queries (to read data) and mutations (to create or update data).

With GraphQL in HCL DevOps Velocity (Velocity), you can use queries to retrieve value stream data, such as work items, deployments, commits, and other DevOps artifacts, and use mutations to create or manage resources.

Setting up GraphQL with API endpoints

Before you begin, you must create a user access key. See Managing User access keys (UAKs).

Follow the steps to set up and authenticate the GraphQL Integrated Development Environment (IDE) in DevOps Velocity:

Navigate to the Velocity instance GraphQL interface using https://my_velocity:port/graphiql.
Click the Set Headers icon.
Enter Authorization in the Header key field.
Enter the user access key in the Value field.

After the authentication is complete, you can start using different GraphQL APIs to validate responses and refine your queries. The GraphQL Playground also provides built-in documentation for each query and mutation, allows you to easily explore available fields, input parameters, and response structures.

After testing, you can use these APIs in your applications or leverage them to create and manage resources in HCL DevOps Velocity (Velocity) for bulk operations or automation scenarios without using the UI.

Mutations

Mutations are used to create new data, update existing data, and delete existing data.

Here are a few examples of mutations that you can use in Velocity.

Create a Value Stream
A Value Stream represents the flow of work items through a pipeline. It helps you visualize how work items move from one stage to another across various tools in the pipeline. To create a new value stream, you can use the following GraphQL mutation:
```
mutation {
  createValueStream(
    name: "string"
    description: "string"
    tenantId: "_____"
    team: { id: "string", name: "string" }
    workflow: "_____"
  )
}
```

Add an environment to a pipeline

A pipeline defines the series of steps required for deploying software, while stages represent the different phases of the pipeline (for example, build, deploy, test). To add a new stage to a pipeline, you can use the following GraphQL mutation:

mutation {
  addPipelineStages(
    pipelineId: "Pipeline_ID",
    stages: [{ name: "<Stage_name>", type: "<Stage_type>" }]
  ) {
    _id
    name
    type
    description
    planId
    triggers {
      _id
      name
    }
    gates {
      _id
      name
    }
    cf_space_id
    promoteTo
    latestAutopromotionStatus
    deploymentModes
    defaultDeploymentMode
    groupsAndUsers
    solutionVersionId
  }
}

Add an application to a pipeline

To add an application to a pipeline, you can use the following mutation:

mutation {
  addApplications(
    pipelineId: "_____"
    applications: [{ name: "string" }]
    processes: [{ name: "string" }]
    type: "string"
  ) {
    _id
    name
    tenant_id
    description
    stages {
      _id
      name
      type
      description
      planId
      triggers
      gates
      cf_space_id
      promoteTo
      latestAutopromotionStatus
      deploymentModes
      defaultDeploymentMode
      groupsAndUsers
      solutionVersionId
      solutionVersion
    }
    applications {
      _id
      name
      type
      description
      processes
      source
      inputJobId
      stages
      subApplications
      children
      level
      external_id
      selectedChildren
      versionRegEx
    }
    synchronize
    team {
      id
      name
      tenantId
    }
    created
    stats {
      leadTime
    }
  }
}

Queries

You can access detailed information from HCL DevOps Velocity (Velocity) by using GraphQL queries.

The following are some example queries that demonstrate how to retrieve various types of data.

Get application data by using the application ID

You can retrieve detailed information about a specific application by using its ID and the following query:

{
  applicationById(id: "<Application_ID>", tenantId: "<Tenant_ID>", loadChildren: true) {
    _id
    id
    external_id
    tenant_id
    integration_id
    name
    alphaNumericName
    active
    createdAdHoc
    json_data
    type
    version
    level
    childrenIds
    children {
      _id
      id
      external_id
      tenant_id
      integration_id
      name
      alphaNumericName
      active
      createdAdHoc
      json_data
      type
      version
      level
    }
  }
}

Retrieve the application environment details by tenantID

To retrieve all unique application environment details for a given tenantID, you can use the following query::

{
  applicationEnvironmentsByTenantId(tenantId: "TenantID") {
    _id
    id
    external_id
    tenant_id
    name
    app_id
    external_app_id
    active
    json_data
    type
    version
    inventory {
      external_version_id
      components
    }
  }
}

Retrieve application environment name by tenantID
To retrieve all unique application environment names for a given tenantID, you can use the following query:
```
{
  uniqueApplicationEnvironmentNamesByTenantId(tenantId: "_____") {
    name
  }
}
```