ServiceNow

v8.1 Enterprise

The ServiceNow integration automatically tracks the state of your Unleash change requests in ServiceNow. For each change request in Unleash, the integration creates a change request of type standard in ServiceNow and updates its stage as the Unleash change request progresses. Standard changes are pre-approved, template-based changes, distinct from ServiceNow’s normal changes.

The ServiceNow change request serves as an audit trail. Change requests are created, approved, and applied in Unleash. Approvals or rejections in ServiceNow do not affect Unleash, and you cannot create a change request in ServiceNow and link it to Unleash.

When the integration syncs a change request, a system user posts a comment on the Unleash change request with a link to the corresponding change request in ServiceNow. If the integration fails to create the change request in ServiceNow, a system user posts a comment describing the failure.

The integration tracks change requests created after you enable it. If you disable and re-enable the integration, change requests that changed state in the meantime are not updated in ServiceNow.

Change request lifecycle

The Unleash change request lifecycle maps to ServiceNow change request stages as follows:

Unleash stage	ServiceNow stage
Draft	None, nothing is created yet
In review	`New`, the ServiceNow change is created
Approved	`Implement`
Scheduled	`Implement`, no change in ServiceNow
Applied	`Closed`, with the close code set to `Successful`
Cancelled	`Canceled`
Rejected	`Canceled`

If new changes are added to an Unleash change request that was already approved, the corresponding ServiceNow change is cancelled and a new one is created. A system user posts a comment on the Unleash change request with a link to the new change request in ServiceNow.

Prerequisites

To set up the integration, you need:

A ServiceNow instance that is reachable from Unleash.
A ServiceNow REST API key that uses the authentication profile Header for API key (x-sn-apikey) and an access policy for Change management with the REST API path sn_chg_rest/change. Leave the methods set to apply to all.
A standard change request template in your ServiceNow instance to use for the integration. We suggest creating a new template and naming it something recognizable, like Unleash Change Request.

Configuration

To create the integration in Unleash:

In the Admin UI, go to Integrations.
Select ServiceNow.
Configure the parameters, events, and optional project and environment filters.
Click Create.

Parameters

The ServiceNow integration takes the following parameters:

ServiceNow instance URL

stringRequired

The base URL of your ServiceNow instance, for example https://example.service-now.com.

API key

stringRequired

The ServiceNow REST API key, sent as the x-sn-apikey header. The key requires an API access policy permitting key authentication on the Change Management API.

Standard change template

stringRequired

The sys_id of a standard change template in your ServiceNow instance.

Events

The integration can subscribe to the following events:

change-request-applied
change-request-approved
change-request-cancelled
change-request-rejected
change-request-sent-to-review

Select all available events when configuring the integration. If you select only a subset, the integration does not work as expected.

Projects and environments

You can filter which projects and environments the integration is enabled for. If you don’t select any projects or environments, the integration receives events from all of them.