Managing API-driven pipelines

API-driven pipeline applications

Before you begin

Create a value stream and its pipeline. See Creating a value stream and Managing pipelines.
Configure a Jenkins integration and create a Jenkins build job. See Configuring Jenkins integrations.
Create a user access key with permission to upload build and deployment information. See Managing user access keys.
Ensure that the Jenkins agent can access the Velocity server.

About this task

API-driven pipeline applications enable you to effectively populate the pipeline and move dots through the system solely through build and deployment uploads. The create build and upload deployment API commands are displayed in the UI and can be executed in a command terminal. These APIs provide simplified endpoints for loading data and allow you to integrate the pipeline with unsupported tools. You can run the API commands manually for testing or add them to a Jenkins job to automate build and deployment status updates. The relationship between the APIs and the pipeline phases that they populate is detailed in the following table.

API	Pipeline phases
builds/apiDriven	Input
deployments/apiDriven	DEV, QA, PROD, and any environments in the pipeline.

Procedure

To map an application environment to the pipeline on the Pipeline page, complete the following steps:

For the environment where you want to add the application, click Add app.
On the Add app - Choose the app window, in the Managed by list, select API-driven.
Click either the Create new application or Use existing appplication radio button.

Note: The Managed by and Description fields are already populated with API-driven.

Based on the radio button you chose in the previous step, use the required procedure in the following table:

Create new application	Use existing application
In the Application name field, enter the name for the application. Click Save to add the application to the stage.	This option links your pipeline application to an already existing application in HCL DevOps Velocity (Velocity). You can use the API-driven REST API to create new versions and deployments for this application. Click the Existing application type drop-down to list all the applications in your database and select the application. Note: If you want to use the API to create versions and run deployments for plugins without pipeline capabilities, select Other. Click the Existing application name drop-down to list and then select the application. Click Save to add the application to the stage.

Create new application

Use existing application

In the Application name field, enter the name for the application.
Click Save to add the application to the stage.

This option links your pipeline application to an already existing application in HCL DevOps Velocity (Velocity). You can use the API-driven REST API to create new versions and deployments for this application.
Click the Existing application type drop-down to list all the applications in your database and select the application. Note: If you want to use the API to create versions and run deployments for plugins without pipeline capabilities, select Other.
Click the Existing application name drop-down to list and then select the application.
Click Save to add the application to the stage.

To upload a build that will create a new version for the application, complete the following steps:
1. Click under the Input stage of the pipeline for the TEST API-driven Application application, used as an example and shown in the figure below.
  The Create version modal displays a curl command, shown in the figure below, to interact with the TEST API-driven Application REST API.
  Note: The Application name entered previously in the Add apps - Choose the apps window is displayed in the Create version modal window above the curl command. Refer to this page for more details on the builds/apiDriven API.
2. Click to copy the curl command.
3. Paste the curl command in any text editor.
4. Edit the following user provided fields: <User Access Key>, <Version Name>, <Build URL>, and <Commit SHA>.
5. Copy the curl command.
6. Paste the curl command into a terminal or CI/CD automation scripts having network access to the Velocity server.
  
  Note: The displayed commands only work in the UNIX operating system. For MS-DOS operating systems, modifications will be required.
7. Run the curl command to update the new version of the application in Input environment.
  
  Note: Running these commands manually in a terminal are typically performed for several initial test runs. This method is not recommended for production use. For best practice, add the create build and upload deployment curl commands directly in the CI/CDs for automatic triggering.
  
  The curl command updates the version of the application in all applicable pipelines successfully.
Notify the pipeline of an Input version deployment by completing the following steps:
1. Click under the DEV stage of the pipeline for the TEST API-driven Application application, used as an example and shown in the figure of the previous step.
  The Create a deployment through the API (DEV) modal window will display a curl command, shown in the figure below, to interact with the TEST API-driven Application REST API to upload a deployment to the aforementioned application.
  Note: The Application name entered previously in the Add apps - Choose the apps window is displayed in the Upload deployment status modal window above the curl command. Refer to this page for more details on the deployments/apiDriven API.
2. Click to copy the curl command.
3. Paste the curl command in a text editor.
4. Edit the following user provided fields: <User Access Key>, <Version Name>, and <Deployment URL>.
5. Copy the curl command.
6. Paste the curl command into a terminal or CI/CD automation scripts having network access to the Velocity server.
  
  Note: The displayed commands only work in the UNIX operating system. For MS-DOS operating systems, modifications will be required.
7. Run the curl command to update the new version of the application in DEV environment.
  
  Note: Running these commands manually in a terminal are typically performed for several initial test runs. This method is not recommended for production use. For best practice, add the create build and upload deployment curl commands directly in the CI/CDs for automatic triggering.
  
  Succesfull run of the curl command updates the version of the application in all applicable pipelines.
To automate build and deployment status updates with Jenkins, add the API commands to the build steps of the Jenkins job.
1. In the Jenkins job, add the builds/apiDriven command after the application build completes.
  Use the Jenkins environment variables for the version, build URL, and commit revision. Store the user access key as a protected Jenkins credential. Do not enter the key directly in the Jenkins job configuration.
```
curl -k -X POST "https://<velocity_server>/api/v1/builds/apiDriven" \
    -H "Authorization: UserAccessKey <user_access_key>" \
    -H "Content-Type: application/json" \
    -d "{\"version\":\"%BUILD_NUMBER%\",\"application\":{\"externalId\":\"<application_external_id>\"},\"url\":\"%BUILD_URL%\",\"revision\":\"%GIT_COMMIT%\"}"
```
  For parameter descriptions, see Uploading a build to a pipeline.
2. After the build upload succeeds, add a deployments/apiDriven command for each environment in which the version is deployed.
  Replace <environment_name> with the target environment, such as DEV, QA, or PROD.
```
curl -k -X POST "https://<velocity_server>/api/v1/deployments/apiDriven" \
    -H "Authorization: UserAccessKey <user_access_key>" \
    -H "Content-Type: application/json" \
    -d "{\"version\":{\"name\":\"%BUILD_NUMBER%\"},\"application\":{\"externalId\":\"<application_external_id>\"},\"url\":\"%BUILD_URL%\",\"environment\":{\"name\":\"<environment_name>\"}}"
```
  For parameter descriptions, see Uploading deployment status.
3. Run the Jenkins job and review the version and deployment status in the pipeline.
  The build version is displayed in the Input stage, and the deployment status is displayed in each target environment.
Perform the same for any required environments.