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: 

Use caseJenkins to BMC Helix ITSM (if a change request does not exist)Jenkins to BMC Helix ITSM (if a change request exists)
Create tickets

Creates a change request and a task under it when a Jenkins pipeline has started.

A task in a change request represents a pipeline stage.

Creates a task under an existing change request that is created from the BMC Helix ITSM and Jira integration.

A task in a change request represents a pipeline stage.

Synchronize statuses

Synchronizes the status of a pipeline stage with the corresponding task.

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

Status of a pipeline stageStatus of a taskReason for a task status
IN_PROGRESSWork In ProgressNA
SUCCESSClosedSuccess
FAILEDClosedFailed
ABORTEDClosedCancelled

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:

Before you begin

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

Required versions

  • Jenkins 2.7 or later
  • Pipeline plugin 2.5 or later
  • Blue Ocean plugin 1.0 or later
  • Jenkins plugins:
    • HTTP Request plugin version1.16
    • Pipeline Utility Steps version2.15.1
  • BMC Helix ITSM minimum version required—21.3

Important: Make sure you enable the plugins before proceeding with the integration.

Authentication and permissions

  • Minimum permissions to access Jenkins and perform the following actions:

    • Job—Read, Build, Create, Configure, Cancel

    • Run—Replay, Update

    • View—Configure, Create, Read, Delete 

  • Administrator access to BMC Helix ITSM

Jitterbit Harmony subscription

A valid BMC Helix iPaaS Open link subscription

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 Open link  project file to your system. 
    This file contains
    the BMC Helix iPaaS Cloud 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 Cloud 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 typeInformation
    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.

      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. 

      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, see Creating a custom API Open link 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 variableAction
      BMC Helix ITSM
      ITSM_UsernameEnter the administrator username to access BMC Helix ITSM.
      ITSM_PasswordEnter the password to access BMC Helix ITSM.
      ITSM_Rest_URLEnter the URL to the BMC Helix ITSM REST endpoint.
    • Jenkins variables

      Project variableAction
      Jenkins_UsernameEnter the username to access the Jenkins instance.
      Jenkins_PasswordEnter the password for the username you provided.
      Jenkins_URLEnter the URL of the Jenkins instance you are using.
    • BMC Helix ITSM fields 

      Project variableValue
      ITSM_Location_CompanyEnter 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:

Operation nameActions performed
2.0 Task ControllerDetermines if a task should be created or updated
2.1 CR Status ControllerChecks the payload and verifies if a change request exists. If not, creates a new change request.
2.2 Query Change Request DetailsGets the details of the change request
2.3 Create TaskCreates a task under a change request
2.4 Query TaskGets the task details
2.5 Update Task StatusUpdates the status of a task when the status of the corresponding stage is changed
2.6 Create a New CRCreates a new change request

2.7 Query From TSM Association

Makes sure that tasks under a change request execute in a sequence

2.8 Active the Task (TMS Flow Builder)Activates a task in a sequence
2.9 Query Task phase managementEnsures that tasks are executed in a sequence
2.10 Get Pipeline StagesGets the details of a pipeline stage

Was this page helpful? Yes No Submitting... Thank you

Comments