Note: This doc is for 4.x version of Deployment Manager

Introduction:

Deployment manager supports integration with Jenkins out of the box and can be extended to work with other CI tools like Bamboo, Azure Deploy and others

This document will walk through the process of integrating with Bamboo and will be a reference guide to integrate with any other tool which has the REST API’s exposed for triggering and managing builds. This guide is relevant for Deployment Manager 4.x series.

Part 1: Steps to Create new task:

1. Create new abstract class inherited from Pega-Pipeline-Task, as we are integrating with Bamboo, we will name the class as Pega-Pipeline-Task-Bamboo
2. Change the Label of Class as Run Bamboo Plan, this will be shown Pipeline Model while adding tasks.

Update Task Defaults:

The next series of steps are about defining some task properties such as declaring if the task is synchronous or asynchronous, updating the task description and task icon. Task description and icon will be shown to user when adding task.

1. To update the task description, create new field value, pyTaskDescription, as below this will be shown in task description in pipeline model.

2. Create a new Data Transform pySetPipelineTaskDefaults in Pega-Pipeline-Task-Bamboo class as below

Here we are setting pyTaskDescription to the newly created field value. As Bamboo plans can run for longer time, we are setting the task to Aysnchronous. We can also update the task icon by uploading new binary file and setting it to pyPipelineTaskImage property. Use pyTaskDescription property in pyTaskParameters section as shown in next section. The field value we added will be shown while adding task as below. We also need to create properties required for running Bamboo build that will be discussed in next section.

Passing parameters required for Bamboo Plan:

1. Here we are running bamboo plan by taking Project ID and Plan ID as parameters, to pass the Parameters we need to create the properties and create a section to update the properties a below. If you need to integrate with any other external system that requires different properties, you can create them and refer as below.
2. Create pyProjectID, pyPlanID properties in Pega-Pipeline-Task-Bamboo class
3. Create pyTaskParameters section as below and refer pyProjectID, pyPlanID, pyTaskDescription as below

Note: We can also create properties for capturing Authentication profile and Bamboo URL so that you have an option to enter appropriate Bamboo URL when configuring the task in the URL. For the purpose of this document, the URL is hardcoded to one and is described in the next section.

Task Execution:

1. Create new flow pyProcessTask in Pega-Pipeline-Task-Bamboo class that will be run as part of task execution.
2. In the above flow we need run an Activity which will invoke the call to Bamboo.  Create a new Activity ex: pzTriggerBambooJob, refer this Activity in the pyProcessTask flow created in the previous step. You can create Activity with any name.
3. The Parameters defined while adding task will be available to the flow as parameters with same name:

We can use these parameters in the Activity to make call to Bamboo. Here we are passing pyProjectID and pyPlanID which will be specified when adding tasks and passed along to pzTriggerBambooJob Activity.

4. Create a new REST connector which will be used to make call to Bamboo such as pzTriggerBambooJob.
5. Create Authentication Profile to be used to run Bamboo plan, such as BambooAuth.

The next step is to make REST call to run the Bamboo plan using the pzTriggerBambooJob   Activity.

1. 1. Here we will need to construct the call back URL and send it as parameter in the URL to Bamboo.
   2. Each deployment creates work object , when we actually run Bamboo task the work object will call Bamboo and waits to be resumed by  Bamboo, so we also need to send CaseInsKey  ie:pzInsKey to resume the flow once the Bamboo plan execution is completed. The current state of build ie: work object will be available in pyCurrentBuildState page.

6. Set all the properties required for REST call as below and invoke the REST Call. In the ResourcePath parameter which we are setting below to make the REST Call we also need to pass CaseInsKey, the CaseInsKey will be available in pyCurrentBuildState page.

1. Set CallBackURL as below:

http://hostname/prweb/PRRestService/cicd/v1/task/Bamboo/status?FlowName=pxProcessTask&FlowActionName=pzProgressTask

        Note: Hostname is the Orchestrator URL

2. Set CaseInsKey as below:

      The CaseID will be available in pyCurrentBuildState page we can set this to Param.CaseInsKey parameter and send in URL.

3. Set Resource Path to make REST Call to Bamboo:

"https://<BambooURL>/bamboo/rest/api/latest/queue/"+Param.ProjectID+"-"+Param.PlanID+"?executeAllStages=true&bamboo.variable.BuildID="+Param.CaseInsKey+"&bamboo.variable.CallBackURL="+ Param.CallBackURL

Here the activity is coded with a specific Bamboo URL directly, but this can be prompted as an input from the task UI and the corresponding parameter could be used instead of the hard-coded URL. We can also refer Authentication Profile similarly.

If the REST Call fails, we need to set the error message on pyErrorMessage property of primary page, and this error will be shown in Pipeline landing page and in reports.

Note: As a reference look at pzTriggerJenkinsJob Activity which also works in a similar way.

Part 2: Callback from Bamboo and parameters:

1. As discussed above, we will be passing BuildID and CallBackURL as parameters from Deployment Manager, therefore we need to define them in our Bamboo Plan before running the task. The CallBackURL variable defined will be used to make callback to Orchestrator after execution of Bamboo task.

Once we add the task in Deployment Manager and run it, after the plan execution has completed, we can run a script to make the callback as shown below using curl (or an equivalent command line utility to that can invoke http/https protocols).

1. 1. If the bamboo plan is successful, we need to send pyStatusValue as SUCCESS and if the bamboo plan fails set the pyStatusValue as FAIL
   2. Set pyStatusMessage as an appropriate error message if Bamboo Job fails.
   3. Use DMReleaseAdmin or Operator who has access to Deployment Manager to make call back to orchestrator.

Below is the sample curl command to make call back to Orchestrator we are using

curl --user "DMReleaseAdmin":"rules" -H "Content-Type: application/json" -X POST --data "{\"buildNumber\":\"$bamboo_BuildID\",\"pyStatusValue\":\"FAIL\",\"pyStatusMessage\":\"Run failed with unknown reason check bamboo logs\",\"pyID\":\"$bamboo_BuildID\"}" $bamboo_CallBackURL

2. Once we make callback to Orchestrator using curl, Deployment Manager resumes the flow and it will set error message if pyStatusValue is FAIL.To set the error message we need to override the pyTaskCallbackHandler Activity.

3. Create pyTaskCallbackHandler Activity in our task class, Pega-Pipeline-Task-Bamboo, and the parameters which we pass here are available in the Activity as parameters. In below section when pyStatusValue is FAIL we are seeting error message, when pyStatusValue is SUCCESS the flow will resume and this Activity will not be called.

After the call back the Deployment proceeds to next task if there are no errors and if we have any error the Deployment waits at current task for user action, you can rerun the task or Abort the build.

The above steps would work for integration with other CI tools as well which have REST API’s exposed. You must replace the Bamboo specific details with the tool specific parameters.

Seek appropriate input parameters by adding properties to the task UI and use the pyProcessTask extension flow for triggering the appropriate REST API for the corresponding action.