Creating BMC Helix ITSM change requests from Jenkins pipelines by using Jitterbit Harmony

BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template that enables you to track a Jenkins pipeline from BMC Helix ITSM. When a pipeline is triggered, the template leverages an existing change request that is created from the BMC Helix ITSM and Jira integration, or creates a change request. 
To use the integration template with the values defined out of the box, you update the project variables with details of your systems and deploy the integration template. 

The template provides the following capabilities: 

The following status mappings between a stage and a task are available:

Jenkins to BMC Helix ITSM data flow by using an existing change request

The following image gives an overview of the data flow from Jenkins to BMC Helix ITSM when a change request already exists:

Jenkins to BMC Helix ITSM data flow by creating a change request

The following image gives an overview of the data flow for creating a BMC Helix ITSM change request from a Jenkins pipeline and shows how the change request is updated:

The following video (2:03) gives a quick overview of the BMC Helix ITSM integration with Jenkins:

 Watch the YouTube video about BMC Helix ITSM and Jenkins integration

Before you begin

You require the following items to successfully set up and use this integration: 

Task 1: To download and import the integration template project file

1. Download the Sync Jenkins Pipeline to BMC Helix ITSM Change Request 2023-01-03 project file to your system. 
   This file contains the BMC Helix iPaaS Integration Studio project Sync Jenkins Pipeline to BMC Helix ITSM Change Request.
   

   Important

   Your ability to access product pages on the EPD website is determined by the license your company purchased.

2. As a developer, log in to BMC Helix iPaaS and navigate to the Integration Studio.
3. On the projects page, click Import.
4. Click Browse and then select the Sync Jenkins Pipeline to BMC Helix ITSM Change Request 2023-01-03 file you downloaded. 
   The Project Name and Organization fields are automatically populated depending on the values defined. 
5. From the Environment list, select the environment to which you want to import this integration template, and click Import.
   The project opens after the integration template is imported.
6. (Optional) To open the project file at a later time, select the environment where the integration templates are available, select the Sync Jenkins Pipeline to BMC Helix ITSM Change Request project and click View/Edit.

Task 2: To update the Jenkins pipeline script

Perform the following steps in the Jenkins pipeline script from which you want to create a change request:

1. In the pipeline script, add the following information:

   Information type	Information
   Variable	env.ITSM_CR="" When the pipeline is run, this variable is autopopulated. env.ITSM_CR_STATUS="Draft"
   Methods	def getCRStatus()—Checks the status of a change request until it is set to Implementation in progress to start executing a pipeline stage. In the script, call this method after the pipeline starts. Click here to view the code for this method def getCRStatus(){     def body ="""             {                 \"pipelinename\":\"${JOB_NAME}",                 \"build_number\":\"${BUILD_NUMBER}\",                 \"crq_number\":\"${ITSM_CR}\"             }             """     iter = 1     while(env.ITSM_CR_STATUS != "Implementation In Progress"){         sleep 10         echo("Waiting for the change request to move in progress")         echo "Iteration count "+iter         resp = httpRequest acceptType: 'APPLICATION_JSON', contentType: 'APPLICATION_JSON',             httpMode: 'GET',             requestBody: body,             url: 'https://BMCQA450391.jitterbit.net/BMC_QA_MULTI_AGENT_WINDOWS/jenkinsToCrq'             response = resp.content             println("Response: "+response)             props = readJSON text: response, returnPojo: true             changeStatus = props["status"]             changeReqId = props["change_req_id"]             env.ITSM_CR = changeReqId             env.ITSM_CR_STATUS=changeStatus             println("Change Req Id :"+env.ITSM_CR)             println("Current Change Status :"+env.ITSM_CR_STATUS)                iter++     } } def notify(name, status)—Synchronizes the status of a pipeline stage with a task. In the script, call this method for each pipeline stage.  Click here to view the code for this method def notify(name) {     getCRStatus()     def body ="""             {                 \"stagename\":\"${name}\",                 \"pipelinename\":\"${JOB_NAME}\",                 \"build_number\":\"${BUILD_NUMBER}\",                 \"crq_number\":\"${ITSM_CR}\"             }"""     resp = httpRequest acceptType: 'APPLICATION_JSON', contentType: 'APPLICATION_JSON',             httpMode: 'POST', quiet: true,             requestBody: body,             url: '' } Important In the def notify(name, status) method, you have to enter a Jitterbit API URL. Create a new API and then add that URL in this method. To create an API, seeCreating a custom API in the official Jitterbit documentation. When you create the API, make sure you use the POST method for the Task Controller operation and the GET method for the CR Status Controller operation, as shown in the following image: To see how to add these methods in the script, refer to the 1.0 Reference Pipeline Script workflow in the template.

Task 3: To update the project variables for the integration template

1.  Next to the Environment name, click the ellipsis ... and select Project Variables.
2. Update the following project variables:

   • Access points and authentication details for BMC Helix ITSM

     Project variable	Action
     BMC Helix ITSM
     ITSM_Username	Enter the administrator username to access BMC Helix ITSM.
     ITSM_Password	Enter the password to access BMC Helix ITSM.
     ITSM_Rest_URL	Enter the URL to the BMC Helix ITSM REST endpoint.

   • Jenkins variables

     Project variable	Action
     Jenkins_Username	Enter the username to access the Jenkins instance.
     Jenkins_Password	Enter the password for the username you provided.
     Jenkins_URL	Enter the URL of the Jenkins instance you are using.

   • BMC Helix ITSM fields

     Project variable	Value
     ITSM_Location_Company	Enter the name of a valid BMC Helix ITSM company for which the change request should be created.

(Optional) Task 4: To set the time for API debug mode

By default, the debug mode is set to 2 hours after you run the integration. Debug logs are updated for the time set for the debug mode. To increase the debug mode for a longer period of time, perform the following steps:

1. In BMC Helix iPaaS, select API Manager > My APIs.
2. Open the API created for the integration.
   The API name is the value defined in the BHIP_API_Name project variable.
3. Select Enable Debug Mode Until: and set it for the required date and time.
4. Save and publish the API.

Workflows included in the integration template

The following workflows are defined as a part of the integration template. Refer to the following details for an overview of the tasks defined in the workflow operations and configurations defined within each workflow.

2.0 Jenkins to ITSM Change

This workflow defines the operations to create change requests and tasks, and update their statuses. The following operations are included in this workflow: