CloudBees ServiceNow Integration

The CloudBees ServiceNow Integration provides the ability to create and manage ServiceNow change requests and incident tickets from your pipeline. CloudBees ServiceNow Integration consists of two components:

  • CloudBees ServiceNow App and

  • CloudBees ServiceNow Jenkins Plugin.

The following sections describe the installation, setup and usage.

Use Cases

  • Change Requests: With your Pipeline, automatically create and update change requests in ServiceNow to track updates to your build, test and production environments. If you have issues with these environments, know what changes occurred.

  • Incident Tickets: On Pipeline failures (build, test, etc.) automatically create and assign tickets in ServiceNow to get triage and resolution done quickly.

Overview

CloudBees ServiceNow App

The CloudBees ServiceNow App provides the ServiceNow web service that allows your Jenkins projects to create and update change requests and incident tickets. This app includes the import set tables, transform maps and security roles that allow this integration with Jenkins.

Installation and Setup

To install the CloudBees ServiceNow App:

  1. The CloudBees ServiceNow App can be installed from the ServiceNow store at https://store.servicenow.com.

  2. Log in with your HI credentials and then search for CloudBees.

  3. Choose the CloudBees tile and get the app.

  4. Choose to install on all of your ServiceNow instances or specific instances.

  5. Go to your ServiceNow instance(s).

  6. Log in with your admin account.

  7. Go to System Applications > Applications.

  8. In the Downloads tab choose the CloudBees ServiceNow app and click Install.

Add the Web Services User

The integration with Jenkins requires a web services user. Follow these steps to create this user.

  1. As admin, go to System Security > Users.

  2. Click New to create a new user.

  3. Complete the fields to add a user.

  4. Add the role x_clbe_cloudbees_s.web_service to this new user. This is the user that will be used to authenticate for the CloudBees ServiceNow Jenkins Plugin. Use this user as your credentials in your Jenkins Pipeline.

Security Roles

The following security roles are provided with the CloudBees ServiceNow App.

Role Description

x_clbe_cloudbees_s.web_service

This role is required to use the web services in order to create and update incident tickets, change requests, and events. This role is required in order to use the Jenkins plugin.

x_clbe_cloudbees_s.admin

This role allows access to the import set tables (see below).

x_clbe_cloudbees_s.user

This role allows the user to view the CloudBees ServiceNow application menu items.

Web Services

The following web services are setup with the CloudBees ServiceNow App.

Web Service Description

/api/now/import/x_clbe_cloudbees_s_change_request_cb

This is the endpoint to create and update change requests.

/api/now/import/x_clbe_cloudbees_s_incident_cb

This is the endpoint to create and update incident tickets.

Import Set Tables

The web services are backed by the following import set tables.

Import Set Table Description

change_request_cb

Stores change requests.

incident_cb

Stores incident tickets.

CloudBees ServiceNow Jenkins Plugin

The CloudBees ServiceNow Jenkins Plugin is a pipeline plugin that provides objects and functions for creating and update change requests and incident tickets in your ServiceNow instance. The plugin package can be acquired through your customer success manager. After acquiring the package, follow the next steps to install it.

Installation and Setup

  1. Log into your Managed Master or Team Master as administrator.

  2. Open Manage Jenkins  Manage Plugins.

  3. Go to the Advanced tab.

  4. Go to the Upload Plugin section.

  5. Upload the hpi package.

  6. Follow the instructions to restart the Managed Master/Team Master.

  7. Go to Manage Jenkins  Configure System.

  8. Scroll down to the ServiceNow section.

  9. Specify the ServiceNow URL.

  10. Specify the username and password for the user created above with role x_clbe_cloudbees_s.web_service.

  11. Click Validate to validate the settings.

Endpoint

Usage

Create and Update Change Requests

Two functions are provided to create and manage change requests: createChangeRequest and updateChangeRequest.

String createChangeRequest(ChangeRequest)

Returns a correlation ID if successful. The correlation ID is used to identify a change request to update.

def requestId = createChangeRequest changeRequest: request
Boolean updateChangeRequest(corrId, ChangeRequest)

Returns true if successful. Requires correlationId. The correlation ID is used to identify a change request to update.

def requestRes = updateChangeRequest correlationId: requestId,changeRequest: updatedRequest
ChangeRequest

The following ChangeRequest fields correspond to ServiceNow change request fields.

assignedTo

assignmentGroup

category

ci

closedBy

description

impact

priority

requestedBy

risk

shortDescription

state

type

workStartDate

workEndDate

Additional non-standard/custom fields may be specified using the additionalFields attribute. The value for this attribute is a map of fields and their values.

def request = ChangeRequest  shortDescription:'Deploy to Test', additionalFields:['my_field':'this is a test','backout_plan':'Roll back to last version']
Scripted Pipeline Examples
def request = ChangeRequest shortDescription:'Deploy to Test',type:'Standard',category:'Other',impact:'3 - Low',risk:'Moderate',priority:'4 - Low',ci:'AS400'
createChangeRequest changeRequest: request
def start = new Date()

sleep 30

def end = new Date()

def request = ChangeRequest shortDescription:'Deploy to Production',type:'Standard',category:'Other',impact:'3 - Low',risk:'Moderate',priority:'4 - Low',ci:'AS400',workStartDate:start,workEndDate:end
createChangeRequest changeRequest: request
Build Status

Change requests that are created will be listed on the build status page. You can click on the link to go directly to the change request in ServiceNow.

Build Status
Change Request in ServiceNow

In ServiceNow, the change request will have log output and linkbacks to the project and build.

ServiceNow Change

Create and Update Incident Tickets

Two functions are provided to create and manage incident tickets: createIncidentTicket and updateIncidentTicket.

String createIncidentTicket(IncidentTicket)

Returns a correlation ID if successful. The correlation ID is used to identify an incident ticket to update.

def corrId = createIncidentTicket incidentTicket: ticket
Boolean updateIncidentTicket(corrId,IncidentTicket)

Returns true if successful. Requires correlationId. The correlation ID is used to identify an incident ticket to update.

def ticketRes = updateIncidentTicket correlationId: ticketId,incidentTicket: updatedTicket
IncidentTicket

The following IncidentTicket fields correspond to ServiceNow incident ticket fields.

assignedTo

assignmentGroup

callerId

category

ci

description

impact

severity

shortDescription

state

urgency

Additional non-standard/custom fields may be specified using the additionalFields attribute. The value for this attribute is a map of fields and their values.

def ticket = IncidentTicket  shortDescription:'Production Issue', additionalFields:['my_field':'this is a test','my_severity':'Urgent']
Scripted Pipeline Example
def ticket = IncidentTicket shortDescription:'Job failed!',callerId:'Beth Anglin',impact:'3 - Low',urgency:'3 - Low'

def requestId = createIncidentTicket incidentTicket: ticket
Build Status

Incident tickets that are created will be listed on the build status page. You can click on the link to go directly to the incident ticket in ServiceNow.

Build Status
Incident Ticket in ServiceNow

In ServiceNow, the incident ticket will have log output and linkbacks to the project and build.

ServiceNow Incident

Troubleshooting

If you are experiencing issues with CloudBees ServiceNow integration, follow these procedures to help you troubleshoot these issues.

Ensure the CloudBees ServiceNow App is installed

To validate that the CloudBees ServiceNow App is installed, type CloudBees in the main menu filter navigator. The CloudBees main menu item and submenu items should appear (if the app has been installed).

Ensure the ServiceNow user has been created with the correct roles

Verify that a user has been created under System Security > Users with the role x_clbe_cloudbees_s.web_service on your ServiceNow instance. If not, follow the steps in Add the Web Services User above.

Ensure that the ServiceNow credentials have been added to Jenkins

Access Manage Jenkins > Configure System on your to verify that the ServiceNow credentials have been added. Click Validate to ensure the credentials are correct.

View the Jenkins log for more details

Look at the Jenkins log, will include debug for this plugin. This includes all ServiceNow POST requests.

.
.
.
com.cloudbees.plugins.servicenow.ServiceNowRestService posted '{"additionalFields":null,"correlation_id":"089f1f71-3c53-44c0-8b57-229b398f33ad","short_description":"Test ticket from CloudBees. Disregard.","state":"New"}' to https://ven02428.service-now.com/api/now/import/x_clbe_cloudbees_s_incident_cb with response 201 '{"import_set":"ISET0010035","staging_table":"x_clbe_cloudbees_s_incident_cb","result":[{"transform_map":"incident_cb","table":"incident","display_name":"number","display_value":"INC0010067","record_link":"https://ven02428.service-now.com/api/now/table/incident/01e32df9dbd95300ffbfec51ca9619cb","status":"inserted","sys_id":"01e32df9dbd95300ffbfec51ca9619cb"}]}'
.
.
.
com.cloudbees.plugins.servicenow.ServiceNowRestService posted '{"additionalFields":null,"correlation_id":"ebd8b4b7-70ad-46df-8ddd-81134f04746d","short_description":"Deploy to Production","work_notes":"[code]<p><a title=\"Jenkins Job\" href=\"http://busdev-controller-2025238388.us-west-2.elb.amazonaws.com.elb.cloudbees.net/bus-dev-master/job/Deploy%20to%20environments%20(change%20request)/\">Go to Jenkins project</a></p>[/code][code]<p><a title=\"Build\" href=\"http://busdev-controller-2025238388.us-west-2.elb.amazonaws.com.elb.cloudbees.net/bus-dev-master/job/Deploy%20to%20environments%20(change%20request)/37/\">Go to Jenkins build report</a></p>[/code][code]<p>Started by user admin</p>[/code][code]<p>Running in Durability level: MAX_SURVIVABILITY</p>[/code][code]<p>Agent 218b400a is provisioned from template Operations Center Shared Templates » maven-jdk-8</p>[/code][code]<p>Agent specification[maven-jdk-8] : cpus=0.1, mem=2048, jvmMem=512, dockerImage=maven:3.5-jdk-8, containerProperties=[--volumes-from certs, -e no_proxy localhost,127.0.0.1,169.254.169.254], constraints=</p>[/code][code]<p>Running on 218b400a in /jenkins/workspace/Deploy to environments (change request)</p>[/code][code]<p>Timeout set to expire in 1 hr 0 min</p>[/code][code]<p>Build</p>[/code][code]<p>Deploy to Test</p>[/code][code]<p>com.cloudbees.plugins.servicenow.ServiceNowRestService posted '{\"additionalFields\":null,\"correlation_id\":\"43034f83-e408-4691-99a1-61fdef529a92\",\"short_description\":\"Deploy to Test\",\"work_notes\":\"[code]<p><a title=\\\"Jenkins Job\\\" href=\\\"http://busdev-controller-2025238388.us-west-2.elb.amazonaws.com.elb.cloudbees.net/bus-dev-master/job/Deploy%20to%20environments%20(change%20request)/\\\">Go to Jenkins project</a></p>[/code][code]<p><a title=\\\"Build\\\" href=\\\"http://busdev-controller-2025238388.us-west-2.elb.amazonaws.com.elb.cloudbees.net/bus-dev-master/job/Deploy%20to%20environments%20(change%20request)/37/\\\">Go to Jenkins build report</a></p>[/code][code]<p>Started by user admin</p>[/code][code]<p>Running in Durability level: MAX_SURVIVABILITY</p>[/code][code]<p>Agent 218b400a is provisioned from template Operations Center Shared Templates » maven-jdk-8</p>[/code][code]<p>Agent specification[maven-jdk-8] : cpus=0.1, mem=2048, jvmMem=512, dockerImage=maven:3.5-jdk-8, containerProperties=[--volumes-from certs, -e no_proxy localhost,127.0.0.1,169.254.169.254], constraints=</p>[/code][code]<p>Running on 218b400a in /jenkins/workspace/Deploy to environments (change request)</p>[/code][code]<p>Timeout set to expire in 1 hr 0 min</p>[/code][code]<p>Build</p>[/code][code]<p>Deploy to Test</p>[/code]\",\"type\":\"Standard\",\"category\":\"Other\",\"state\":\"New\",\"impact\":\"3 - Low\",\"priority\":\"4 - Low\",\"risk\":\"Moderate\",\"cmdb_ci\":\"AS400\",\"work_start\":\"2018-04-06 03:18:23\",\"work_end\":\"2018-04-06 03:18:23\"}' to https://ven02428.service-now.com/api/now/import/x_clbe_cloudbees_s_change_request_cb with response 201 '{\"import_set\":\"ISET0010034\",\"staging_table\":\"x_clbe_cloudbees_s_change_request_cb\",\"result\":[{\"transform_map\":\"change_request_cb\",\"table\":\"change_request\",\"display_name\":\"number\",\"display_value\":\"CHG0030083\",\"record_link\":\"https://ven02428.service-now.com/api/now/table/change_request/53a5cea5db155300ffbfec51ca961980\",\"status\":\"inserted\",\"sys_id\":\"53a5cea5db155300ffbfec51ca961980\"}]}'</p>[/code][code]<p>Smoke Test</p>[/code][code]<p>Integration Test</p>[/code][code]<p>Deploy to Production</p>[/code][code]<p>Sleeping for 30 sec</p>[/code]","type":"Standard","category":"Other","state":"New","impact":"3 - Low","priority":"4 - Low","risk":"Moderate","cmdb_ci":"AS400","work_start":"2018-04-06 03:18:25","work_end":"2018-04-06 03:18:55"}' to https://ven02428.service-now.com/api/now/import/x_clbe_cloudbees_s_change_request_cb with response 201 '{"import_set":"ISET0010034","staging_table":"x_clbe_cloudbees_s_change_request_cb","result":[{"transform_map":"change_request_cb","table":"change_request","display_name":"number","display_value":"CHG0030084","record_link":"https://ven02428.service-now.com/api/now/table/change_request/b6c50ae5db155300ffbfec51ca96196b","status":"inserted","sys_id":"b6c50ae5db155300ffbfec51ca96196b"}]}'
.
.
.
Copyright © 2010-2020 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees Flow, CloudBees Flow Deploy, CloudBees Flow DevOps Insight, CloudBees Flow DevOps Foresight, CloudBees Flow Release, CloudBees Accelerator, CloudBees Accelerator ElectricInsight, CloudBees Accelerator Electric Make, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center, and DEV@cloud are trademarks of CloudBees, Inc. Most CloudBees products are commonly referred to by their short names — Accelerator, Automation Platform, Flow, Deploy, Foresight, Release, Insight, and eMake — throughout various types of CloudBees product-specific documentation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at www.cloudbees.com/jenkins/about. Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.