From 7b989e27779d102f718276523040cd0d58c8a28e Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Mon, 6 Apr 2026 11:07:15 -0400
Subject: [PATCH 01/16] RHIDP-10933: [Doc] ServiceNow plugin: Allow integration
 without changing ServiceNow infrastructure

---
 ...bly-servicenow-custom-actions-in-rhdh.adoc |  9 ++++
 ...con-servicenow-entity-linking-methods.adoc | 34 +++++++++++++
 ...c-configure-servicenow-custom-mapping.adoc | 51 +++++++++++++++++++
 ...c-using-servicenow-scaffolder-actions.adoc | 50 ++++++++++++++++++
 ...f-servicenow-configuration-parameters.adoc | 40 +++++++++++++++
 5 files changed, 184 insertions(+)
 create mode 100644 modules/shared/con-servicenow-entity-linking-methods.adoc
 create mode 100644 modules/shared/proc-configure-servicenow-custom-mapping.adoc
 create mode 100644 modules/shared/proc-using-servicenow-scaffolder-actions.adoc
 create mode 100644 modules/shared/ref-servicenow-configuration-parameters.adoc

diff --git a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
index 0540cc6ad7d..57596d1a340 100644
--- a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
+++ b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
@@ -15,6 +15,15 @@ The custom actions in {product-short} help you automate the management of record
 
 The `ServiceNow` custom actions plugin is community-sourced.
 
+
+include::../modules/shared/con-servicenow-entity-linking-methods.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-configure-servicenow-custom-mapping.adoc[leveloffset=+2]
+
+include::../modules/shared/proc-using-servicenow-scaffolder-actions.adoc[leveloffset=+2]
+
+include::../modules/shared/ref-servicenow-configuration-parameters.adoc[leveloffset=+2]
+
 include::../modules/shared/proc-enable-servicenow-custom-actions-plugin-in-rhdh.adoc[leveloffset=+1]
 
 include::../modules/shared/ref-supported-servicenow-custom-actions-in-rhdh.adoc[leveloffset=+1]
diff --git a/modules/shared/con-servicenow-entity-linking-methods.adoc b/modules/shared/con-servicenow-entity-linking-methods.adoc
new file mode 100644
index 00000000000..04fad63018a
--- /dev/null
+++ b/modules/shared/con-servicenow-entity-linking-methods.adoc
@@ -0,0 +1,34 @@
+:_mod-docs-content-type: CONCEPT
+[id="servicenow-entity-linking-methods_{context}"]
+= ServiceNow entity linking methods
+
+[role="_abstract"]
+
+To view and manage ServiceNow incidents directly in {product} ({product-very-short}), you must link an entity to your ServiceNow records. Linking ensures that incident data is accurately synchronized and visible within the relevant component or system.
+
+{product} provides two methods for linking these entities. You can choose the method that best fits your organization's security requirements and your ability to modify the ServiceNow schema.
+
+== Direct mapping (Backstage Entity ID column)
+
+The default method requires adding a custom column named `backstage_entity_id` to your ServiceNow incident table. You then manually or programmatically assign the specific {product-very-short} entity reference (for example, `component:default/my-service`) to this column in ServiceNow.
+
+* **Pros:** Highly secure and precise; ensures data is only exposed to the intended entity.
+* **Cons:** Requires a schema change in ServiceNow and manual data entry for each incident.
+
+== Flexible mapping (Custom column mapping)
+
+The flexible mapping approach is an optional, opt-in feature that allows you to use any existing column in your ServiceNow incident table to link to {product-very-short} entities. Instead of creating a new column, you configure the ServiceNow plugin to look at an existing field (such as `short_description`, `cmdb_ci`, or a custom organizational ID) to match the entity.
+
+* **Pros:** Does not require ServiceNow schema changes; faster to implement for organizations with strict ServiceNow governance.
+* **Cons:** Requires careful configuration to ensure that the search criteria in the chosen column are unique enough to prevent displaying unrelated incidents.
+
+== Comparison of linking methods
+
+|===
+| Feature | Direct Mapping | Flexible Mapping
+
+| **ServiceNow Schema Change** | Required | Not Required
+| **Security Level** | High (Strict matching) | Medium (Dependent on column data)
+| **Configuration Complexity** | Low (Plugin side) | Medium (Requires YAML mapping)
+| **Ideal Use Case** | New ServiceNow instances or high-security environments. | Existing ServiceNow instances where schema changes are restricted.
+|===
diff --git a/modules/shared/proc-configure-servicenow-custom-mapping.adoc b/modules/shared/proc-configure-servicenow-custom-mapping.adoc
new file mode 100644
index 00000000000..5c9468ce367
--- /dev/null
+++ b/modules/shared/proc-configure-servicenow-custom-mapping.adoc
@@ -0,0 +1,51 @@
+:_mod-docs-content-type: PROCEDURE
+[id="configure-servicenow-custom-mapping_{context}"]
+= Configure ServiceNow incident mapping using custom columns
+
+[role="_abstract"]
+
+To integrate ServiceNow without modifying your existing schema, you can configure the plugin to map incidents using any ServiceNow column. While the platform uses the `backstage_entity_id `column by default, custom mapping ensures compatibility with your current ServiceNow configuration.
+
+.Prerequisites
+* You have installed the ServiceNow plugin 1.0 or later.
+* You have administrative access to the {product} configuration.
+* You have identified the specific column in your ServiceNow incident table (for example, `short_description` or `cmdb_ci`) that contains values matching your {product-very-short} entity names.
+
+.Procedure
+
+. Open your {product} `app-config.yaml` file.
+
+. Navigate to the `catalog.providers.servicenow` section.
+
+. Add the `mapping` configuration to specify your custom column. 
++
+[source,yaml]
+----
+catalog:
+  providers:
+    servicenow:
+      your-instance-name:
+        baseUrl: ${SERVICENOW_BASE_URL}
+        # The following lines enable the flexible mapping
+        entityIdentificationField: "u_your_custom_column"
+        # Ensure your integration still points to the correct location
+        schedule:
+          frequency: { minutes: 30 }
+          timeout: { minutes: 3 }
+----
+
+* `catalog.providers.servicenow.your-instance-name.entityIdentificationField` specifies the actual name of the column you wish to use for entity matching.
+
+. Save the changes to `app-config.yaml`.
+
+. Restart your {product} instance to apply the configuration.
+
+.Verification
+
+. Log in to your {product}.
+
+. Open a Component that has a corresponding entry in your chosen ServiceNow column.
+
+. Select the **ServiceNow** tab.
+
+. Confirm that incidents are displayed correctly without the need for a `backstage_entity_id` column in ServiceNow.
\ No newline at end of file
diff --git a/modules/shared/proc-using-servicenow-scaffolder-actions.adoc b/modules/shared/proc-using-servicenow-scaffolder-actions.adoc
new file mode 100644
index 00000000000..d1b539468f2
--- /dev/null
+++ b/modules/shared/proc-using-servicenow-scaffolder-actions.adoc
@@ -0,0 +1,50 @@
+:_mod-docs-content-type: PROCEDURE
+[id="using-servicenow-scaffolder-actions_{context}"]
+= Using ServiceNow scaffolder actions in Software Templates
+
+[role="_abstract"]
+
+ServiceNow scaffolder actions enable the automation of ServiceNow operations, such as creating incidents or updating records, directly from Software Templates.
+
+In {product} {product-very-short} 1.9 and later, these actions have been moved to a dedicated `servicenow` workspace to improve integration with the ServiceNow plugin.
+
+.Prerequisites
+
+* You have configured the ServiceNow plugin in your `app-config.yaml` file.
+* Your Software template is defined as an allowed entity type, for example `Template`, in the `catalog.rules` section of your `app-config.yaml` file.
+* You have the required permissions to create or edit Software Templates in {product-very-short}.
+
+.Procedure
+
+. Open your Software Template YAML file (usually `template.yaml`).
+
+. In the `spec.steps` section, define a ServiceNow action using the `servicenow:` prefix.
++
+[source,yaml]
+----
+spec:
+  steps:
+    - id: create-incident
+      name: Create ServiceNow Incident
+      action: servicenow:create-incident
+      input:
+        instanceName: 'production'
+        short_description: 'Incident created from RHDH Software Template'
+        severity: '3'
+----
+
+* `spec.steps.action` specifies the automated function within the ServiceNow workspace that {product-very-short} uses to generate a new incident record in your connected ServiceNow instance. If you are migrating a template from an older version, update the action ID to match the new workspace location.
+
+* `spec.steps.input.instanceName` specifies the ServiceNow instance, as defined in your `app-config.yaml` file, that {product-very-short} targets when executing the scaffolder action. 
+
+. Save the template file and register it in the {product-very-short} Catalog. If you are registering the template via a Pull Request, ensure you use the {backstage-integration} branch as configured in your `app-config.yaml` file.
+
+. Run the template from the **Create** menu to verify the integration.
+
+.Verification
+
+. After the Scaffolder task completes, navigate to your ServiceNow instance.
+
+. Confirm that the new incident appears with the description provided in the template.
+
+. If you are using flexible mapping, verify that the incident is correctly linked to the new component in the **ServiceNow** tab of the {product-very-short} UI.
diff --git a/modules/shared/ref-servicenow-configuration-parameters.adoc b/modules/shared/ref-servicenow-configuration-parameters.adoc
new file mode 100644
index 00000000000..b2fd02e573b
--- /dev/null
+++ b/modules/shared/ref-servicenow-configuration-parameters.adoc
@@ -0,0 +1,40 @@
+:_mod-docs-content-type: REFERENCE
+[id="servicenow-configuration-parameters_{context}"]
+= ServiceNow configuration parameters
+
+[role="_abstract"]
+
+The ServiceNow plugin configuration parameters define one or more ServiceNow instances and map incidents to entities in the `app-config.yaml` file.
+
+.ServiceNow configuration parameters
+[cols="3,1,1,5", options="header"]
+|===
+| Parameter | Type | Default | Description
+
+| `baseUrl` | String | N/A | *Required.* The base URL of your ServiceNow instance (for example, `https://instance.service-now.com`).
+| `entityIdentificationField` | String | `backstage_entity_id` | The ServiceNow column used to match {product-very-short} entities. Specify a custom column name to use flexible mapping without ServiceNow schema changes.
+| `username` | String | N/A | The username for the ServiceNow service account.
+| `password` | String | N/A | The password for the ServiceNow service account.
+| `schedule.frequency` | Duration | `30m` | The interval at which the plugin synchronizes with ServiceNow.
+| `schedule.timeout` | Duration | `3m` | The maximum time allowed for a single synchronization attempt.
+|===
+
+== Multi-instance configuration example
+
+You can configure multiple ServiceNow endpoints by providing a unique key for each instance in the `servicenow` configuration block. These keys correspond to the `instanceName` parameter used in Software Templates.
+
+[source,yaml]
+----
+catalog:
+  providers:
+    servicenow:
+      production: <1>
+        baseUrl: ${SERVICENOW_PROD_URL}
+        entityIdentificationField: "u_custom_id"
+      sandbox: <2>
+        baseUrl: ${SERVICENOW_SANDBOX_URL}
+----
+
+* `catalog.providers.servicenow.production` specifies the ServiceNow instance, as defined in your `app-config.yaml` file, that {product-very-short} targets when executing the scaffolder action.
+
+* `catalog.providers.servicenow.sandbox` specifies an additional ServiceNow instance, such as a sandbox environment, for testing purposes.
\ No newline at end of file

