View source for Strategies for integrating Deployment Manager with Jenkins

{{Design pattern
|E-mail notification sent=True
|Title=Strategies for integrating Deployment Manager with Jenkins pipelines|Description=Strategies for integrating Deployment Manager with Jenkins|Version=8.1|Applications=Pega Platform|Capability Area=DevOps|Owner=Ryan Feeney
}}

Deployment Manager provides a suite of APIs for a wide variety of implementation strategies with third-party orchestration tools, including Jenkins. These design patterns outline various strategies to begin incorporating a Deployment Manager pipeline in Jenkins. Although this document is specific to Jenkins, you can apply the same concepts to other third-party tools.

==Use case examples==

==== Approach 1: Deployment Manager as primary orchestrator ====

* In this approach, the application uses a typical Deployment Manager configuration consisting of merge and deployment pipelines. However, each deployment triggers a Jenkins job that collects deployment metrics for consolidated reporting.
* This approach is easier to set up, but provides less visibility into the status of ongoing deployments in Deployment Manager.
[[File:DeploymentManager_as_primary_orchestrator.png|alt=Using Deployment Manager as primary orchestrator.|center|frameless|Using Deployment Manager as primary orchestrator.]]


==== Approach 2: Jenkins as Primary Orchestrator ====

* In this approach, Jenkins is the primary orchestrator of the entire process, delegating all Pega-specific tasks to Deployment Manager.
* Merge pipelines trigger the Jenkins job, allowing Pega developers to trigger deployments directly from Dev studio without any additional configuration.
* This approach requires additional effort to set up, but provides greater visibility into the status of ongoing deployments in Deployment Manager.
[[File:Jenkins_as_Primary_orchestrator.png|alt=Using Jenkins as primary orchestrator.|center|frameless|Using Jenkins as primary orchestrator.]] 

==Before you begin==
Review the following documentation before proceeding with these approaches.

