docs(servicenow): refresh Pro ServiceNow Integrator guide (OAuth, close fields, push filters) (#15298)

* docs(integrators): refresh ServiceNow guide — OAuth (Zurich + legacy), close fields, push filters [sc-13803]

- Instance Setup now covers both auth paths: ServiceNow Zurich+ (New Inbound
  Integration Experience -> OAuth client-credentials grant, with an OAuth
  Application User) and earlier releases (the legacy App Registry + refresh
  token). ServiceNow deprecated the classic 'Create an OAuth API endpoint for
  external clients' option our guide relied on. Also fixes the duplicated
  'Client ID' field label (the second one is the Client Secret).
- New 'Close and resolution fields' section documenting the apply_on custom
  field recipe for instances whose data policy makes the Resolution code
  mandatory on close (the 403 'Data Policy Exception'), with a worked example
  and the reserved-field / sys_id notes.
- integrations.md documents the new per-assignment push filters (minimum
  severity, active-only) and the one-assignment-per-asset guidance.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(servicenow): document custom numeric state values in the status mapping

Customized instances (and non-incident tables) use state values outside the standard set. Documents that numeric values pass through as configured, and that the built-in Resolution-code default only accompanies standard resolved/closed states - custom values pair with the close/resolution field mappings.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(servicenow): transition timing, JSON value coercion, and custom-table state caveats

Documents when transition mappings actually fire (state changes only - one journal entry per transition), the JSON typing of mapping values including the null-clears-field behavior and quoting escape, and the Incident-semantics caveat for standard state values on non-incident tables.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: devGregA

docs/content/issue_tracking/pro_integration/integrations.md

@@ -57,6 +57,19 @@ Findings can also be pushed automatically, with the **Issue Tracker Assignment**
 - **Automatically Update Existing Link**: When Findings or Finding Groups are **updated** in the assigned Product or Engagement, automatically push the object to the Issue Tracker if an existing link has already been created manually.
 - **Automatically Link New and Update Existing Link**: When Findings or Finding Groups are created **or** updated in the assigned Product or Engagement, automatically push the object to the Issue Tracker.
 
+#### Push Filters
+
+Each Issue Tracker Assignment can optionally narrow which Findings are pushed **automatically**:
+
+- **Minimum Severity**: only automatically create tickets for Findings at or above the selected severity. Leave it blank to include every severity.
+- **Active findings only**: only automatically create tickets for active Findings, skipping ones that are already mitigated, false positive, or risk accepted when the assignment first sees them.
+
+These filters apply to automatic **creation** only. Updates to a Finding that already has a linked ticket are always sent, so status changes (including closures) continue to propagate. A manual **Push to Integrators** always ignores the filters. Leaving both at their defaults preserves the original behavior of pushing every Finding.
+
+#### Assigning multiple Products
+
+An Issue Tracker Assignment targets a single Product or Engagement. To cover several assets, create one Assignment per Product (or Engagement). If you also need vendor fields to differ per asset — for example a distinct ServiceNow **Assignment group** or **Assigned to**, or a different Jira project — create a separate Issue Tracker Mapping (with its own Custom Field Mappings) for each asset and point each Assignment at the matching Mapping.
+
 ## Issue Tracker Ticket Representation
 
 Issue Tracker Tickets are represented by a series of icons under the "Integrator Tickets" column when viewing and listing

docs/content/issue_tracking/pro_integration/integrations_toolreference.md

@@ -332,13 +332,34 @@ The ServiceNow Integration allows you to push DefectDojo Findings as ServiceNow
 
 ### Instance Setup
 
-Your ServiceNow instance will require you to obtain a Refresh Token, associated with the User or Service account that will push Incidents to ServiceNow.
+DefectDojo authenticates to ServiceNow over OAuth 2.0. How you create the OAuth credentials depends on your ServiceNow release — newer releases (Zurich and later) use a Client Credentials grant, while earlier releases use a refresh token.
 
-You'll need to start by creating an OAuth registration on your ServiceNow instance for DefectDojo:
+#### ServiceNow Zurich and later (client credentials)
 
-1. In the left-hand navigation bar, search for “Application Registry” and select it.
-2. Click “New”.
-3. Choose “Create an OAuth API endpoint for external clients”.
+Recent ServiceNow releases deprecated the classic "Create an OAuth API endpoint for external clients" option in favor of the **New Inbound Integration Experience**, which issues an OAuth **Client Credentials** grant bound to a service account:
+
+1. In the left-hand navigation bar, search for "Application Registry" and select it.
+2. Click **New**, then choose **New Inbound Integration Experience**.
+3. Select **New Integration → OAuth - Client credentials grant**.
+4. Set the **OAuth Application User** to the service account that will create Incidents. That account's roles determine what DefectDojo is allowed to write.
+5. Save the registration. ServiceNow auto-generates the **Client ID** and **Client Secret** (leave those fields blank when creating the registration).
+
+Then, in DefectDojo:
+
+- **Instance Label** should be the label that you want to use to identify this integration.
+- **Location** should be set to the URL for your ServiceNow server, for example `https://your-organization.service-now.com/`.
+- **Client ID** should be the Client ID from the OAuth registration.
+- **Client Secret** should be the Client Secret from the OAuth registration.
+
+Leave the Refresh Token, Username, and Password fields empty — DefectDojo requests a fresh client-credentials token for each sync.
+
+#### Earlier ServiceNow releases (refresh token)
+
+On releases that still offer the classic registration, obtain a Refresh Token associated with the User or Service account that will push Incidents to ServiceNow:
+
+1. In the left-hand navigation bar, search for "Application Registry" and select it.
+2. Click "New".
+3. Choose "Create an OAuth API endpoint for external clients".
 4. Fill in the required fields:
     * Name: Provide a meaningful name for your application (e.g., Vulnerability Integration Client).
     * (Optional) Adjust the Token Lifespan:
@@ -366,7 +387,7 @@ If your ServiceNow credentials are correct, and allow for admin level-access to
 - **Location** should be set to the URL for your ServiceNow server, for example `https://your-organization.service-now.com/`.
 - **Refresh Token** is where the Refresh Token should be entered.
 - **Client ID** should be the Client ID set in the OAuth App Registration.
-- **Client ID** should be the Client Secret set in the OAuth App Registration.
+- **Client Secret** should be the Client Secret set in the OAuth App Registration.
 
 ### Severity Mapping Details
 
@@ -385,6 +406,35 @@ This maps to the ServiceNow Impact field.
 - **False Positive Mapping**: `Resolved`
 - **Risk Accepted Mapping**: `Resolved`
 
+Each mapping accepts a standard state label (`New`, `In Progress`, `On Hold`, `Resolved`, `Closed`, `Cancelled`) or a numeric state value. On instances with customized Incident states — or when targeting a table other than `incident` — use the numeric **state value** from your instance's choice list; a numeric value outside the standard set is sent to ServiceNow exactly as configured. The built-in Resolution-code default only accompanies the standard resolved/closed states, so pair custom state values with the close and resolution field mappings below.
+
+### Close and resolution fields
+
+Some ServiceNow instances enforce a Data Policy that makes fields such as the **Resolution code** (`close_code`) mandatory whenever an Incident moves to a resolved or closed state. If DefectDojo closes an Incident without them, ServiceNow rejects the write with an HTTP 403 *"Data Policy Exception"* and the reason is recorded in the integration's Errors view.
+
+Attach the required fields to the state change with **Custom Field Mappings**, setting **Apply On** to the disposition that should carry them:
+
+- **Transition to Closed** — sent when a Finding is mitigated / closed.
+- **Transition to False Positive** — sent when a Finding is marked a false positive.
+- **Transition to Risk Accepted** — sent when a Finding is risk accepted.
+
+For example, to satisfy a mandatory Resolution code:
+
+| Source | Field Name | Value | Apply On |
+|---|---|---|---|
+| Static | `close_code` | `Resolved by DefectDojo` | Transition to Closed |
+| Static | `close_notes` | `Reviewed by the security team` | Transition to Closed |
+| Static | `close_code` | `Not a defect` | Transition to False Positive |
+
+Notes:
+
+- Field Name is the ServiceNow column name — `close_code`, `close_notes`, or a custom `u_...` field.
+- Transition mappings fire when the record's state actually changes: a Finding that is already closed when first pushed, an update that closes or reopens the record, and the forced close when a ticket link is deleted. They are not re-sent on routine updates of an unchanged record, so journal fields such as `work_notes` receive one entry per transition.
+- Reference fields such as `assignment_group` and `assigned_to` expect a **sys_id**, not a display name.
+- Values that parse as JSON are sent typed: `true`, `42`, `[...]`, `{...}` — and `null`, which clears the field. To send such text as a literal string, wrap it in double quotes (e.g. `"null"`).
+- `short_description`, `description`, `state`, `impact`, `urgency`, and `priority` are owned by the description template and the severity/status mappings, so they cannot be set through a custom field mapping.
+- On tables other than `incident`, state values that match the standard Incident set (`1`, `2`, `3`, `6`, `7`, `8`) are still interpreted with Incident semantics — including the automatic Resolution code default on `6`/`7`/`8`. Prefer state values outside that range on custom tables, or supply the close fields explicitly as above.
+
 ## Shortcut
 
 The Shortcut integration allows you to push DefectDojo Findings as [Shortcut](https://www.shortcut.com/) Stories. Stories are created with the story type of Bug and assigned to a Team in your Shortcut workspace.