From 773d52cb8ba5c8090413663b5b41fda6a8891ed8 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Tue, 14 Apr 2026 12:57:35 -0400
Subject: [PATCH 02/16] RHIDP-10933: edits from AI review

---
 ...con-servicenow-entity-linking-methods.adoc | 29 ++++++++++++-------
 ...c-configure-servicenow-custom-mapping.adoc | 13 ++++-----
 2 files changed, 23 insertions(+), 19 deletions(-)

diff --git a/modules/shared/con-servicenow-entity-linking-methods.adoc b/modules/shared/con-servicenow-entity-linking-methods.adoc
index 04fad63018a..089e518cff3 100644
--- a/modules/shared/con-servicenow-entity-linking-methods.adoc
+++ b/modules/shared/con-servicenow-entity-linking-methods.adoc
@@ -3,7 +3,6 @@
 = ServiceNow entity linking methods
 
 [role="_abstract"]
-
 To view and manage ServiceNow incidents directly in {product} ({product-very-short}), you must link an entity to your ServiceNow records. Linking ensures that incident data is accurately synchronized and visible within the relevant component or system.
 
 {product} provides two methods for linking these entities. You can choose the method that best fits your organization's security requirements and your ability to modify the ServiceNow schema.
@@ -12,23 +11,31 @@ To view and manage ServiceNow incidents directly in {product} ({product-very-sho
 
 The default method requires adding a custom column named `backstage_entity_id` to your ServiceNow incident table. You then manually or programmatically assign the specific {product-very-short} entity reference (for example, `component:default/my-service`) to this column in ServiceNow.
 
-* **Pros:** Highly secure and precise; ensures data is only exposed to the intended entity.
-* **Cons:** Requires a schema change in ServiceNow and manual data entry for each incident.
+* Advantages:
+** Highly secure and precise
+** Ensures data is only exposed to the intended entity
+* Limitations:
+** Requires a schema change in ServiceNow
+** Requires manual data entry for each incident
 
 == Flexible mapping (Custom column mapping)
 
-The flexible mapping approach is an optional, opt-in feature that allows you to use any existing column in your ServiceNow incident table to link to {product-very-short} entities. Instead of creating a new column, you configure the ServiceNow plugin to look at an existing field (such as `short_description`, `cmdb_ci`, or a custom organizational ID) to match the entity.
+The flexible mapping approach is an opt-in feature that allows you to use any existing column in your ServiceNow incident table to link to {product-very-short} entities. Instead of creating a new column, you configure the ServiceNow plugin to look at an existing field (such as `short_description`, `cmdb_ci`, or a custom organizational ID) to match the entity.
 
-* **Pros:** Does not require ServiceNow schema changes; faster to implement for organizations with strict ServiceNow governance.
-* **Cons:** Requires careful configuration to ensure that the search criteria in the chosen column are unique enough to prevent displaying unrelated incidents.
+* Advantages:
+** Does not require ServiceNow schema changes
+** Faster to implement for organizations with strict ServiceNow governance
+* Limitations:
+** Requires careful configuration to ensure that the search criteria in the chosen column are unique enough to prevent displaying unrelated incidents
 
 == Comparison of linking methods
 
+[cols="1h,1,1"]
 |===
-| Feature | Direct Mapping | Flexible Mapping
+| Feature | Direct mapping | Flexible mapping
 
-| **ServiceNow Schema Change** | Required | Not Required
-| **Security Level** | High (Strict matching) | Medium (Dependent on column data)
-| **Configuration Complexity** | Low (Plugin side) | Medium (Requires YAML mapping)
-| **Ideal Use Case** | New ServiceNow instances or high-security environments. | Existing ServiceNow instances where schema changes are restricted.
+| ServiceNow schema change | Required | Not required
+| Security level | High (strict matching) | Medium (dependent on column data)
+| Configuration complexity | Low (plugin side) | Medium (requires YAML mapping)
+| Ideal use case | New ServiceNow instances or high-security environments | Existing ServiceNow instances where schema changes are restricted
 |===
diff --git a/modules/shared/proc-configure-servicenow-custom-mapping.adoc b/modules/shared/proc-configure-servicenow-custom-mapping.adoc
index 5c9468ce367..1841ab2d62f 100644
--- a/modules/shared/proc-configure-servicenow-custom-mapping.adoc
+++ b/modules/shared/proc-configure-servicenow-custom-mapping.adoc
@@ -3,8 +3,7 @@
 = Configure ServiceNow incident mapping using custom columns
 
 [role="_abstract"]
-
-To integrate ServiceNow without modifying your existing schema, you can configure the plugin to map incidents using any ServiceNow column. While the platform uses the `backstage_entity_id `column by default, custom mapping ensures compatibility with your current ServiceNow configuration.
+To integrate ServiceNow without modifying your existing schema, you can configure the plugin to map incidents using any ServiceNow column. While the platform uses the `backstage_entity_id` column by default, custom mapping ensures compatibility with your current ServiceNow configuration.
 
 .Prerequisites
 * You have installed the ServiceNow plugin 1.0 or later.
@@ -26,15 +25,13 @@ catalog:
     servicenow:
       your-instance-name:
         baseUrl: ${SERVICENOW_BASE_URL}
-        # The following lines enable the flexible mapping
         entityIdentificationField: "u_your_custom_column"
-        # Ensure your integration still points to the correct location
         schedule:
           frequency: { minutes: 30 }
           timeout: { minutes: 3 }
 ----
-
-* `catalog.providers.servicenow.your-instance-name.entityIdentificationField` specifies the actual name of the column you wish to use for entity matching.
++
+`catalog.providers.servicenow.your-instance-name.entityIdentificationField`:: Specifies the actual name of the column you wish to use for entity matching.
 
 . Save the changes to `app-config.yaml`.
 
@@ -44,8 +41,8 @@ catalog:
 
 . Log in to your {product}.
 
-. Open a Component that has a corresponding entry in your chosen ServiceNow column.
+. Open a component that has a corresponding entry in your chosen ServiceNow column.
 
 . Select the **ServiceNow** tab.
 
-. Confirm that incidents are displayed correctly without the need for a `backstage_entity_id` column in ServiceNow.
\ No newline at end of file
+. Confirm that the ServiceNow tab displays incidents and that no error message indicates a missing `backstage_entity_id` column.
\ No newline at end of file

From 08f74df023f63d0936fc83c84545d08cfa5ee4fd Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Tue, 14 Apr 2026 16:38:19 -0400
Subject: [PATCH 03/16] RHIDP-10933: revised for style using AI

---
 ...c-using-servicenow-scaffolder-actions.adoc | 19 ++++++++++---------
 ...f-servicenow-configuration-parameters.adoc | 13 ++++++-------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/modules/shared/proc-using-servicenow-scaffolder-actions.adoc b/modules/shared/proc-using-servicenow-scaffolder-actions.adoc
index d1b539468f2..34d21587914 100644
--- a/modules/shared/proc-using-servicenow-scaffolder-actions.adoc
+++ b/modules/shared/proc-using-servicenow-scaffolder-actions.adoc
@@ -1,24 +1,25 @@
 :_mod-docs-content-type: PROCEDURE
 [id="using-servicenow-scaffolder-actions_{context}"]
-= Using ServiceNow scaffolder actions in Software Templates
+= Using ServiceNow scaffolder actions in software templates
 
 [role="_abstract"]
-
-ServiceNow scaffolder actions enable the automation of ServiceNow operations, such as creating incidents or updating records, directly from Software Templates.
+With ServiceNow scaffolder actions, you can automate ServiceNow operations, such as creating incidents or updating records, directly from software templates.
 
 In {product} {product-very-short} 1.9 and later, these actions have been moved to a dedicated `servicenow` workspace to improve integration with the ServiceNow plugin.
 
 .Prerequisites
 
 * You have configured the ServiceNow plugin in your `app-config.yaml` file.
+
 * Your Software template is defined as an allowed entity type, for example `Template`, in the `catalog.rules` section of your `app-config.yaml` file.
+
 * You have the required permissions to create or edit Software Templates in {product-very-short}.
 
 .Procedure
 
 . Open your Software Template YAML file (usually `template.yaml`).
 
-. In the `spec.steps` section, define a ServiceNow action using the `servicenow:` prefix.
+. In the `spec.steps` section, define a ServiceNow action by using the `servicenow:` prefix.
 +
 [source,yaml]
 ----
@@ -33,18 +34,18 @@ spec:
         severity: '3'
 ----
 
-* `spec.steps.action` specifies the automated function within the ServiceNow workspace that {product-very-short} uses to generate a new incident record in your connected ServiceNow instance. If you are migrating a template from an older version, update the action ID to match the new workspace location.
+`spec.steps.action`:: Specifies the automated function in the ServiceNow workspace for generating a new incident record in the connected ServiceNow instance. If you migrate a template from an older version, update the action ID to match the new workspace location.
 
-* `spec.steps.input.instanceName` specifies the ServiceNow instance, as defined in your `app-config.yaml` file, that {product-very-short} targets when executing the scaffolder action. 
+`spec.steps.input.instanceName`:: Specifies the ServiceNow instance, as defined in your `app-config.yaml` file, that {product-very-short} targets when it executes the scaffolder action.
 
-. Save the template file and register it in the {product-very-short} Catalog. If you are registering the template via a Pull Request, ensure you use the {backstage-integration} branch as configured in your `app-config.yaml` file.
+. Save the template file and register it in the {product-very-short} catalog. If you register the template through a pull request, ensure that you use the {backstage-integration} branch as configured in your `app-config.yaml` file.
 
 . Run the template from the **Create** menu to verify the integration.
 
 .Verification
 
-. After the Scaffolder task completes, navigate to your ServiceNow instance.
+. After the scaffolder task completes, go to your ServiceNow instance.
 
 . Confirm that the new incident appears with the description provided in the template.
 
-. If you are using flexible mapping, verify that the incident is correctly linked to the new component in the **ServiceNow** tab of the {product-very-short} UI.
+. If you use flexible mapping, verify that the incident is correctly linked to the new component in the *ServiceNow* tab of the {product-very-short} user interface.
\ No newline at end of file
diff --git a/modules/shared/ref-servicenow-configuration-parameters.adoc b/modules/shared/ref-servicenow-configuration-parameters.adoc
index b2fd02e573b..ba05b95859a 100644
--- a/modules/shared/ref-servicenow-configuration-parameters.adoc
+++ b/modules/shared/ref-servicenow-configuration-parameters.adoc
@@ -3,8 +3,7 @@
 = ServiceNow configuration parameters
 
 [role="_abstract"]
-
-The ServiceNow plugin configuration parameters define one or more ServiceNow instances and map incidents to entities in the `app-config.yaml` file.
+Use the ServiceNow plugin configuration parameters to define one or more ServiceNow instances and to map incidents to entities in the `app-config.yaml` file.
 
 .ServiceNow configuration parameters
 [cols="3,1,1,5", options="header"]
@@ -21,20 +20,20 @@ The ServiceNow plugin configuration parameters define one or more ServiceNow ins
 
 == Multi-instance configuration example
 
-You can configure multiple ServiceNow endpoints by providing a unique key for each instance in the `servicenow` configuration block. These keys correspond to the `instanceName` parameter used in Software Templates.
+You can configure multiple ServiceNow endpoints by providing a unique key for each instance in the `servicenow` configuration block. These keys correspond to the `instanceName` parameter used in software templates.
 
 [source,yaml]
 ----
 catalog:
   providers:
     servicenow:
-      production: <1>
+      production: 
         baseUrl: ${SERVICENOW_PROD_URL}
         entityIdentificationField: "u_custom_id"
-      sandbox: <2>
+      sandbox: 
         baseUrl: ${SERVICENOW_SANDBOX_URL}
 ----
 
-* `catalog.providers.servicenow.production` specifies the ServiceNow instance, as defined in your `app-config.yaml` file, that {product-very-short} targets when executing the scaffolder action.
+`catalog.providers.servicenow.production`:: Specifies the ServiceNow instance, as defined in your `app-config.yaml` file, that {product-very-short} targets when it executes the scaffolder action.
 
-* `catalog.providers.servicenow.sandbox` specifies an additional ServiceNow instance, such as a sandbox environment, for testing purposes.
\ No newline at end of file
+`catalog.providers.servicenow.sandbox`:: Specifies an additional ServiceNow instance, such as a sandbox environment, for testing.

From cf526cc5f09af1fcf3e4a50b2f266c46d92aa1fd Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Wed, 15 Apr 2026 14:19:14 -0400
Subject: [PATCH 04/16] RHIDP-10933: Updated based on  dev review

---
 ...bly-servicenow-custom-actions-in-rhdh.adoc |  2 +-
 ...c-configure-servicenow-custom-mapping.adoc | 48 -----------------
 .../proc-linking-servicenow-entities.adoc     | 53 +++++++++++++++++++
 ...f-servicenow-configuration-parameters.adoc | 50 ++++++++++-------
 4 files changed, 86 insertions(+), 67 deletions(-)
 delete mode 100644 modules/shared/proc-configure-servicenow-custom-mapping.adoc
 create mode 100644 modules/shared/proc-linking-servicenow-entities.adoc

diff --git a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
index 57596d1a340..59e5192dfd6 100644
--- a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
+++ b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
@@ -18,7 +18,7 @@ The `ServiceNow` custom actions plugin is community-sourced.
 
 include::../modules/shared/con-servicenow-entity-linking-methods.adoc[leveloffset=+1]
 
-include::../modules/shared/proc-configure-servicenow-custom-mapping.adoc[leveloffset=+2]
+include::../modules/shared/proc-linking-servicenow-entities.adoc[leveloffset=+2] 
 
 include::../modules/shared/proc-using-servicenow-scaffolder-actions.adoc[leveloffset=+2]
 
diff --git a/modules/shared/proc-configure-servicenow-custom-mapping.adoc b/modules/shared/proc-configure-servicenow-custom-mapping.adoc
deleted file mode 100644
index 1841ab2d62f..00000000000
--- a/modules/shared/proc-configure-servicenow-custom-mapping.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-:_mod-docs-content-type: PROCEDURE
-[id="configure-servicenow-custom-mapping_{context}"]
-= Configure ServiceNow incident mapping using custom columns
-
-[role="_abstract"]
-To integrate ServiceNow without modifying your existing schema, you can configure the plugin to map incidents using any ServiceNow column. While the platform uses the `backstage_entity_id` column by default, custom mapping ensures compatibility with your current ServiceNow configuration.
-
-.Prerequisites
-* You have installed the ServiceNow plugin 1.0 or later.
-* You have administrative access to the {product} configuration.
-* You have identified the specific column in your ServiceNow incident table (for example, `short_description` or `cmdb_ci`) that contains values matching your {product-very-short} entity names.
-
-.Procedure
-
-. Open your {product} `app-config.yaml` file.
-
-. Navigate to the `catalog.providers.servicenow` section.
-
-. Add the `mapping` configuration to specify your custom column. 
-+
-[source,yaml]
-----
-catalog:
-  providers:
-    servicenow:
-      your-instance-name:
-        baseUrl: ${SERVICENOW_BASE_URL}
-        entityIdentificationField: "u_your_custom_column"
-        schedule:
-          frequency: { minutes: 30 }
-          timeout: { minutes: 3 }
-----
-+
-`catalog.providers.servicenow.your-instance-name.entityIdentificationField`:: Specifies the actual name of the column you wish to use for entity matching.
-
-. Save the changes to `app-config.yaml`.
-
-. Restart your {product} instance to apply the configuration.
-
-.Verification
-
-. Log in to your {product}.
-
-. Open a component that has a corresponding entry in your chosen ServiceNow column.
-
-. Select the **ServiceNow** tab.
-
-. Confirm that the ServiceNow tab displays incidents and that no error message indicates a missing `backstage_entity_id` column.
\ No newline at end of file
diff --git a/modules/shared/proc-linking-servicenow-entities.adoc b/modules/shared/proc-linking-servicenow-entities.adoc
new file mode 100644
index 00000000000..980cea6040b
--- /dev/null
+++ b/modules/shared/proc-linking-servicenow-entities.adoc
@@ -0,0 +1,53 @@
+:_mod-docs-content-type: PROCEDURE
+[id="linking-servicenow-entities_{context}"]
+= Linking ServiceNow tickets to catalog entities
+
+[role="_abstract"]
+The ServiceNow integration in {product} uses software catalog annotations to associate entities with ServiceNow records. By defining these identifiers, the ServiceNow plugin can retrieve and display relevant tickets and incidents directly within the component dashboard.
+
+.Prerequisites
+* The ServiceNow plugin is installed and configured in your {product} instance.
+* You have the unique identifier (such as a Service ID or Category) for the ServiceNow resource you want to link.
+
+.Procedure
+
+. Open the `catalog-info.yaml` file of the component you want to link to ServiceNow.
+
+. Add the `servicenow.com/service-id` annotation to the `metadata.annotations` section.
++
+[source,yaml]
+----
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: example-component
+  annotations:
+    servicenow.com/service-id: <your-service-id>
+----
++
+metadata.annotations.servicenow.com/service-id:: Specifies the service identifier from your ServiceNow instance.   
+
+. Optional: If your organization uses different categories to filter tickets, you can also add the category annotation:
++
+[source,yaml]
+----
+metadata:
+  annotations:
+    servicenow.com/category: "software"
+----
++
+metadata.annotations.servicenow.com/category:: Specifies the ServiceNow category used to filter the displayed incidents.
+
+. Save the changes to `catalog-info.yaml` and commit them to your repository.
+
+. If the changes do not appear automatically, manually refresh the entity in the {product} catalog.
+
+.Verification
+
+. Log in to your {product} and navigate to the *Catalog*.
+
+. Select the component you updated.
+
+. Select the *ServiceNow* tab.
+
+. Confirm that the tab displays ServiceNow tickets or incidents associated with the provided ID.
\ No newline at end of file
diff --git a/modules/shared/ref-servicenow-configuration-parameters.adoc b/modules/shared/ref-servicenow-configuration-parameters.adoc
index ba05b95859a..e44f10af656 100644
--- a/modules/shared/ref-servicenow-configuration-parameters.adoc
+++ b/modules/shared/ref-servicenow-configuration-parameters.adoc
@@ -3,37 +3,51 @@
 = ServiceNow configuration parameters
 
 [role="_abstract"]
-Use the ServiceNow plugin configuration parameters to define one or more ServiceNow instances and to map incidents to entities in the `app-config.yaml` file.
+Configure the ServiceNow integration by defining instance connection parameters in the app-config.yaml file. This reference provides the required configuration blocks and syntax for both the ServiceNow UI plugin and Scaffolder actions.
 
-.ServiceNow configuration parameters
+== ServiceNow backend configuration
+
+The following parameters apply to the core ServiceNow integration used by the UI plugin and Scaffolder actions.
+
+.ServiceNow global configuration parameters
 [cols="3,1,1,5", options="header"]
 |===
 | Parameter | Type | Default | Description
 
-| `baseUrl` | String | N/A | *Required.* The base URL of your ServiceNow instance (for example, `https://instance.service-now.com`).
-| `entityIdentificationField` | String | `backstage_entity_id` | The ServiceNow column used to match {product-very-short} entities. Specify a custom column name to use flexible mapping without ServiceNow schema changes.
-| `username` | String | N/A | The username for the ServiceNow service account.
-| `password` | String | N/A | The password for the ServiceNow service account.
-| `schedule.frequency` | Duration | `30m` | The interval at which the plugin synchronizes with ServiceNow.
-| `schedule.timeout` | Duration | `3m` | The maximum time allowed for a single synchronization attempt.
+| `baseUrl` | String | N/A | Required. The base URL of your ServiceNow instance (for example, `https://instance.service-now.com`).
+| `username` | String | N/A | The username for Basic Authentication. Required if not using OAuth.
+| `password` | String | N/A | The password for Basic Authentication. Required if not using OAuth.
+| `apiToken` | String | N/A | An alternative to username/password for token-based authentication.
 |===
 
-== Multi-instance configuration example
+=== OAuth 2.0 authentication
+
+If your organization uses OAuth 2.0, use the following parameters instead of `username` and `password`:
 
-You can configure multiple ServiceNow endpoints by providing a unique key for each instance in the `servicenow` configuration block. These keys correspond to the `instanceName` parameter used in software templates.
+* `oauthClientId`: The Client ID from your ServiceNow OAuth application.
+* `oauthClientSecret`: The Client Secret from your ServiceNow OAuth application.
+* `oauthTokenUrl`: The URL used to retrieve the access token.
+
+== Scaffolder actions configuration
+
+To use ServiceNow actions in software templates, define your instances under the `scaffolder.notifications.servicenow` block.
 
 [source,yaml]
 ----
-catalog:
-  providers:
+scaffolder:
+  notifications:
     servicenow:
-      production: 
+      production:
         baseUrl: ${SERVICENOW_PROD_URL}
-        entityIdentificationField: "u_custom_id"
-      sandbox: 
-        baseUrl: ${SERVICENOW_SANDBOX_URL}
+        username: ${SERVICENOW_USER}
+        password: ${SERVICENOW_PASS}
 ----
++
+scaffolder.notifications.servicenow.<instance_name>:: Defines a unique key for a ServiceNow instance used by the Scaffolder.
+
+== Catalog annotations
 
-`catalog.providers.servicenow.production`:: Specifies the ServiceNow instance, as defined in your `app-config.yaml` file, that {product-very-short} targets when it executes the scaffolder action.
+The ServiceNow plugin does not use `app-config.yaml` for entity mapping or filtering. To link catalog entities to ServiceNow, use the following annotations in the `catalog-info.yaml` file:
 
-`catalog.providers.servicenow.sandbox`:: Specifies an additional ServiceNow instance, such as a sandbox environment, for testing.
+* `servicenow.com/service-id`: Maps the entity to a specific ServiceNow Service ID.
+* `servicenow.com/category:` Filters incidents by a specific ServiceNow category.

From 1e0404dfc6f47f51384b6fb34fc40e49b022cde6 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Wed, 15 Apr 2026 14:46:12 -0400
Subject: [PATCH 05/16] RHIDP-10933: updated task for using servicenow
 scaffolder actions

---
 ...c-using-servicenow-scaffolder-actions.adoc | 37 ++++++++-----------
 1 file changed, 16 insertions(+), 21 deletions(-)

diff --git a/modules/shared/proc-using-servicenow-scaffolder-actions.adoc b/modules/shared/proc-using-servicenow-scaffolder-actions.adoc
index 34d21587914..f3a7f2ab3a7 100644
--- a/modules/shared/proc-using-servicenow-scaffolder-actions.adoc
+++ b/modules/shared/proc-using-servicenow-scaffolder-actions.adoc
@@ -3,24 +3,20 @@
 = Using ServiceNow scaffolder actions in software templates
 
 [role="_abstract"]
-With ServiceNow scaffolder actions, you can automate ServiceNow operations, such as creating incidents or updating records, directly from software templates.
-
-In {product} {product-very-short} 1.9 and later, these actions have been moved to a dedicated `servicenow` workspace to improve integration with the ServiceNow plugin.
+Add ServiceNow actions to your Software Templates to automate ticket creation and record updates during the software scaffolding process. Use these actions to ensure consistent tracking and compliance throughout your development lifecycle.
 
 .Prerequisites
-
-* You have configured the ServiceNow plugin in your `app-config.yaml` file.
-
-* Your Software template is defined as an allowed entity type, for example `Template`, in the `catalog.rules` section of your `app-config.yaml` file.
-
-* You have the required permissions to create or edit Software Templates in {product-very-short}.
+* You have configured the ServiceNow instance parameters in the `scaffolder.notifications.servicenow` section of your `app-config.yaml` file.
+* You have the required permissions to edit Software Templates in the source repository.
+* You have registered the Software Template in the {product} catalog.
 
 .Procedure
 
-. Open your Software Template YAML file (usually `template.yaml`).
+. Open your Software Template YAML file. For example, `template.yaml`.
 
-. In the `spec.steps` section, define a ServiceNow action by using the `servicenow:` prefix.
+. Add the `servicenow:create-incident` action to the `spec.steps` block.
 +
+...
 [source,yaml]
 ----
 spec:
@@ -29,23 +25,22 @@ spec:
       name: Create ServiceNow Incident
       action: servicenow:create-incident
       input:
-        instanceName: 'production'
+        instanceName: 'production' # <1>
         short_description: 'Incident created from RHDH Software Template'
-        severity: '3'
 ----
++
+spec.steps.action:: Specifies the `servicenow:create-incident` identifier to trigger the ServiceNow integration.
+spec.steps.input.instanceName:: Specifies the name of the ServiceNow instance defined in your `app-config.yaml` file.
 
-`spec.steps.action`:: Specifies the automated function in the ServiceNow workspace for generating a new incident record in the connected ServiceNow instance. If you migrate a template from an older version, update the action ID to match the new workspace location.
+. Save the changes and push them to your Git repository.
 
-`spec.steps.input.instanceName`:: Specifies the ServiceNow instance, as defined in your `app-config.yaml` file, that {product-very-short} targets when it executes the scaffolder action.
 
-. Save the template file and register it in the {product-very-short} catalog. If you register the template through a pull request, ensure that you use the {backstage-integration} branch as configured in your `app-config.yaml` file.
+.Verification
 
-. Run the template from the **Create** menu to verify the integration.
+. In {product}, navigate to the *Create* menu and select your template.
 
-.Verification
+. Fill out the required fields and click *Next Step* until the dry-run or execution begins.
 
-. After the scaffolder task completes, go to your ServiceNow instance.
+. After the task completes, log in to your ServiceNow instance.
 
 . Confirm that the new incident appears with the description provided in the template.
-
-. If you use flexible mapping, verify that the incident is correctly linked to the new component in the *ServiceNow* tab of the {product-very-short} user interface.
\ No newline at end of file

From b3bc2a8490e30b23f276f71e67ab26c3198955b8 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 8 May 2026 16:53:46 -0400
Subject: [PATCH 06/16] RHIDP-10933: added task after discussion with developer

---
 ...bly-servicenow-custom-actions-in-rhdh.adoc |  2 +
 .../proc-configure-servicenow-image-path.adoc | 65 +++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 modules/shared/proc-configure-servicenow-image-path.adoc

diff --git a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
index 59e5192dfd6..6bc2754f218 100644
--- a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
+++ b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
@@ -18,6 +18,8 @@ The `ServiceNow` custom actions plugin is community-sourced.
 
 include::../modules/shared/con-servicenow-entity-linking-methods.adoc[leveloffset=+1]
 
+//include::../modules/shared/proc-configure-servicenow-plugin-configmap.adoc[leveloffset=+2]
+
 include::../modules/shared/proc-linking-servicenow-entities.adoc[leveloffset=+2] 
 
 include::../modules/shared/proc-using-servicenow-scaffolder-actions.adoc[leveloffset=+2]
diff --git a/modules/shared/proc-configure-servicenow-image-path.adoc b/modules/shared/proc-configure-servicenow-image-path.adoc
new file mode 100644
index 00000000000..360aca52f90
--- /dev/null
+++ b/modules/shared/proc-configure-servicenow-image-path.adoc
@@ -0,0 +1,65 @@
+:_mod-docs-content-type: PROCEDURE
+[id="configure-servicenow-plugin-configmap_{context}"]
+= Configure the ServiceNow plugin in the ConfigMap
+
+[role="_abstract"]
+Update the `{product}` ConfigMap to enable the ServiceNow backend, frontend, and Scaffolder actions. This configuration defines the connection parameters and UI components required to integrate ServiceNow with your software catalog.
+
+.Prerequisites
+
+* You have administrator access to an {ocp-brand-name} cluster.
+
+* {product} is installed on the cluster.
+
+.Procedure
+
+. Open your `{product}` ConfigMap for editing.
+
+. Add the ServiceNow backend and frontend plugin packages to the `dynamic-plugins.yaml` section, including the connection and UI configuration:
++
+[source,yaml]
+----
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: rhdh-plugin-config
+data:
+  dynamic-plugins.yaml: |
+    includes:
+      - dynamic-plugins.default.yaml
+    plugins:
+      - package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow-backend:bs_1.45.3__1.6.1'
+        disabled: false
+        pluginConfig:
+          servicenow:
+            instanceUrl: ${SERVICENOW_BASE_URL}
+            basicAuth:
+              username: ${SERVICENOW_USERNAME}
+              password: ${SERVICENOW_PASSWORD}
+          scaffolder:
+            servicenow:
+              baseUrl: ${SERVICENOW_BASE_URL}
+              username: ${SERVICENOW_USERNAME}
+              password: ${SERVICENOW_PASSWORD}
+      - package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow:bs_1.45.3__1.6.0'
+        disabled: false
+        pluginConfig:
+          dynamicPlugins:
+            frontend:
+              backstage-community.plugin-servicenow:
+                entityTabs:
+                  - path: /servicenow
+                    title: ServiceNow
+                    mountPoint: entity.page.servicenow
+                mountPoints:
+                  - mountPoint: entity.page.servicenow/cards
+                    importName: ServicenowPage
+                    config:
+                      layout:
+                        gridColumn: 1 / -1
+                        height: 75vh
+----
+
+. Save the changes to the ConfigMap.
+
+. Wait for the {product-very-short} Operator to redeploy the pods. The plugins are available once the pods are in a `Running` state.

From e4c2853a4bf6d044c9d90acd9a566ee4f74fa78c Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 8 May 2026 16:55:45 -0400
Subject: [PATCH 07/16] RHIDP-10933: modified procedure name and updated
 assembly

---
 .../assembly-servicenow-custom-actions-in-rhdh.adoc             | 2 +-
 ...ath.adoc => proc-configure-servicenow-plugin-configmap.adoc} | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename modules/shared/{proc-configure-servicenow-image-path.adoc => proc-configure-servicenow-plugin-configmap.adoc} (100%)

diff --git a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
index 6bc2754f218..1854dae9f2c 100644
--- a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
+++ b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
@@ -18,7 +18,7 @@ The `ServiceNow` custom actions plugin is community-sourced.
 
 include::../modules/shared/con-servicenow-entity-linking-methods.adoc[leveloffset=+1]
 
-//include::../modules/shared/proc-configure-servicenow-plugin-configmap.adoc[leveloffset=+2]
+include::../modules/shared/proc-configure-servicenow-plugin-configmap.adoc[leveloffset=+2]
 
 include::../modules/shared/proc-linking-servicenow-entities.adoc[leveloffset=+2] 
 
diff --git a/modules/shared/proc-configure-servicenow-image-path.adoc b/modules/shared/proc-configure-servicenow-plugin-configmap.adoc
similarity index 100%
rename from modules/shared/proc-configure-servicenow-image-path.adoc
rename to modules/shared/proc-configure-servicenow-plugin-configmap.adoc

From 382631fe16067f50cbe1c54c0fa29461d213375d Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 8 May 2026 17:13:56 -0400
Subject: [PATCH 08/16] RHIDP-10933: name change and tshooting

---
 .../assembly-servicenow-custom-actions-in-rhdh.adoc    | 10 +++++-----
 ...figure-the-servicenow-plugin-in-the-configmap.adoc} |  2 +-
 2 files changed, 6 insertions(+), 6 deletions(-)
 rename modules/shared/{proc-configure-servicenow-plugin-configmap.adoc => configure-the-servicenow-plugin-in-the-configmap.adoc} (97%)

