Share this page

# Work with CI servers, pipelines, and builds

You can use API resources to collect information from your CI server and inject it for use in ALM Octane.

Here are some basic methods for working with CI servers, pipelines, and builds using the REST API.

Tip: There are many ways to use the REST API to work with CI servers, pipelines, and builds. We recommend you use the interactive API client to explore the syntax for other options. For details, see Interactive API client.

In this topic:

## Overview

For full functionality, work with CI Servers and pipelines using the ALM Octane UI and its associated plugins. For details about the overall process, including measuring your release and product quality and following your build progress, see CI server integration flow.

The limited functionality that is available with the REST API is useful for those who cannot use the Application Automation Tools and Application Automation Tools plugins.

## Add a CI server (POST)

Create a CI Server entity as a top-level context of CI data submitted. This is done once.

- name is required and must be unique in the shared space.

- instance_id is optional. If not provided, ALM Octane generates it. This instance ID is a unique string and should not be confused with the internally numbered IDs that ALM Octane uses. This value is fully maintained by the consumer of the API, can be any unique string, and should consistently be used in all further APIs usages (pipelines, builds, tests results) as a primary CI context identifier.

- url is optional. If no URL is provided, the REST API cannot redirect users to the CI Server itself, so it is highly recommended that you do provide the base URL of the CI Server.

- server_type is optional. If not provided, "unknown" is used.

    *** Request ***

    POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/ci_servers

    Accepts:        application/json

    Produces:       application/json

    	{
    		"data": [{
    		    "name": "The server name, for display purposes",
    		    "instance_id": "12345-123",
    		    "url": "http://some.url:8383",
    		    "server_type": "teamcity"
    		}]
    	}

    *** Response ***

    	{
    	    "total_count": 1,
    	    "data": [
    	        {
    	            "type": "ci_server",
    	            "id": "6005"
    	        }
    	    ]

    }

See the results in the ALM Octane UI

After posting a CI server, you can check that it exists in the ALM Octane UI.

Note: When creating CI servers directly from within the ALM Octane UI, plug-ins make sure that the CI server is "connected." Because this CI server was created with the REST API, it is shown as NA. This is not a problem when working with the REST API for limited functionality. Continue working as usual.

Back to top

Examples

Other examples of working with CI servers

- Retrieve information about a specific CI server with ID number 1001:

  `GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/ci_servers/1001`

- Retrieve all CI servers:

  `GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/ci_servers`

- Delete a CI server with ID number 1001:

  `DELETE .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/ci_servers/1001`

- Update a CI server with ID number 1001:

  `PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/ci_servers/1001`

      *** Request***

      	{
      		   "name": "Your server name, for display purposes",
      		   "url": "http://some.other.url:8383",
      		   "server_type": "custom_ci"
      	}

      *** Response ***

      	{
      	       "type": "ci_server",

      	       "id": "6005"
      	}

Back to top

## Add a pipeline (POST)

Create a pipeline as it reflects the build flow to be tracked and visualized. This pipeline becomes the basic context for the tests to be submitted. This is done once.

- name is required. The pipeline name must be unique in the shared space.

  Each pipeline is linked to a CI Server, and the CI Server is identified by the CI internal instance ID.

- server_ci_id is required. This must be the same value that was previously provided as the instance_id. This value is fully maintained by the consumer of the API and should be used as defined in the CI server and Pipeline APIs.The CI server must already exist before creating pipelines and linking them to it. For details, see Add a CI server (POST).

- The keyword jobs is required, and precedes the array of jobs in the pipeline. jobs must contain at least the root job, referred to with the root_job_ci_id attribute.

  Job attributes:

  - For each job, jobCiId is required. This value is fully maintained by the consumer of the API and should be used as defined in the CI server and Pipeline APIs.

  - The jobCIId must be unique across all the jobs provided in context of this CI Server (meaning, under this server_ci_id). This is true not only for this API invocation but across all the pipelines ever created within this CI Server.

  - Each job has a name. The name is optional. If not provided, jobCiId is used.

  - Each job can have parameters. The parameters are optional.

    Parameter attributes:

    - The type of the parameter is optional. Allowed types are: "boolean", "string", "number", "axis", "file", "password", "unknown"

    - The name of the parameter is mandatory.

    - The description, defaultValue, and value attributes are optional.

- root_job_ci_id is required. root_job_ci_id corresponds to the jobCiId property of one of the jobs provided in the jobs array.

