Service Now Integration

Overview

The Octopus Deploy/ServiceNow integration allows users to block the execution of specifically configured deployments unless they have a corresponding approved ServiceNow Change Request (CR).

To enable this behavior, both the Octopus Project and Environment you are deploying to must be configured and the ServiceNow configuration is set up before deployments can be managed.

Getting started

The Service Now integration requires Octopus 2022.2.5556 or later and an Octopus license with the Service Now Integration feature enabled.

Before you can use the Octopus Deploy/ServiceNow integration, you'll need to:

1. Configure ServiceNow OAuth credentials (for use by Octopus).
2. Request and install a new Octopus license required to enable the ServiceNow feature.
3. Configure a connection from Octopus to ServiceNow.
4. Configure which deployments require an approved CR.

Configuring Service Now

The Octopus Deploy / ServiceNow integration requires security configuration in your target ServiceNow instance.

Follow the ServiceNow OAuth documentation to configure an OAuth endpoint for Octopus to use for authentication. Take note of the OAuth client id and client secret from the configuration.

Next, the integration will require a user account in ServiceNow. The recommendation is to create a service account specifically for Octopus, once created the user must be assigned the following two roles:

• sn_change_read
• sn_change_write

Ensure that the new user has the Web service access only checkbox checked.

Take note of the password assigned or generated for this user.

Licensing

For the ServiceNow approval checks to be performed as part of the deployment process, an appropriate Octopus license must be configured in your Octopus instance.

A ServiceNow enabled Octopus license must be requested from Octopus directly, and cannot be managed through the self-service process. To request a license register for the ServiceNow Early Access Program

Once you have received your feature-enabled license, you can install it by navigating to Configuration ➜ License.

An enabled license will include a block similar to below:

<Features>
  <ServiceNowIntegration>
    <ValidTo>...</ValidTo>
  </ServiceNowIntegration>
</Features>

Configuring ServiceNow connections

To connect your Octopus Deploy instance to ServiceNow, navigate to Configuration ➜ Settings ➜ ServiceNow Integration.

Check the Enabled option

Click on ADD CONNECTION and fill out the details. The ServiceNow Base Url should be the root URL and include the protocol e.g. https://

Press TEST to ensure that the connection details are working.

Multiple ServiceNow connections are supported, however, each project can only use one ServiceNow connection.

Configuring deployments

To enforce a deployment to require an approved CR, the Change Controlled setting needs to be enabled in both the project and the environment it is being deployed to.

Setting up projects for CR approval

To enable a project to enforce a requirement for an approved CR:

1. Navigate to the project and then Settings ➜ General.
2. Check the Change-controlled setting.
3. Select your ServiceNow connection in the Service Now Connection setting and click SAVE.

Standard Change Templates

By default, the deployments resulting in a CR creation will produce a Normal change. Setting the Change Template Name setting under Project Settings to the name of a valid, approved Change Template will instead create a Standard change based upon the change template.

Supplying the CR number to a deployment

If you add a variable to your project named Octopus.ServiceNow.Change.Number, then a CR will not be created, and instead, the supplied CR number will be used during the approval check. This variable can also be scoped or configured as a Prompted variable.

Setting up environments for CR approval

To enable an environment to enforce a requirement for an approved CR, navigate to Infrastructure ➜ Environments, edit the environment via the overflow menu and check the Change Controlled setting, and then press SAVE.

How it works

Deployments where both the project and environment have Change Controlled enabled, will query ServiceNow for an approved CR before execution can begin.

When a Change Controlled deployment is evaluated for approval, the following checks are performed:

• If a specific CR number is available, via a variable named Octopus.ServiceNow.Change.Number, then only this CR will be checked.
• If there is an existing CR with the specifically formatted Short Description available. See Title text matching for more information, then this CR will be evaluated.
• Create a new CR.
  • This will be a Normal change, or a Standard change if the project has a Change Template Name set.
  • A CR created by Octopus will have a Short Description in the format outlined in Title text matching.

When re-deploying a previous deployment, the same CR will be used if it is still open. If it is closed the above process will be followed again.

Once a CR has been found, the deployment will only proceed if the State of the CR is Implement. If the State is either New, Assess, Authorize, or Scheduled the deployment will wait. Any other State will cause the deployment task to fail.

If the deployment is scheduled to execute in the future, then a CR will be created at the scheduled deployment time, and not when the deployment was requested.

The number of the CR created or found will appear in the Task Summary tab of the executing Octopus deployment task. Clicking on the CR number in the message will navigate you to the CR in ServiceNow.

Title text matching

Octopus supports matching a CR by setting the Short Description of the CR to a well-known format:

Octopus: Deploy "{project name}" version {release version number} to "{environment name}"

e.g Octopus: Deploy "Web Site" version 1.0.1-hotfix-001 to "Dev"

Known Issues and limitations

• Pressing TEST on a ServiceNow connection that has not been saved will error. The workaround is to press SAVE and then open the connection flyout again and press TEST.

• The approval status of a deployment is not evaluated until the deployment scheduled start time has been reached.

• The Planned start date and Planned end date supplied on a CR will not be considered.

• Once a CR is deemed to be related to a deployment, then only this CR will be evaluated for the deployment to proceed. If the CR is incorrect, you will need to cancel the deployment, close the CR and try the deployment again.

• Each project only supports a single ServiceNow connection.

• Each project only supports supplying the same Change Template Name across all environments in the Lifecycle attached to the project or channel.

Need support? We're here to help.