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.

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

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

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