Back to top

    POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/pipelines

    Accept:     application/json
    Produces:   application/json

    *** Request ***

    {
      "data": [
        {
          "jobs": [
            {
              "jobCiId": "MyRootJob",
              "name": "The name of the root job"
            },
            {
              "jobCiId": "MyNextJob",
              "name": "The name of the next job"
            }
          ],
          "name": "MyPipelineIDName",
          "root_job_ci_id": "MyRootJob",
          "server_ci_id": "MyInstanceID"
        }
      ]
    }

    *** Response ***

    {
      "total_count": 1,
      "data": [
        {
          "type": "pipeline",
          "id": "1007"
        }
      ],
      "exceeds_total_count": false
    }

See the results in the ALM Octane UI

After posting a pipeline and its jobs, you can check that they exist in the ALM Octane UI.

Back to top

Examples

Other examples of working with pipelines

- Retrieve information about a specific pipeline with ID number 1001:

- Retrieve all pipelines:

  `GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/pipelines`

- Delete a pipeline with ID number 1008:

  `DELETE .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/pipeline/1008`

- Update the release of a pipeline with ID number 1007:

      PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/pipelines/1007

      *** Request***

      {
        "name": "MyPipelineIDName",
        "current_release": {
          "id": "1035,"
          "type": "release"
        }
      }

      *** Response ***

      {
        "type": "pipeline",
        "id": "1007"
      }

Back to top

## Update build statuses (PUT)

Add a build to a pipeline and update the status of the pipeline jobs. Each build is equivalent to an event in the pipeline. This is done on an ongoing basis.

- The CI server ID serverCiId and the job ID jobCiId are mandatory.

- The build ID buildCiId is mandatory and is used for viewing test results. This value is fully maintained by the consumer of the API and should be used as defined in the Pipeline APIs.

- buildName is optional. If not provided, buildCiId is used.

- status is optional. If not provided, finished is used.

- parameters and causes are optional.

- startTime, duration, and result are mandatory.

- The status of the build event is optional. Allowed statuses are: ”finished", "running", "unavailable"

- The results of the build event is optional. Recommended results are: "success", "failure", "unstable", "aborted", "unavailable"

- Each build is updated via two requests: the first with a status of running and the second with status of finished.

- In the case of hierarchical jobs, child jobs must use causes, and must be run after the parent is running and before the parent is finished.

Start root job build

    PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/analytics/ci/builds

    *** Request ***

    {
        "serverCiId": "12345-123",
        "jobCiId": "MyRootJob",
        "buildCiId": "MyRootJob-1",
        "buildName": "Short name for build",
        "startTime": 1456679398786,
        "duration": 120490,
        "status": "running",
        "result": "unavailable"
    }

Start sub job build

    PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/analytics/ci/builds

    *** Request ***

    {
        "serverCiId": "12345-123",
        "jobCiId": "MyNextJob",
        "buildCiId": "MyNextJob-1",
        "buildName": "Short name for build",
        "startTime": 1456679398786,
        "duration": 120490,
        "status": "running",
        "result": "unavailable",
        "causes": [{
            "jobCiId": "MyRootJob",
            "buildCiId": "MyRootJob-1"
        }]
    }

End sub job build

    PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/analytics/ci/builds

    *** Request ***

    {
        "serverCiId": "12345-123",
        "jobCiId": "MyNextJob",
        "buildCiId": "MyNextJob-1",
        "buildName": "Short name for build",
        "startTime": 1456679398786,
        "duration": 120490,
        "status": "finished",
        "result": "success",
        "causes": [{
            "jobCiId": "MyRootJob",
            "buildCiId": "MyRootJob-1"
        }]
    }

End root job build

    PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/analytics/ci/builds

    *** Request ***

    {
        "serverCiId": "12345-123",
        "jobCiId": "MyRootJob",
        "buildCiId": "MyRootJob-1",
        "buildName": "Short name for build",
        "startTime": 1456679398786,
        "duration": 120490,
        "status": "finished",
        "result": "success"
    }

See the results in the ALM Octane UI

After updating a build, you can check it in the ALM Octane UI.

Back to top

## View test results (test_results resource)

View test results in the context of the CI server, pipeline, and build. This is done on an ongoing basis. For details, see Add automated test results to ALM Octane.

Back to top

See also:

- Test results
- Report results from a pipeline
- CI server integration flow

https://admhelp.microfocus.com ALM Octane 8942
Tips to improve your search results... ALM Octane Help Center ALM Octane Help 23.4-24.3 All View Local Help Center View Online Help Center Version: