From ccfe8756db2d94ad1355a451bed44c72c5319599 Mon Sep 17 00:00:00 2001 From: wlthomson Date: Wed, 3 Jun 2026 15:33:58 +1200 Subject: [PATCH 1/4] Update ServiceNow docs --- src/pages/docs/approvals/index.md | 4 ++-- src/pages/docs/approvals/jira-service-management/index.md | 2 +- src/pages/docs/approvals/servicenow/index.md | 5 +++-- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/src/pages/docs/approvals/index.md b/src/pages/docs/approvals/index.md index 28d97935d8..c0bd61ae07 100644 --- a/src/pages/docs/approvals/index.md +++ b/src/pages/docs/approvals/index.md @@ -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. diff --git a/src/pages/docs/approvals/jira-service-management/index.md b/src/pages/docs/approvals/jira-service-management/index.md index 3772d9612a..ccb96cebe8 100644 --- a/src/pages/docs/approvals/jira-service-management/index.md +++ b/src/pages/docs/approvals/jira-service-management/index.md @@ -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**, for tenanted deployments, the tenant name and tags are also included. To enable this feature navigate to **Configuration ➜ Settings ➜ Jira Service Management Integration**, click the **Customer Comments Enabled** checkbox show below then click **Save**. diff --git a/src/pages/docs/approvals/servicenow/index.md b/src/pages/docs/approvals/servicenow/index.md index 4138f498e5..7c80a11c9c 100644 --- a/src/pages/docs/approvals/servicenow/index.md +++ b/src/pages/docs/approvals/servicenow/index.md @@ -121,7 +121,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**, for tenanted deployments, the tenant name and tags are also included. To enable this feature navigate to **Configuration ➜ Settings ➜ ServiceNow Integration**, click the **Work Notes Enabled** checkbox show below then click **Save**. @@ -173,6 +173,8 @@ Setting the **Standard Change Template Name** setting under **ITSM Providers** t 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** the **Standard Change Template Name** supports Octopus variable expressions (e.g. `#{ServiceNow.StandardTemplate}`), allowing the template to vary by environment, tenant, or any other variable scope. If the expression resolves to an empty value, the change type falls back to `Normal`. + 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) @@ -314,7 +316,6 @@ The following variables are only available in version 2025.4 and later - 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 From 36eeb4f68fdc2be8f38c802c3871c5ea09221d16 Mon Sep 17 00:00:00 2001 From: wlthomson Date: Wed, 3 Jun 2026 15:41:01 +1200 Subject: [PATCH 2/4] Improve wording and punctuation --- src/pages/docs/approvals/jira-service-management/index.md | 2 +- src/pages/docs/approvals/servicenow/index.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/approvals/jira-service-management/index.md b/src/pages/docs/approvals/jira-service-management/index.md index ccb96cebe8..9927e95a21 100644 --- a/src/pages/docs/approvals/jira-service-management/index.md +++ b/src/pages/docs/approvals/jira-service-management/index.md @@ -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. Comments include the project name, environment, and version. From **2026.2**, for tenanted deployments, the tenant name and tags are also included. +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**. diff --git a/src/pages/docs/approvals/servicenow/index.md b/src/pages/docs/approvals/servicenow/index.md index 7c80a11c9c..3d630068f9 100644 --- a/src/pages/docs/approvals/servicenow/index.md +++ b/src/pages/docs/approvals/servicenow/index.md @@ -121,7 +121,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. Work notes include the project name, environment, and version. From **2026.2**, for tenanted deployments, the tenant name and tags are also included. +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**. @@ -173,7 +173,7 @@ Setting the **Standard Change Template Name** setting under **ITSM Providers** t 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** the **Standard Change Template Name** supports Octopus variable expressions (e.g. `#{ServiceNow.StandardTemplate}`), allowing the template to vary by environment, tenant, or any other variable scope. If the expression resolves to an empty value, the change type falls back to `Normal`. +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 From 667a0704e786dbeb03366e9a766eb9d18cb8dca3 Mon Sep 17 00:00:00 2001 From: wlthomson Date: Wed, 3 Jun 2026 15:43:14 +1200 Subject: [PATCH 3/4] Make markdownlint happy --- src/pages/docs/approvals/servicenow/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/approvals/servicenow/index.md b/src/pages/docs/approvals/servicenow/index.md index 3d630068f9..2f5c1d21c9 100644 --- a/src/pages/docs/approvals/servicenow/index.md +++ b/src/pages/docs/approvals/servicenow/index.md @@ -319,7 +319,7 @@ 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 +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. @@ -333,8 +333,8 @@ The ServiceNow integration uses the following REST endpoints: | 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 | +| 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 From 40071b3998a411db791a3c6a5478455546f7a116 Mon Sep 17 00:00:00 2001 From: wlthomson Date: Wed, 3 Jun 2026 17:00:06 +1200 Subject: [PATCH 4/4] Make markdownlint happy again --- src/pages/docs/approvals/servicenow/index.md | 81 ++++++++++---------- 1 file changed, 39 insertions(+), 42 deletions(-) diff --git a/src/pages/docs/approvals/servicenow/index.md b/src/pages/docs/approvals/servicenow/index.md index 2f5c1d21c9..5d25e98a6c 100644 --- a/src/pages/docs/approvals/servicenow/index.md +++ b/src/pages/docs/approvals/servicenow/index.md @@ -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 @@ -166,12 +167,9 @@ 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. @@ -255,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. @@ -300,17 +297,17 @@ 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 @@ -322,19 +319,19 @@ The following variables are only available in version 2025.4 and later 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