diff --git a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
index 1854dae9f2c..772888d7eff 100644
--- a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
+++ b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
@@ -18,15 +18,15 @@ The `ServiceNow` custom actions plugin is community-sourced.
 
 include::../modules/shared/con-servicenow-entity-linking-methods.adoc[leveloffset=+1]
 
-include::../modules/shared/proc-configure-servicenow-plugin-configmap.adoc[leveloffset=+2]
+include::../modules/shared/modules/shared/configure-the-servicenow-plugin-in-the-configmap.adoc[leveloffset=+2]
 
-include::../modules/shared/proc-linking-servicenow-entities.adoc[leveloffset=+2] 
+//include::../modules/shared/proc-linking-servicenow-entities.adoc[leveloffset=+2] 
 
-include::../modules/shared/proc-using-servicenow-scaffolder-actions.adoc[leveloffset=+2]
+//include::../modules/shared/proc-using-servicenow-scaffolder-actions.adoc[leveloffset=+2]
 
-include::../modules/shared/ref-servicenow-configuration-parameters.adoc[leveloffset=+2]
+//include::../modules/shared/ref-servicenow-configuration-parameters.adoc[leveloffset=+2]
 
-include::../modules/shared/proc-enable-servicenow-custom-actions-plugin-in-rhdh.adoc[leveloffset=+1]
+//include::../modules/shared/proc-enable-servicenow-custom-actions-plugin-in-rhdh.adoc[leveloffset=+1]
 
 include::../modules/shared/ref-supported-servicenow-custom-actions-in-rhdh.adoc[leveloffset=+1]
 
