RHIDP-10933: [Doc] ServiceNow plugin: Allow integration without changing ServiceNow infrastructure

Author: rh-tokeefe

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]

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.
+|===

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.

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.

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.