Skip to content

Update ServiceNow docs #3195

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wlthomson wants to merge 5 commits into
base: main
Choose a base branch
from
+46 −48
Open

Update ServiceNow docs #3195

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ccfe875
Update ServiceNow docs
wlthomson Jun 3, 2026
36eeb4f
Improve wording and punctuation
wlthomson Jun 3, 2026
667a070
Make markdownlint happy
wlthomson Jun 3, 2026
40071b3
Make markdownlint happy again
wlthomson Jun 3, 2026
7a5a9db
Merge branch 'main' into wlthomson/update-snow-docs
wlthomson Jun 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/pages/docs/approvals/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,8 @@ What's included in our ServiceNow support?
- Automatically create normal and emergency change requests at execution time. Octopus pauses the execution until the appropriate approvals are complete.
- Let Octopus do the work for you by automating the transition between stages in the change request once created, leaving a deployment or runbook run record in ServiceNow.
- Use change templates to auto-create standard change requests to reduce manual work and control what information is populated.
- Ensure "Change Windows" are honored on existing change requests so deployments or runbook runs won't execute until the specified time window.
- Add work notes to change requests with information about deployment or runbook run start and finish time and whether it was successful or not.
- Ensure “Change Windows” are honored on existing change requests so deployments or runbook runs won't execute until the specified time window.
- Add work notes to change requests, capturing execution details for deployments and runbook runs, including tenant name and tags for tenanted deployments.
- Create change requests with pre-populated fields through variables.
- View and export audit logs of controlled deployments and runbook runs for easy compliance and post-execution reconciliation.

Expand Down
2 changes: 1 addition & 1 deletion src/pages/docs/approvals/jira-service-management/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ The instructions in this section will require an Octopus Deploy Manager or Admin
:::

If enabled, this feature will result in a linked change request having one or more Comments added
during the deployment lifecycle which record details about the deployment and its execution status.
during the deployment lifecycle, which record details about the deployment and its execution status. Comments include the project name, environment, and version. From **2026.2**, the tenant name and tags are also included for tenanted deployments.

To enable this feature navigate to **Configuration ➜ Settings ➜ Jira Service Management
Integration**, click the **Customer Comments Enabled** checkbox show below then click **Save**.
Expand Down
88 changes: 43 additions & 45 deletions src/pages/docs/approvals/servicenow/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,26 +20,27 @@ To enable this behavior, both the Octopus Project and Environment you are deploy

### Deployments

| Project | Environment | Outcome |
|--|--|--|
| Change controlled| Change controlled| Approval required for deployment |
| **_Not_** Change controlled| Change controlled| No approval required |
| Change controlled| **_Not_** Change controlled| No approval required |
| Project | Environment | Outcome |
|---------------------------|---------------------------|----------------------------------|
| Change controlled | Change controlled | Approval required for deployment |
| **Not** Change controlled | Change controlled | No approval required |
| Change controlled | **Not** Change controlled | No approval required |

### Runbooks

| Project | Environment | Runbook | Outcome |
|--|--|--|--|
| Change controlled | Change controlled | Enabled | Approval required |
| Change controlled | Change controlled | **_Not_** Enabled | No approval required |
| **_Not_** Change controlled | Change controlled | Enabled | No approval required |
| Change controlled | **_Not_** Change controlled | Enabled | No approval required |
| Project | Environment | Runbook | Outcome |
|---------------------------|---------------------------|-----------------------|--------------------------|
| Change controlled | Change controlled | Enabled | Approval required |
| Change controlled | Change controlled | **Not** Enabled | No approval required |
| **Not** Change controlled | Change controlled | Enabled | No approval required |
| Change controlled | **Not** Change controlled | Enabled | No approval required |

## Getting started

The ServiceNow integration requires Octopus **2022.3** or later and an Octopus enterprise subscription.

Your ServiceNow instance must have the following modules installed and activated:

- Change Management
- Change Management Standard Change Catalog
- Change Management State Model
Expand Down Expand Up @@ -121,7 +122,7 @@ This feature is only available for version 2022.3.1274 and later
The instructions in this section will require an Octopus Deploy Manager or Administrator
:::

If enabled, this feature will result in a linked change request having one or more Work Notes added during the deployment lifecycle which record details about the deployment and its execution status.
If enabled, this feature will result in a linked change request having one or more Work Notes added during the deployment lifecycle which record details about the deployment and its execution status. Work notes include the project name, environment, and version. From **2026.2**, the tenant name and tags are also included for tenanted deployments.

To enable this feature navigate to **Configuration ➜ Settings ➜ ServiceNow Integration**, click the **Work Notes Enabled** checkbox show below then click **Save**.

Expand Down Expand Up @@ -166,12 +167,11 @@ To enable a runbook to enforce a requirement for an approved CR:

### Standard, Normal, and Emergency Changes

By default, deployments and runbooks runs resulting in CR creation will produce a `Normal` change (i.e. one
requiring explicit approval).
By default, deployments and runbooks runs resulting in CR creation will produce a `Normal` change (i.e. one requiring explicit approval).

Setting the **Standard Change Template Name** setting under **ITSM Providers** to the name of an active, approved **Standard Change Template** (as found in the Standard Change Catalog) will instead result in deployments and runbook runs of the project creating a `Standard` (i.e. low-risk, pre-approved) change.

Setting the **Standard Change Template Name** setting under **ITSM Providers** to the name of an
active, approved **Standard Change Template** (as found in the Standard Change Catalog) will instead
result in deployments and runbook runs of the project creating a `Standard` (i.e. low-risk, pre-approved) change.
From **2026.2**, **Standard Change Template Name** supports Octopus variable expressions (e.g. `#{ServiceNow.StandardTemplate}`), allowing the template to vary dynamically by environment or tenant. If the expression resolves to an empty value, a Normal change request will be created.