diff --git a/modules/shared/proc-configure-servicenow-plugin-configmap.adoc b/modules/shared/configure-the-servicenow-plugin-in-the-configmap.adoc
similarity index 97%
rename from modules/shared/proc-configure-servicenow-plugin-configmap.adoc
rename to modules/shared/configure-the-servicenow-plugin-in-the-configmap.adoc
index 360aca52f90..c130a66cdb4 100644
--- a/modules/shared/proc-configure-servicenow-plugin-configmap.adoc
+++ b/modules/shared/configure-the-servicenow-plugin-in-the-configmap.adoc
@@ -1,5 +1,5 @@
 :_mod-docs-content-type: PROCEDURE
-[id="configure-servicenow-plugin-configmap_{context}"]
+[id="configure-the-servicenow-plugin-in-the-configmap_{context}"]
 = Configure the ServiceNow plugin in the ConfigMap
 
 [role="_abstract"]

From 91016f6022392ef11cdbbcde8c6bf6e67c1af868 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 8 May 2026 17:30:37 -0400
Subject: [PATCH 09/16] RHIDP-10933: tshooting

---
 .../assembly-servicenow-custom-actions-in-rhdh.adoc    | 10 +++++-----
 ...c-link-servicenow-tickets-to-catalog-entities.adoc} |  4 ++--
 ...enow-scaffolder-actions-in-software-templates.adoc} |  2 +-
 3 files changed, 8 insertions(+), 8 deletions(-)
 rename modules/shared/{proc-linking-servicenow-entities.adoc => proc-link-servicenow-tickets-to-catalog-entities.adoc} (94%)
 rename modules/shared/{proc-using-servicenow-scaffolder-actions.adoc => proc-use-servicenow-scaffolder-actions-in-software-templates.adoc} (95%)

