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 OpenText Core Software Delivery Platform.

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

In this topic:

Overview

For full functionality, work with CI Servers and pipelines using the OpenText Core SDP 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, an instance ID is generated. This instance ID is a unique string and should not be confused with the internally numbered IDs that OpenText Core SDP 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 UI

After posting a CI server, you can check that it exists in the OpenText Core SDP UI.

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.

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
}

Check the results in the UI

After posting a pipeline and its jobs, you can check that they exist in the OpenText Core SDP UI.

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 UI

After updating a build, you can check it in the OpenText Core SDP 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.

Back to top