* [https://community.pega.com/knowledgebase/articles/devops/85/installing-or-upgrading-deployment-manager-5x Configuring Deployment Manager]
* [https://community.pega.com/knowledgebase/articles/devops/85/configuring-jenkins-51x Configuring Jenkins integration]

==Process/Steps to achieve objective==

==== Approach 1:  Deployment Manager as Primary Orchestrator ====
Create a deployment pipeline and a merge pipeline in Deployment Manager to promote your application. See [https://community.pega.com/knowledgebase/articles/devops/86/creating-pipelines Creating pipelines in Deployment Manager] for more information. Next, call a Jenkins job as the final step of a deployment pipeline. This Jenkins job will connect to Deployment Manager using the APIs to collect information, such as:

* Agile workbench items
* Branch names
* Test coverage percentages
* Test executions
* Artifact locations
* Approvers

See the code from the Jenkins approach below as a starting point for metric collection. 

==== Approach 2: Jenkins as Primary Orchestrator ====
Although this approach requires more effort, using Jenkins provides greater visibility of your deployment status.

# Create a deployment pipeline in Deployment Manager, and capture the pipeline ID.
# Create a Jenkins pipeline project and follow all the guidance from the Jenkins configuration document.
# Add additional parameters: 
#* '''DeployPipelineId''' - Set the default value to the pipeline ID from step 1.
#* '''BranchName'''
#* '''CallBackURL'''
# Populate the pipeline definition as a script using the boilerplate code below.
# Trigger the pipeline and ensure that the Deployment Manager pipeline starts.
# Abort the Deployment Manager pipeline and the Jenkins pipeline should end.
# Create a merge pipeline and add a Jenkins task to the final step, invoking the Jenkins job from step #2.
# Trigger the merge pipeline, starting the deployment process in Jenkins when it completes.
The following boilerplate code can be added to a Jenkins pipeline definition to get you started.<syntaxhighlight lang="groovy" line="1">
import groovy.json.JsonSlurper

def deploymentStatus
def deploymentId
pipeline {
    agent any
    environment {
        DM_AUTH = credentials('DM_AUTH')
    }
    stages {
        stage('Trigger Deployment') {
            steps{
                script {
                    if(env.BranchName != ""){
                        echo "Completing the merge deployment"
                            resolveMergeDeployment(env.CallBackURL)
                    }
                    deploymentId = startDeployment(env.DeployPipelineId)
                }
            }   
        }

        stage('Wait for deployment complete'){
            steps{
                waitUntil{
                    script{
                        deploymentStatus = getDeploymentStatus("Pipeline-CNVQW", deploymentId)
                        if(deploymentStatus.contains("Resolved-")){
                            return true
                        }
                        return false
                    }
                }
                script{
                    if(deploymentStatus.contains("Resolved-Aborted")){
                        error('The deployment manager deployment was aborted')
                    }    
                }
            }
        }
        stage('Collect deploment metrics'){
            steps{
                echo 'TODO'
            }   
        }
    }
}

def getPipeline() {
    def token = getToken();
    def pipelineDef = sh(script: "curl --insecure -H \"Content-Type: application/json\" -H \"Accept: application/json\" -H \"Authorization:Bearer ${token}\" -k -X GET $OrchestratorURL/PRRestService/DeploymentManager/v1/pipelines/${pipelineId}",  returnStdout:true).trim()
    return pipelineDef
}

def addStagesFromPipeline(){
    def stagesJSON = getPipelineStages()
    new JsonSlurper().parseText(stagesJSON).each { pipelineStage ->  
        stage(pipelineStage.name) {
            steps{
                echo pipelineStage.name                                    
            }
        }
    }
}

def startDeployment(pipelineId){
    def token = getToken();
    deploymentId = sh(script: "curl -H \"Content-Type: application/json\" -H \"Accept: application/json\" -H \"Authorization:Bearer ${token}\" -k -X POST $OrchestratorURL/PRRestService/DeploymentManager/v1/pipelines/${pipelineId}/deployments | jq -r .deploymentID",  returnStdout:true).trim()
    return deploymentId
}

def getDeployment(pipelineId, deploymentId){
    def token = getToken();
    deployment = sh(script:"curl -H \"Content-Type: application/json\" -H \"Accept: application/json\" -H \"Authorization:Bearer ${token}\" -k -X GET $OrchestratorURL/PRRestService/DeploymentManager/v1/pipelines/${pipelineId}/deployments/${deploymentId}",  returnStdout:true)
    return deployment
}

def getDeploymentStatus(pipelineId, deploymentId){
    deployment = getDeployment(pipelineId, deploymentId)
    deploymentStatus = sh(script:"jq .status <<<'${deployment}'",  returnStdout:true)
    return deploymentStatus
}

def getToken(){
    sh(script: "curl -d \"client_id=$DM_AUTH_USR&client_secret=$DM_AUTH_PSW&grant_type=client_credentials\" $OrchestratorURL/PRRestService/oauth2/v1/token | jq -r .access_token",  returnStdout:true).trim()
}

def resolveMergeDeployment(CallBackURL){
    def token = getToken();
    sh(script:"curl -H \"Content-Type: application/json\" -H \"Accept: application/json\" -H \"Authorization:Bearer ${token}\" -k -X PUT --data '{\"taskStatus\":\"Resolved-Completed\",\"taskInfo\":{\"outputParameters\":[{\"name\": \"BuildNumber\",\"type\": \"Text\",\"value\": \"%BUILD_NUMBER%\"},{\"name\": \"JenkinsBuildURL\",\"type\": \"Text\",\"value\": \"%BUILD_URL%\"}]}}' ${CallBackURL}",  returnStdout:true)
}

</syntaxhighlight>

==Results==
You now have everything you need to create a simple Jenkins pipeline to expose ongoing Pega deployments from within the Jenkins dashboard.