diff --git a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
index 772888d7eff..ecc2efbeddf 100644
--- a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
+++ b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
@@ -18,15 +18,15 @@ The `ServiceNow` custom actions plugin is community-sourced.
 
 include::../modules/shared/con-servicenow-entity-linking-methods.adoc[leveloffset=+1]
 
-include::../modules/shared/modules/shared/configure-the-servicenow-plugin-in-the-configmap.adoc[leveloffset=+2]
+include::../modules/shared/configure-the-servicenow-plugin-in-the-configmap.adoc[leveloffset=+2]
 
-//include::../modules/shared/proc-linking-servicenow-entities.adoc[leveloffset=+2] 
+include::../modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc[leveloffset=+2]
 
-//include::../modules/shared/proc-using-servicenow-scaffolder-actions.adoc[leveloffset=+2]
+include::../modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc[leveloffset=+2]
 
-//include::../modules/shared/ref-servicenow-configuration-parameters.adoc[leveloffset=+2]
+include::../modules/shared/ref-servicenow-configuration-parameters.adoc[leveloffset=+2]
 
-//include::../modules/shared/proc-enable-servicenow-custom-actions-plugin-in-rhdh.adoc[leveloffset=+1]
+include::../modules/shared/proc-enable-servicenow-custom-actions-plugin-in-rhdh.adoc[leveloffset=+1]
 
 include::../modules/shared/ref-supported-servicenow-custom-actions-in-rhdh.adoc[leveloffset=+1]
 
