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

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 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.
 
 The custom actions in {product-short} help you automate the management of records. By using the custom actions, you can:
@@ -15,6 +17,17 @@ 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-the-servicenow-plugin-in-the-configmap.adoc[leveloffset=+2]
+
+include::../modules/shared/proc-link-servicenow-tickets-to-catalog-entities.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/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,41 @@
+:_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.
+
+* 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 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.
+
+* 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
+
+| 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-the-servicenow-plugin-in-the-configmap.adoc

@@ -0,0 +1,57 @@
+:_mod-docs-content-type: PROCEDURE
+[id="configure-the-servicenow-plugin-in-the-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:
+      # 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:
+          servicenow:
+            instanceUrl: ${SERVICENOW_BASE_URL}
+            basicAuth:
+              username: ${SERVICENOW_USERNAME}
+              password: ${SERVICENOW_PASSWORD}
+
+      # 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:
+          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.
+
+. Wait for the {product-very-short} Operator to redeploy the pods. The plugins are available once the pods are in a `Running` state.

modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc

@@ -0,0 +1,54 @@
+:_mod-docs-content-type: PROCEDURE
+[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.
+
+.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>
+----
+
+`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:
++
+[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.

modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc

@@ -0,0 +1,50 @@
+:_mod-docs-content-type: PROCEDURE
+[id="use-servicenow-scaffolder-actions-in-software-templates_{context}"]
+= Use ServiceNow scaffolder actions in software templates
+
+[role="_abstract"]
+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 {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.
+
+. In the `spec.steps` section, add the ServiceNow action that corresponds to your goal.
+
+. 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]
+----
+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"
+----
+
+. 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.
+====

modules/shared/ref-servicenow-configuration-parameters.adoc

@@ -0,0 +1,89 @@
+:_mod-docs-content-type: REFERENCE
+[id="servicenow-configuration-parameters_{context}"]
+= ServiceNow configuration parameters
+
+[role="_abstract"]
+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 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.
+
+|===
+| Parameter | Description | Requirement
+
+| `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
+|===
+
+== ServiceNow scaffolder configuration
+The ServiceNow Scaffolder module requires a separate configuration block. Note that this module uses `baseUrl` instead of `instanceUrl`.
+
+|===
+| Parameter | Description | Requirement
+
+| `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
+|===
+
+== Authentication examples
+The following examples demonstrate how to structure different authentication methods in your configuration.
+
+== Basic authentication example
+[source,yaml]
+----
+servicenow:
+  instanceUrl: ${SERVICENOW_INSTANCE_URL}
+  basicAuth:
+    username: ${SERVICENOW_USER}
+    password: ${SERVICENOW_PASS}
+----
+
+== OAuth with Client Credentials
+[source,yaml]
+----
+servicenow:
+  instanceUrl: ${SERVICENOW_INSTANCE_URL}
+  oauth:
+    grantType: client_credentials
+    clientId: ${SERVICENOW_CLIENT_ID}
+    clientSecret: ${SERVICENOW_CLIENT_SECRET}
+----
+
+== 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}
+----
+
+== Frontend UI configuration
+The frontend plugin configuration defines how ServiceNow data appears on component entity pages.
+
+[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
+----