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..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. +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 4138f498e5..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 @@ -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**. @@ -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 @@ -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. @@ -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