diff --git a/modules/shared/proc-linking-servicenow-entities.adoc b/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc
similarity index 94%
rename from modules/shared/proc-linking-servicenow-entities.adoc
rename to modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc
index 980cea6040b..9ce3efe6572 100644
--- a/modules/shared/proc-linking-servicenow-entities.adoc
+++ b/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
-[id="linking-servicenow-entities_{context}"]
-= Linking ServiceNow tickets to catalog entities
+[id="link-servicenow-tickets-to-catalog-entities_{context}"]
+= Link ServiceNow tickets to catalog entities
 
 [role="_abstract"]
 The ServiceNow integration in {product} uses software catalog annotations to associate entities with ServiceNow records. By defining these identifiers, the ServiceNow plugin can retrieve and display relevant tickets and incidents directly within the component dashboard.
diff --git a/modules/shared/proc-using-servicenow-scaffolder-actions.adoc b/modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc
similarity index 95%
rename from modules/shared/proc-using-servicenow-scaffolder-actions.adoc
rename to modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc
index f3a7f2ab3a7..258318b2f77 100644
--- a/modules/shared/proc-using-servicenow-scaffolder-actions.adoc
+++ b/modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc
@@ -1,5 +1,5 @@
 :_mod-docs-content-type: PROCEDURE
-[id="using-servicenow-scaffolder-actions_{context}"]
+[id="use-servicenow-scaffolder-actions-in-software-templates_{context}"]
 = Using ServiceNow scaffolder actions in software templates
 
 [role="_abstract"]

From e49070453f1dd89133e942000383864fb38996f8 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 8 May 2026 17:43:39 -0400
Subject: [PATCH 10/16] RHIDP-10933: tshooting

---
 .../assembly-servicenow-custom-actions-in-rhdh.adoc             | 2 +-
 ... proc-configure-the-servicenow-plugin-in-the-configmap.adoc} | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename modules/shared/{configure-the-servicenow-plugin-in-the-configmap.adoc => proc-configure-the-servicenow-plugin-in-the-configmap.adoc} (100%)

diff --git a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
index ecc2efbeddf..15e122e3d49 100644
--- a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
+++ b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
@@ -18,7 +18,7 @@ The `ServiceNow` custom actions plugin is community-sourced.
 
 include::../modules/shared/con-servicenow-entity-linking-methods.adoc[leveloffset=+1]
 
-include::../modules/shared/configure-the-servicenow-plugin-in-the-configmap.adoc[leveloffset=+2]
+include::../modules/shared/proc-configure-the-servicenow-plugin-in-the-configmap.adoc[leveloffset=+2]
 
 include::../modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc[leveloffset=+2]
 
diff --git a/modules/shared/configure-the-servicenow-plugin-in-the-configmap.adoc b/modules/shared/proc-configure-the-servicenow-plugin-in-the-configmap.adoc
similarity index 100%
rename from modules/shared/configure-the-servicenow-plugin-in-the-configmap.adoc
rename to modules/shared/proc-configure-the-servicenow-plugin-in-the-configmap.adoc

From 2320888f879d25af3698238eb2a6fd33d308801a Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Fri, 8 May 2026 17:52:44 -0400
Subject: [PATCH 11/16] RHIDP-10933: fixed CQA warnings

---
 ...-servicenow-scaffolder-actions-in-software-templates.adoc | 2 +-
 modules/shared/ref-servicenow-configuration-parameters.adoc  | 5 +++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc b/modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc
index 258318b2f77..875f316b3b2 100644
--- a/modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc
+++ b/modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 [id="use-servicenow-scaffolder-actions-in-software-templates_{context}"]
-= Using ServiceNow scaffolder actions in software templates
+= Use ServiceNow scaffolder actions in software templates
 
 [role="_abstract"]
 Add ServiceNow actions to your Software Templates to automate ticket creation and record updates during the software scaffolding process. Use these actions to ensure consistent tracking and compliance throughout your development lifecycle.
diff --git a/modules/shared/ref-servicenow-configuration-parameters.adoc b/modules/shared/ref-servicenow-configuration-parameters.adoc
index e44f10af656..74fef4e3f1d 100644
--- a/modules/shared/ref-servicenow-configuration-parameters.adoc
+++ b/modules/shared/ref-servicenow-configuration-parameters.adoc
@@ -9,7 +9,8 @@ Configure the ServiceNow integration by defining instance connection parameters
 
 The following parameters apply to the core ServiceNow integration used by the UI plugin and Scaffolder actions.
 
-.ServiceNow global configuration parameters
+== ServiceNow global configuration parameters
+
 [cols="3,1,1,5", options="header"]
 |===
 | Parameter | Type | Default | Description
@@ -20,7 +21,7 @@ The following parameters apply to the core ServiceNow integration used by the UI
 | `apiToken` | String | N/A | An alternative to username/password for token-based authentication.
 |===
 
