Skip to content

Commit 942fb83

Browse files
openshift-cherrypick-robotrh-tokeefe
openshift-cherrypick-robot
and
rh-tokeefe
authored
[release-1.10] RHIDP-10933: [Doc] ServiceNow plugin: Allow integration without changing ServiceNow infrastructure (#2318)
* RHIDP-10933: [Doc] ServiceNow plugin: Allow integration without changing ServiceNow infrastructure * RHIDP-10933: edits from AI review * RHIDP-10933: revised for style using AI * RHIDP-10933: Updated based on dev review * RHIDP-10933: updated task for using servicenow scaffolder actions * RHIDP-10933: added task after discussion with developer * RHIDP-10933: modified procedure name and updated assembly * RHIDP-10933: name change and tshooting * RHIDP-10933: tshooting * RHIDP-10933: tshooting * RHIDP-10933: fixed CQA warnings * RHIDP-10933: edits from dev review * RHIDP-10933: updated section headers * RHIDP-10933: updated based on dev comment * RHIDP-10933: updated short description to address CQA item flagged * RHIDP-10933: minor edit * RHIDP-10933: update from peer review * RHIDP-10933: edits from dev review --------- Co-authored-by: Tim O'Keefe <tokeefe@redhat.com>
1 parent 3d182c2 commit 942fb83

6 files changed

Lines changed: 309 additions & 0 deletions

‎assemblies/extend_configuring-dynamic-plugins/assembly-servicenow-custom-actions-in-rhdh.adoc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ ifdef::context[:parent-context: {context}]
66
:context: servicenow-custom-actions-in-rhdh
77

88
[role="_abstract"]
9+
Integrate ServiceNow with {product} to manage ServiceNow records by using Scaffolder actions and view ServiceNow data on entity pages.
10+
911
In {product}, you can use `ServiceNow` custom actions to fetch and register resources within the catalog.
1012

1113
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
1517

1618
The `ServiceNow` custom actions plugin is community-sourced.
1719

20+
21+
include::../modules/shared/con-servicenow-entity-linking-methods.adoc[leveloffset=+1]
22+
23+
include::../modules/shared/proc-configure-the-servicenow-plugin-in-the-configmap.adoc[leveloffset=+2]
24+
25+
include::../modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc[leveloffset=+2]
26+
27+
include::../modules/shared/proc-use-servicenow-scaffolder-actions-in-software-templates.adoc[leveloffset=+2]
28+
29+
include::../modules/shared/ref-servicenow-configuration-parameters.adoc[leveloffset=+2]
30+
1831
include::../modules/shared/proc-enable-servicenow-custom-actions-plugin-in-rhdh.adoc[leveloffset=+1]
1932

2033
include::../modules/shared/ref-supported-servicenow-custom-actions-in-rhdh.adoc[leveloffset=+1]

‎modules/shared/con-servicenow-entity-linking-methods.adoc‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
:_mod-docs-content-type: CONCEPT
2+
[id="servicenow-entity-linking-methods_{context}"]
3+
= ServiceNow entity linking methods
4+
5+
[role="_abstract"]
6+
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.
7+
8+
{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.
9+
10+
== Direct mapping (Backstage Entity ID column)
11+
12+
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.
13+
14+
* Advantages:
15+
** Highly secure and precise
16+
** Ensures data is only exposed to the intended entity
17+
* Limitations:
18+
** Requires a schema change in ServiceNow
19+
** Requires manual data entry for each incident
20+
21+
== Flexible mapping (Custom column mapping)
22+
23+
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.
24+
25+
* Advantages:
26+
** Does not require ServiceNow schema changes
27+
** Faster to implement for organizations with strict ServiceNow governance
28+
* Limitations:
29+
** Requires careful configuration to ensure that the search criteria in the chosen column are unique enough to prevent displaying unrelated incidents
30+
31+
== Comparison of linking methods
32+
33+
[cols="1h,1,1"]
34+
|===
35+
| Feature | Direct mapping | Flexible mapping
36+
37+
| ServiceNow schema change | Required | Not required
38+
| Security level | High (strict matching) | Medium (dependent on column data)
39+
| Configuration complexity | Low (plugin side) | Medium (requires YAML mapping)
40+
| Ideal use case | New ServiceNow instances or high-security environments | Existing ServiceNow instances where schema changes are restricted
41+
|===

‎modules/shared/proc-configure-the-servicenow-plugin-in-the-configmap.adoc‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="configure-the-servicenow-plugin-in-the-configmap_{context}"]
3+
= Configure the ServiceNow plugin in the ConfigMap
4+
5+
[role="_abstract"]
6+
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.
7+
8+
.Prerequisites
9+
10+
* You have provisioned a custom configuration by following the steps in link:https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/release-1.10/configure_configuring-rhdh/#provision-your-custom-rhdh-configuration_provision-and-use-your-custom-rhdh-configuration[Provisioning and using your custom {product-short} configuration], including the section on authoring a custom `dynamic-plugins.yaml` file.
11+
12+
* You have administrator access to an {ocp-brand-name} cluster.
13+
14+
* {product} is installed on the cluster.
15+
16+
.Procedure
17+
18+
. Open your `{product}` ConfigMap for editing.
19+
20+
. Add the ServiceNow backend and frontend plugin packages to the `dynamic-plugins.yaml` section, including the connection and UI configuration:
21+
+
22+
[source,yaml]
23+
----
24+
kind: ConfigMap
25+
apiVersion: v1
26+
metadata:
27+
name: rhdh-plugin-config
28+
data:
29+
dynamic-plugins.yaml: |
30+
includes:
31+
- dynamic-plugins.default.yaml
32+
plugins:
33+
# -----------------------------------------------------------------
34+
# ... Your pre-existing custom dynamic plugins would be listed here
35+
# -----------------------------------------------------------------
36+
37+
# ServiceNow Backend Plugin
38+
- package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow-backend:bs_1.45.3__1.6.1'
39+
disabled: false
40+
pluginConfig:
41+
servicenow:
42+
instanceUrl: ${SERVICENOW_BASE_URL}
43+
basicAuth:
44+
username: ${SERVICENOW_USERNAME}
45+
password: ${SERVICENOW_PASSWORD}
46+
47+
# ServiceNow Scaffolder Module / Actions
48+
- package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-scaffolder-backend-module-servicenow:bs_1.49.4__2.15.0'
49+
disabled: false
50+
pluginConfig:
51+
servicenow:
52+
baseUrl: ${SERVICENOW_BASE_URL}
53+
username: ${SERVICENOW_USERNAME}
54+
password: ${SERVICENOW_PASSWORD}
55+
56+
# ServiceNow Frontend Plugin
57+
- package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow:bs_1.45.3__1.6.0'
58+
disabled: false
59+
----
60+
61+
. Save the changes to the ConfigMap.
62+
63+
. 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‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="link-servicenow-tickets-to-catalog-entities_{context}"]
3+
= Link ServiceNow tickets to catalog entities
4+
5+
[role="_abstract"]
6+
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.
7+
8+
.Prerequisites
9+
* The ServiceNow plugin is installed and configured in your {product} instance.
10+
* You have the unique identifier (such as a Service ID or Category) for the ServiceNow resource you want to link.
11+
12+
.Procedure
13+
14+
. Open the `catalog-info.yaml` file of the component you want to link to ServiceNow.
15+
16+
. Add the `servicenow.com/service-id` annotation to the `metadata.annotations` section.
17+
+
18+
[source,yaml]
19+
----
20+
apiVersion: backstage.io/v1alpha1
21+
kind: Component
22+
metadata:
23+
name: example-component
24+
annotations:
25+
servicenow.com/service-id: <your-service-id>
26+
----
27+
28+
`servicenow.com/<field-name>`::
29+
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.
30+
31+
. Optional: If your organization uses different categories to filter tickets, you can also add the category annotation:
32+
+
33+
[source,yaml]
34+
----
35+
metadata:
36+
annotations:
37+
servicenow.com/category: "software"
38+
----
39+
40+
metadata.annotations.servicenow.com/category:: Specifies the ServiceNow category used to filter the displayed incidents.
41+
42+
. Save the changes to `catalog-info.yaml` and commit them to your repository.
43+
44+
. If the changes do not appear automatically, manually refresh the entity in the {product} catalog.
45+
46+
.Verification
47+
48+
. Log in to your {product} and navigate to the *Catalog*.
49+
50+
. Select the component you updated.
51+
52+
. Select the *ServiceNow* tab.
53+
54+
. 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‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="use-servicenow-scaffolder-actions-in-software-templates_{context}"]
3+
= Use ServiceNow scaffolder actions in software templates
4+
5+
[role="_abstract"]
6+
Add ServiceNow actions to your software templates to automate the creation, retrieval, and modification of ServiceNow records during the software scaffolding process.
7+
8+
.Prerequisites
9+
10+
* You have configured the ServiceNow instance parameters in the {product}ConfigMap or app-config.yaml file.
11+
* You have the required permissions to edit Software Templates in the source repository.
12+
* You have registered the Software Template in the {product} catalog.
13+
14+
.Procedure
15+
16+
. Open your software template YAML file.
17+
18+
. In the `spec.steps` section, add the ServiceNow action that corresponds to your goal.
19+
20+
. 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:
21+
+
22+
[source,yaml]
23+
----
24+
steps:
25+
- id: create-incident
26+
name: Create ServiceNow Incident
27+
action: servicenow:now:table:createRecord
28+
input:
29+
tableName: incident
30+
requestBody:
31+
short_description: "Printer is offline"
32+
description: "The office printer is not accessible via the network"
33+
severity: "3"
34+
----
35+
36+
. Optional: To perform other operations, use the appropriate action ID and parameters:
37+
+
38+
|===
39+
| Goal | Action ID | Key Input Parameters
40+
41+
| **Delete a record** | `servicenow:now:table:deleteRecord` | `tableName`, `sysId`
42+
| **Modify a record** | `servicenow:now:table:modifyRecord` | `tableName`, `sysId`, `requestBody`
43+
| **Retrieve a record** | `servicenow:now:table:retrieveRecord` | `tableName`, `sysId`
44+
| **Update a record** | `servicenow:now:table:updateRecord` | `tableName`, `sysId`, `requestBody`
45+
|===
46+
47+
[TIP]
48+
====
49+
To view the full schema and all available ServiceNow actions for your specific installation, navigate to **Create** > **Installed Actions** in the {product} interface.
50+
====

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
:_mod-docs-content-type: REFERENCE
2+
[id="servicenow-configuration-parameters_{context}"]
3+
= ServiceNow configuration parameters
4+
5+
[role="_abstract"]
6+
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.
7+
8+
== ServiceNow backend and frontend configuration
9+
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.
10+
11+
|===
12+
| Parameter | Description | Requirement
13+
14+
| `instanceUrl` | String | N/A | The base URL of your ServiceNow instance (e.g., `https://dev12345.service-now.com`). | Required
15+
| `basicAuth.username` | The service account username for Basic authentication. | Optional
16+
| `basicAuth.password` | The service account password for Basic authentication. | Optional
17+
| `oauth.grantType` | The OAuth 2.0 grant type. Supports `client_credentials` or `password`. | Optional
18+
| `oauth.clientId` | The client ID for OAuth authentication. | Optional
19+
| `oauth.clientSecret` | The client secret for OAuth authentication. | Optional
20+
|===
21+
22+
== ServiceNow scaffolder configuration
23+
The ServiceNow Scaffolder module requires a separate configuration block. Note that this module uses `baseUrl` instead of `instanceUrl`.
24+
25+
|===
26+
| Parameter | Description | Requirement
27+
28+
| `baseUrl` | The base URL of your ServiceNow instance. | Required
29+
| `username` | The service account username. | Required for Basic Auth
30+
| `password` | The service account password. | Required for Basic Auth
31+
|===
32+
33+
== Authentication examples
34+
The following examples demonstrate how to structure different authentication methods in your configuration.
35+
36+
== Basic authentication example
37+
[source,yaml]
38+
----
39+
servicenow:
40+
baseUrl: ${SERVICENOW_PROD_URL}
41+
username: ${SERVICENOW_USER}
42+
password: ${SERVICENOW_PASS}
43+
----
44+
45+
== OAuth with Client Credentials
46+
[source,yaml]
47+
----
48+
servicenow:
49+
instanceUrl: ${SERVICENOW_INSTANCE_URL}
50+
oauth:
51+
grantType: client_credentials
52+
clientId: ${SERVICENOW_CLIENT_ID}
53+
clientSecret: ${SERVICENOW_CLIENT_SECRET}
54+
----
55+
56+
== OAuth with Password Grant
57+
[source,yaml]
58+
----
59+
servicenow:
60+
instanceUrl: ${SERVICENOW_INSTANCE_URL}
61+
oauth:
62+
grantType: password
63+
clientId: ${SERVICENOW_CLIENT_ID}
64+
clientSecret: ${SERVICENOW_CLIENT_SECRET}
65+
username: ${SERVICENOW_USER}
66+
password: ${SERVICENOW_PASS}
67+
----
68+
69+
== Frontend UI configuration
70+
The frontend plugin configuration defines how ServiceNow data appears on component entity pages.
71+
72+
[source,yaml]
73+
----
74+
dynamicPlugins:
75+
frontend:
76+
backstage-community.plugin-servicenow:
77+
entityTabs:
78+
- path: /servicenow
79+
title: ServiceNow
80+
mountPoint: entity.page.servicenow
81+
mountPoints:
82+
- mountPoint: entity.page.servicenow/cards
83+
importName: ServicenowPage
84+
config:
85+
layout:
86+
gridColumn: 1 / -1
87+
height: 75vh
88+
----

0 commit comments

Comments
 (0)