From a781c7c02723d9dc09134e08ebfcabae17827263 Mon Sep 17 00:00:00 2001 From: vlussenburg Date: Tue, 12 May 2026 10:05:41 -0700 Subject: [PATCH 1/2] docs(servicenow): point OAuth link at current canonical URL The 'sandiego-platform-security' bundle URL is the San Diego release-named location; the canonical doc has moved to the unversioned www.servicenow.com/docs/r/platform-security/authentication/ path. The old URL still works via 301 redirect but the new one is the direct canonical. --- src/pages/docs/approvals/servicenow/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/approvals/servicenow/index.md b/src/pages/docs/approvals/servicenow/index.md index 4138f498e5..81a2d545f9 100644 --- a/src/pages/docs/approvals/servicenow/index.md +++ b/src/pages/docs/approvals/servicenow/index.md @@ -62,7 +62,7 @@ The instructions in this section will require a ServiceNow Administrator. The Octopus Deploy / ServiceNow integration requires security configuration in your target ServiceNow instance. -Follow the [ServiceNow OAuth documentation](https://docs.servicenow.com/bundle/sandiego-platform-security/page/administer/security/task/t_SettingUpOAuth.html) to configure an OAuth endpoint for Octopus to use for authentication. Take note of the OAuth client id and client secret from the configuration. +Follow the [ServiceNow OAuth documentation](https://www.servicenow.com/docs/r/platform-security/authentication/t_SettingUpOAuth.html) 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: From 8e4f3ddde6f69a2826e94ffaf3884d0ad5bb1402 Mon Sep 17 00:00:00 2001 From: Sam Wilde Date: Mon, 18 May 2026 09:52:02 +0100 Subject: [PATCH 2/2] Fix Markdown lint errors --- src/pages/docs/approvals/servicenow/index.md | 63 ++++++++++---------- 1 file changed, 30 insertions(+), 33 deletions(-) diff --git a/src/pages/docs/approvals/servicenow/index.md b/src/pages/docs/approvals/servicenow/index.md index 81a2d545f9..d449d50dc0 100644 --- a/src/pages/docs/approvals/servicenow/index.md +++ b/src/pages/docs/approvals/servicenow/index.md @@ -21,25 +21,26 @@ 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 | +| -- | -- | -- | +| 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 | +| 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 @@ -166,14 +167,12 @@ 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 **2024.2** you can create an `Emergency` change by selecting the Emergency Change setting on the deployment or runbook run creation page. + :::figure ![ServiceNow Integration Project settings](/docs/img/approvals/servicenow/images/servicenow-emergency-change.png) ::: @@ -253,15 +252,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. @@ -299,10 +297,10 @@ 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.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.Id` | | | `Octopus.ServiceNow.Connection.Name` | | | `Octopus.ServiceNow.Connection.BaseUrl` | | | `Octopus.ServiceNow.Connection.OAuthClientId` | | @@ -318,22 +316,21 @@ The following variables are only available in version 2025.4 and later ## Troubleshooting -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". +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