-=== OAuth 2.0 authentication
+== OAuth 2.0 authentication
 
 If your organization uses OAuth 2.0, use the following parameters instead of `username` and `password`:
 

From f8e78e975e844cff0330ba92f88235cbf7f1d7e6 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Wed, 13 May 2026 13:31:48 -0400
Subject: [PATCH 12/16] RHIDP-10933: edits from dev review

---
 ...bly-servicenow-custom-actions-in-rhdh.adoc |  2 +
 ...he-servicenow-plugin-in-the-configmap.adoc | 32 +++---
 ...ffolder-actions-in-software-templates.adoc | 60 +++++------
 ...f-servicenow-configuration-parameters.adoc | 99 +++++++++++++------
 4 files changed, 113 insertions(+), 80 deletions(-)

diff --git a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
index 15e122e3d49..4344057bf51 100644
--- a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
+++ b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
@@ -6,6 +6,8 @@ ifdef::context[:parent-context: {context}]
 :context: servicenow-custom-actions-in-rhdh
 
 [role="_abstract"]
+Integrate ServiceNow with {product} to manage ServiceNow records using Scaffolder actions and view ServiceNow data on entity pages.
+
 In {product}, you can use `ServiceNow` custom actions to fetch and register resources within the catalog.
 
 The custom actions in {product-short} help you automate the management of records. By using the custom actions, you can:
diff --git a/modules/shared/proc-configure-the-servicenow-plugin-in-the-configmap.adoc b/modules/shared/proc-configure-the-servicenow-plugin-in-the-configmap.adoc
index c130a66cdb4..b06146f6c7c 100644
--- a/modules/shared/proc-configure-the-servicenow-plugin-in-the-configmap.adoc
+++ b/modules/shared/proc-configure-the-servicenow-plugin-in-the-configmap.adoc
@@ -28,6 +28,7 @@ data:
     includes:
       - dynamic-plugins.default.yaml
     plugins:
+      # ServiceNow Backend Plugin
       - package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow-backend:bs_1.45.3__1.6.1'
         disabled: false
         pluginConfig:
@@ -36,28 +37,19 @@ data:
             basicAuth:
               username: ${SERVICENOW_USERNAME}
               password: ${SERVICENOW_PASSWORD}
-          scaffolder:
-            servicenow:
-              baseUrl: ${SERVICENOW_BASE_URL}
-              username: ${SERVICENOW_USERNAME}
-              password: ${SERVICENOW_PASSWORD}
-      - package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow:bs_1.45.3__1.6.0'
+      
+      # ServiceNow Scaffolder Module
+      - package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-scaffolder-backend-module-servicenow:bs_1.49.4__2.15.0'
         disabled: false
         pluginConfig:
-          dynamicPlugins:
-            frontend:
-              backstage-community.plugin-servicenow:
-                entityTabs:
-                  - path: /servicenow
-                    title: ServiceNow
-                    mountPoint: entity.page.servicenow
-                mountPoints:
-                  - mountPoint: entity.page.servicenow/cards
-                    importName: ServicenowPage
-                    config:
-                      layout:
-                        gridColumn: 1 / -1
-                        height: 75vh
+          servicenow:
+            baseUrl: ${SERVICENOW_BASE_URL}
+            username: ${SERVICENOW_USERNAME}
+            password: ${SERVICENOW_PASSWORD}
+
+      # ServiceNow Frontend Plugin
+      - package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow:bs_1.45.3__1.6.0'
+        disabled: false
 ----
 
 . Save the changes to the ConfigMap.
diff --git a/modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc b/modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc
index 875f316b3b2..20e9e514d7f 100644
--- a/modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc
+++ b/modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc
@@ -3,44 +3,48 @@
 = Use ServiceNow scaffolder actions in software templates
 
 [role="_abstract"]
-Add ServiceNow actions to your Software Templates to automate ticket creation and record updates during the software scaffolding process. Use these actions to ensure consistent tracking and compliance throughout your development lifecycle.
+Add ServiceNow actions to your software templates to automate the creation, retrieval, and modification of ServiceNow records during the software scaffolding process.
 
 .Prerequisites
-* You have configured the ServiceNow instance parameters in the `scaffolder.notifications.servicenow` section of your `app-config.yaml` file.
+
+* You have configured the ServiceNow instance parameters in the {product}ConfigMap or app-config.yaml file.
 * You have the required permissions to edit Software Templates in the source repository.
 * You have registered the Software Template in the {product} catalog.
 
 .Procedure
 
-. Open your Software Template YAML file. For example, `template.yaml`.
+. Open your software template YAML file.
+
+. In the `spec.steps` section, add the ServiceNow action that corresponds to your goal.
 
-. Add the `servicenow:create-incident` action to the `spec.steps` block.
+. Define the `tableName` and the `requestBody` containing the fields to populate or modify. The following example demonstrates how to use the `servicenow:now:table:createRecord` action to generate an incident ticket:
 +
-...
 [source,yaml]
 ----
-spec:
-  steps:
-    - id: create-incident
-      name: Create ServiceNow Incident
-      action: servicenow:create-incident
-      input:
-        instanceName: 'production' # <1>
-        short_description: 'Incident created from RHDH Software Template'
+steps:
+  - id: create-incident
+    name: Create ServiceNow Incident
+    action: servicenow:now:table:createRecord
+    input:
+      tableName: incident
+      requestBody:
+        short_description: "New project scaffolded"
+        description: "A new software component was created via the Developer Hub."
+        severity: "3"
 ----
-+
-spec.steps.action:: Specifies the `servicenow:create-incident` identifier to trigger the ServiceNow integration.
-spec.steps.input.instanceName:: Specifies the name of the ServiceNow instance defined in your `app-config.yaml` file.
-
-. Save the changes and push them to your Git repository.
-
 
-.Verification
-
-. In {product}, navigate to the *Create* menu and select your template.
-
-. Fill out the required fields and click *Next Step* until the dry-run or execution begins.
-
-. After the task completes, log in to your ServiceNow instance.
-
-. Confirm that the new incident appears with the description provided in the template.
+. Optional: To perform other operations, use the appropriate action ID and parameters:
++
+|===
+| Goal | Action ID | Key Input Parameters
+
+| **Delete a record** | `servicenow:now:table:deleteRecord` | `tableName`, `sysId`
+| **Modify a record** | `servicenow:now:table:modifyRecord` | `tableName`, `sysId`, `requestBody`
+| **Retrieve a record** | `servicenow:now:table:retrieveRecord` | `tableName`, `sysId`
+| **Update a record** | `servicenow:now:table:updateRecord` | `tableName`, `sysId`, `requestBody`
+|===
+
+[TIP]
+====
+To view the full schema and all available ServiceNow actions for your specific installation, navigate to **Create** > **Installed Actions** in the {product} interface.
+====
diff --git a/modules/shared/ref-servicenow-configuration-parameters.adoc b/modules/shared/ref-servicenow-configuration-parameters.adoc
index 74fef4e3f1d..01a20afa02f 100644
--- a/modules/shared/ref-servicenow-configuration-parameters.adoc
+++ b/modules/shared/ref-servicenow-configuration-parameters.adoc
@@ -3,52 +3,87 @@
 = ServiceNow configuration parameters
 
 [role="_abstract"]
-Configure the ServiceNow integration by defining instance connection parameters in the app-config.yaml file. This reference provides the required configuration blocks and syntax for both the ServiceNow UI plugin and Scaffolder actions.
+The ServiceNow integration requires specific parameters in your configuration files to establish a connection between {product} and your ServiceNow instances. Use these parameters to define authentication methods, instance URLs, and UI layouts.
 
-== ServiceNow backend configuration
+== ServiceNow backend and frontend configuration
+Define the following parameters in the `app-config.yaml` file or the `dynamic-plugins.yaml` section of the `{product}` ConfigMap to enable the backend and frontend plugins.
 
-The following parameters apply to the core ServiceNow integration used by the UI plugin and Scaffolder actions.
-
-== ServiceNow global configuration parameters
-
-[cols="3,1,1,5", options="header"]
 |===
-| Parameter | Type | Default | Description
+| Parameter | Description | Requirement
 
-| `baseUrl` | String | N/A | Required. The base URL of your ServiceNow instance (for example, `https://instance.service-now.com`).
-| `username` | String | N/A | The username for Basic Authentication. Required if not using OAuth.
-| `password` | String | N/A | The password for Basic Authentication. Required if not using OAuth.
-| `apiToken` | String | N/A | An alternative to username/password for token-based authentication.
+| `instanceUrl` | The base URL of your ServiceNow instance (e.g., `https://dev12345.service-now.com`). | Required
+| `basicAuth.username` | The service account username for Basic authentication. | Optional
+| `basicAuth.password` | The service account password for Basic authentication. | Optional
+| `oauth.grantType` | The OAuth 2.0 grant type. Supports `client_credentials` or `password`. | Optional
+| `oauth.clientId` | The client ID for OAuth authentication. | Optional
+| `oauth.clientSecret` | The client secret for OAuth authentication. | Optional
 |===
 