From **2024.2** you can create an `Emergency` change by selecting the Emergency Change setting on the deployment or runbook run creation page.
:::figure
Expand Down Expand Up @@ -253,15 +253,14 @@ The title must match the format **exactly**, including the double-quotes.
This feature is only available for version 2024.2.6455 and later
:::


To control the content of the CRs the variable `Octopus.ServiceNow.Field[snow_field]` can be set at the project level. These are contributed to the create CR body as a dictionary allowing any field to be set.

For example to set the `Assigned To` or `Short Description` fields you can use the following:

| Field | Variable | Example Value|
|--|--|--|
|Assigned To|Octopus.ServiceNow.Field[assigned_to]|beth.anglin|
|Short Description|Octopus.ServiceNow.Field[short_description]|Custom Short Description with #{SomeVariable} #{Octopus.Deployment.Id}|
| Field | Variable | Example Value |
|-------------------|--------------------------------------------------|-----------------------------------------------------------------------|
| Assigned To | Octopus.ServiceNow.Field[assigned_to] | beth.anglin |
| Short Description | Octopus.ServiceNow.Field[short_description] | Custom Short Description with #{SomeVariable} #{Octopus.Deployment.Id}|

:::div{.hint}
Setting a `Short Description` will over-ride the auto generated Octopus description. [Title text matching](#title-text-matching) means this will automatically progress the deployment unless the resolved description is unique. This can be done by including variables like the deployment or environment Id.
Expand Down Expand Up @@ -298,42 +297,41 @@ The following list assumes the linked change is in an **approved** state.
The following variables are only available in version 2025.4 and later
:::

| Variable | Notes |
|--|--|
| `Octopus.ServiceNow.ChangeRequest.Number` | The number of the matched or created change request |
| `Octopus.ServiceNow.ChangeRequest.SysId` | The system identifier of the matched or created change request |
| `Octopus.ServiceNow.Connection.Id` | |
| `Octopus.ServiceNow.Connection.Name` | |
| `Octopus.ServiceNow.Connection.BaseUrl` | |
| `Octopus.ServiceNow.Connection.OAuthClientId` | |
| `Octopus.ServiceNow.Connection.OAuthClientSecret` | |
| `Octopus.ServiceNow.Connection.Username` | |
| `Octopus.ServiceNow.Connection.Password` | |
| Variable | Notes |
|---------------------------------------------------|------------------------------------------------------------------------|
| `Octopus.ServiceNow.ChangeRequest.Number` | The number of the matched or created change request |
| `Octopus.ServiceNow.ChangeRequest.SysId` | The system identifier of the matched or created change request |
| `Octopus.ServiceNow.Connection.Id` | |
| `Octopus.ServiceNow.Connection.Name` | |
| `Octopus.ServiceNow.Connection.BaseUrl` | |
| `Octopus.ServiceNow.Connection.OAuthClientId` | |
| `Octopus.ServiceNow.Connection.OAuthClientSecret` | |
| `Octopus.ServiceNow.Connection.Username` | |
| `Octopus.ServiceNow.Connection.Password` | |

## Known Issues and limitations

- 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](/docs/releases/lifecycles) attached to the project or channel.

## Troubleshooting

Errors occurring during a deployment approval checks will appear in the "Task Failed" icon's
Errors occurring during a deployment approval checks will appear in the "Task Failed" icon's
tooltip. From **2024.2** on errors related to creating a change request are available through the task log. Additional information will also be available in the "System Diagnostic Report".

If you are seeing errors in Octopus during deployments, ensure that the ServiceNow user account is authorized to call the required endpoints.
If you are seeing errors in Octopus during deployments, ensure that the ServiceNow user account is authorized to call the required endpoints.

The ServiceNow integration uses the following REST endpoints:

| Purpose | HTTP Method | Path | Notes |
|--------------------------------------|-------------|-------------------------------------------------|-------|
| Authorize | `POST` | `/oauth_token.do` | |
| Search for changes | `GET` | `/api/sn_chg_rest/change` | |
| Create change | `POST` | `/api/sn_chg_rest/change/normal` | |
| Search for Standard Change templates | `GET` | `/api/sn_chg_rest/change/standard/template` | Requires project **Change Template Name** configuration |
| Create Standard Change from template | `POST` | `/api/sn_chg_rest/change/standard/{templateId}` | Requires project **Change Template Name** configuration |
|Approve Standard Change | `PATCH` | `/api/sn_chg_rest/change/{changeId}` | Requires project **Automatic Transition** configuration |
|Add work notes | `PATCH` | `/api/sn_chg_rest/change/{changeId}` | Requires **Work Notes Enabled** **ServiceNow** global configuration |
| Purpose | HTTP Method | Path | Notes |
|--------------------------------------|-------------|-------------------------------------------------|-----------------------------------------------------------------------|
| Authorize | `POST` | `/oauth_token.do` | |
| Search for changes | `GET` | `/api/sn_chg_rest/change` | |
| Create change | `POST` | `/api/sn_chg_rest/change/normal` | |
| Search for Standard Change templates | `GET` | `/api/sn_chg_rest/change/standard/template` | Requires project **Change Template Name** configuration |
| Create Standard Change from template | `POST` | `/api/sn_chg_rest/change/standard/{templateId}` | Requires project **Change Template Name** configuration |
| Approve Standard Change | `PATCH` | `/api/sn_chg_rest/change/{changeId}` | Requires project **Automatic Transition** configuration |
| Add work notes | `PATCH` | `/api/sn_chg_rest/change/{changeId}` | Requires **Work Notes Enabled** **ServiceNow** global configuration |

## Older versions

Expand Down