-== OAuth 2.0 authentication
+== ServiceNow scaffolder configuration
+The ServiceNow Scaffolder module requires a separate configuration block. Note that this module uses `baseUrl` instead of `instanceUrl`.
 
-If your organization uses OAuth 2.0, use the following parameters instead of `username` and `password`:
+|===
+| Parameter | Description | Requirement
 
-* `oauthClientId`: The Client ID from your ServiceNow OAuth application.
-* `oauthClientSecret`: The Client Secret from your ServiceNow OAuth application.
-* `oauthTokenUrl`: The URL used to retrieve the access token.
+| `baseUrl` | The base URL of your ServiceNow instance. | Required
+| `username` | The service account username. | Required for Basic Auth
+| `password` | The service account password. | Required for Basic Auth
+|===
 
-== Scaffolder actions configuration
+== Authentication examples
+The following examples demonstrate how to structure different authentication methods in your configuration.
 
-To use ServiceNow actions in software templates, define your instances under the `scaffolder.notifications.servicenow` block.
+.Basic authentication example
+[source,yaml]
+----
+servicenow:
+  instanceUrl: ${SERVICENOW_INSTANCE_URL}
+  basicAuth:
+    username: ${SERVICENOW_USER}
+    password: ${SERVICENOW_PASS}
+----
 
+.OAuth with Client Credentials
 [source,yaml]
 ----
-scaffolder:
-  notifications:
-    servicenow:
-      production:
-        baseUrl: ${SERVICENOW_PROD_URL}
-        username: ${SERVICENOW_USER}
-        password: ${SERVICENOW_PASS}
+servicenow:
+  instanceUrl: ${SERVICENOW_INSTANCE_URL}
+  oauth:
+    grantType: client_credentials
+    clientId: ${SERVICENOW_CLIENT_ID}
+    clientSecret: ${SERVICENOW_CLIENT_SECRET}
 ----
-+
-scaffolder.notifications.servicenow.<instance_name>:: Defines a unique key for a ServiceNow instance used by the Scaffolder.
 
-== Catalog annotations
+.OAuth with Password Grant
+[source,yaml]
+----
+servicenow:
+  instanceUrl: ${SERVICENOW_INSTANCE_URL}
+  oauth:
+    grantType: password
+    clientId: ${SERVICENOW_CLIENT_ID}
+    clientSecret: ${SERVICENOW_CLIENT_SECRET}
+    username: ${SERVICENOW_USER}
+    password: ${SERVICENOW_PASS}
+----
 
-The ServiceNow plugin does not use `app-config.yaml` for entity mapping or filtering. To link catalog entities to ServiceNow, use the following annotations in the `catalog-info.yaml` file:
+== Frontend UI configuration
+The frontend plugin configuration defines how ServiceNow data appears on component entity pages.
 
-* `servicenow.com/service-id`: Maps the entity to a specific ServiceNow Service ID.
-* `servicenow.com/category:` Filters incidents by a specific ServiceNow category.
+[source,yaml]
+----
+dynamicPlugins:
+  frontend:
+    backstage-community.plugin-servicenow:
+      entityTabs:
+        - path: /servicenow
+          title: ServiceNow
+          mountPoint: entity.page.servicenow
+      mountPoints:
+        - mountPoint: entity.page.servicenow/cards
+          importName: ServicenowPage
+          config:
+            layout:
+              gridColumn: 1 / -1
+              height: 75vh
+----
\ No newline at end of file

From e0efe7606383494c7275cf513a0cd47e4c7c831a Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Wed, 13 May 2026 13:39:12 -0400
Subject: [PATCH 13/16] RHIDP-10933: updated section headers

---
 modules/shared/ref-servicenow-configuration-parameters.adoc | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/modules/shared/ref-servicenow-configuration-parameters.adoc b/modules/shared/ref-servicenow-configuration-parameters.adoc
index 01a20afa02f..b04c26df534 100644
--- a/modules/shared/ref-servicenow-configuration-parameters.adoc
+++ b/modules/shared/ref-servicenow-configuration-parameters.adoc
@@ -33,7 +33,7 @@ The ServiceNow Scaffolder module requires a separate configuration block. Note t
 == Authentication examples
 The following examples demonstrate how to structure different authentication methods in your configuration.
 
-.Basic authentication example
+== Basic authentication example
 [source,yaml]
 ----
 servicenow:
@@ -43,7 +43,7 @@ servicenow:
     password: ${SERVICENOW_PASS}
 ----
 
-.OAuth with Client Credentials
+== OAuth with Client Credentials
 [source,yaml]
 ----
 servicenow:
@@ -54,7 +54,7 @@ servicenow:
     clientSecret: ${SERVICENOW_CLIENT_SECRET}
 ----
 
-.OAuth with Password Grant
+== OAuth with Password Grant
 [source,yaml]
 ----
 servicenow:

From 824ee8b1d20aa6f9e3372ac03521bc52c1e6e07f Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Tue, 19 May 2026 14:52:44 -0400
Subject: [PATCH 14/16] RHIDP-10933: updated based on dev comment

---
 .../proc-link-servicenow-tickets-to-catalog-entities.adoc | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc b/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc
index 9ce3efe6572..667a64ab659 100644
--- a/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc
+++ b/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc
@@ -24,8 +24,10 @@ metadata:
   annotations:
     servicenow.com/service-id: <your-service-id>
 ----
-+
-metadata.annotations.servicenow.com/service-id:: Specifies the service identifier from your ServiceNow instance.   
+
+`metadata.annotations.servicenow.com/service-id`:: Defines the custom annotation prefix that matches your `metadata.annotations` keys, which determines whether the portal workspace displays a *ServiceNow* tab for that catalog entity.
+
+`servicenow.com/service-id`:: Specifies the unique identifier of the target item in your ServiceNow instance that links this catalog entity to its corresponding ServiceNow record.
 
 . Optional: If your organization uses different categories to filter tickets, you can also add the category annotation:
 +
@@ -35,7 +37,7 @@ metadata:
   annotations:
     servicenow.com/category: "software"
 ----
-+
+
 metadata.annotations.servicenow.com/category:: Specifies the ServiceNow category used to filter the displayed incidents.
 
 . Save the changes to `catalog-info.yaml` and commit them to your repository.

From b48cb68f39f319e2102c1208deaeccbb50d6fefb Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Tue, 19 May 2026 15:09:34 -0400
Subject: [PATCH 15/16] RHIDP-10933: updated short description to address CQA
 item flagged

---
 .../assembly-servicenow-custom-actions-in-rhdh.adoc             | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
index 4344057bf51..3ea980c796b 100644
--- a/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
+++ b/assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc
@@ -6,7 +6,7 @@ ifdef::context[:parent-context: {context}]
 :context: servicenow-custom-actions-in-rhdh
 
 [role="_abstract"]
-Integrate ServiceNow with {product} to manage ServiceNow records using Scaffolder actions and view ServiceNow data on entity pages.
+Integrate ServiceNow with {product} to manage ServiceNow records by using Scaffolder actions and view ServiceNow data on entity pages.
 
 In {product}, you can use `ServiceNow` custom actions to fetch and register resources within the catalog.
 

From 4f690a88196cf3152f5fe26dd31456d96efb1412 Mon Sep 17 00:00:00 2001
From: Tim O'Keefe <tokeefe@redhat.com>
Date: Wed, 20 May 2026 12:04:34 -0400
Subject: [PATCH 16/16] RHIDP-10933: minor edit

---
 .../proc-link-servicenow-tickets-to-catalog-entities.adoc    | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc b/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc
index 667a64ab659..85be0a47670 100644
--- a/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc
+++ b/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc
@@ -25,9 +25,8 @@ metadata:
     servicenow.com/service-id: <your-service-id>
 ----
 
-`metadata.annotations.servicenow.com/service-id`:: Defines the custom annotation prefix that matches your `metadata.annotations` keys, which determines whether the portal workspace displays a *ServiceNow* tab for that catalog entity.
-
-`servicenow.com/service-id`:: Specifies the unique identifier of the target item in your ServiceNow instance that links this catalog entity to its corresponding ServiceNow record.
+`servicenow.com/<field-name>`::
+  Annotation pattern for linking to ServiceNow records. Replace `<field-name>` with any ServiceNow table column name (such as `service-id`, `category`, `company`). The `servicenow.com/` prefix enables the ServiceNow tab. You can add multiple annotations to filter by different fields.
 
 . Optional: If your organization uses different categories to filter tickets, you can also add the category annotation:
 +