Skip to content

Commit ac50c6d

Browse files
rh-tokeeferh-tokeefe
committed
RHIDP-10933: edits from dev review
1 parent 425cb26 commit ac50c6d

4 files changed

Lines changed: 113 additions & 80 deletions

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

Lines changed: 2 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 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:

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

Lines changed: 12 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ data:
2828
includes:
2929
- dynamic-plugins.default.yaml
3030
plugins:
31+
# ServiceNow Backend Plugin
3132
- package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow-backend:bs_1.45.3__1.6.1'
3233
disabled: false
3334
pluginConfig:
@@ -36,28 +37,19 @@ data:
3637
basicAuth:
3738
username: ${SERVICENOW_USERNAME}
3839
password: ${SERVICENOW_PASSWORD}
39-
scaffolder:
40-
servicenow:
41-
baseUrl: ${SERVICENOW_BASE_URL}
42-
username: ${SERVICENOW_USERNAME}
43-
password: ${SERVICENOW_PASSWORD}
44-
- package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow:bs_1.45.3__1.6.0'
40+
41+
# ServiceNow Scaffolder Module
42+
- package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-scaffolder-backend-module-servicenow:bs_1.49.4__2.15.0'
4543
disabled: false
4644
pluginConfig:
47-
dynamicPlugins:
48-
frontend:
49-
backstage-community.plugin-servicenow:
50-
entityTabs:
51-
- path: /servicenow
52-
title: ServiceNow
53-
mountPoint: entity.page.servicenow
54-
mountPoints:
55-
- mountPoint: entity.page.servicenow/cards
56-
importName: ServicenowPage
57-
config:
58-
layout:
59-
gridColumn: 1 / -1
60-
height: 75vh
45+
servicenow:
46+
baseUrl: ${SERVICENOW_BASE_URL}
47+
username: ${SERVICENOW_USERNAME}
48+
password: ${SERVICENOW_PASSWORD}
49+
50+
# ServiceNow Frontend Plugin
51+
- package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow:bs_1.45.3__1.6.0'
52+
disabled: false
6153
----
6254
6355
. Save the changes to the ConfigMap.

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

Lines changed: 32 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -3,44 +3,48 @@
33
= Use ServiceNow scaffolder actions in software templates
44

55
[role="_abstract"]
6-
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.
6+
Add ServiceNow actions to your software templates to automate the creation, retrieval, and modification of ServiceNow records during the software scaffolding process.
77

88
.Prerequisites
9-
* You have configured the ServiceNow instance parameters in the `scaffolder.notifications.servicenow` section of your `app-config.yaml` file.
9+
10+
* You have configured the ServiceNow instance parameters in the {product}ConfigMap or app-config.yaml file.
1011
* You have the required permissions to edit Software Templates in the source repository.
1112
* You have registered the Software Template in the {product} catalog.
1213
1314
.Procedure
1415

15-
. Open your Software Template YAML file. For example, `template.yaml`.
16+
. Open your software template YAML file.
17+
18+
. In the `spec.steps` section, add the ServiceNow action that corresponds to your goal.
1619

17-
. Add the `servicenow:create-incident` action to the `spec.steps` block.
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:
1821
+
19-
...
2022
[source,yaml]
2123
----
22-
spec:
23-
steps:
24-
- id: create-incident
25-
name: Create ServiceNow Incident
26-
action: servicenow:create-incident
27-
input:
28-
instanceName: 'production' # <1>
29-
short_description: 'Incident created from RHDH Software Template'
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: "New project scaffolded"
32+
description: "A new software component was created via the Developer Hub."
33+
severity: "3"
3034
----
31-
+
32-
spec.steps.action:: Specifies the `servicenow:create-incident` identifier to trigger the ServiceNow integration.
33-
spec.steps.input.instanceName:: Specifies the name of the ServiceNow instance defined in your `app-config.yaml` file.
34-
35-
. Save the changes and push them to your Git repository.
36-
3735

38-
.Verification
39-
40-
. In {product}, navigate to the *Create* menu and select your template.
41-
42-
. Fill out the required fields and click *Next Step* until the dry-run or execution begins.
43-
44-
. After the task completes, log in to your ServiceNow instance.
45-
46-
. Confirm that the new incident appears with the description provided in the template.
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: 67 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -3,52 +3,87 @@
33
= ServiceNow configuration parameters
44

55
[role="_abstract"]
6-
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.
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.
77

8-
== ServiceNow backend configuration
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.
910

10-
The following parameters apply to the core ServiceNow integration used by the UI plugin and Scaffolder actions.
11-
12-
== ServiceNow global configuration parameters
13-
14-
[cols="3,1,1,5", options="header"]
1511
|===
16-
| Parameter | Type | Default | Description
12+
| Parameter | Description | Requirement
1713

18-
| `baseUrl` | String | N/A | Required. The base URL of your ServiceNow instance (for example, `https://instance.service-now.com`).
19-
| `username` | String | N/A | The username for Basic Authentication. Required if not using OAuth.
20-
| `password` | String | N/A | The password for Basic Authentication. Required if not using OAuth.
21-
| `apiToken` | String | N/A | An alternative to username/password for token-based authentication.
14+
| `instanceUrl` | 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
2220
|===
2321

24-
== OAuth 2.0 authentication
22+
== ServiceNow scaffolder configuration
23+
The ServiceNow Scaffolder module requires a separate configuration block. Note that this module uses `baseUrl` instead of `instanceUrl`.
2524

26-
If your organization uses OAuth 2.0, use the following parameters instead of `username` and `password`:
25+
|===
26+
| Parameter | Description | Requirement
2727

28-
* `oauthClientId`: The Client ID from your ServiceNow OAuth application.
29-
* `oauthClientSecret`: The Client Secret from your ServiceNow OAuth application.
30-
* `oauthTokenUrl`: The URL used to retrieve the access token.
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+
|===
3132

32-
== Scaffolder actions configuration
33+
== Authentication examples
34+
The following examples demonstrate how to structure different authentication methods in your configuration.
3335

34-
To use ServiceNow actions in software templates, define your instances under the `scaffolder.notifications.servicenow` block.
36+
.Basic authentication example
37+
[source,yaml]
38+
----
39+
servicenow:
40+
instanceUrl: ${SERVICENOW_INSTANCE_URL}
41+
basicAuth:
42+
username: ${SERVICENOW_USER}
43+
password: ${SERVICENOW_PASS}
44+
----
3545

46+
.OAuth with Client Credentials
3647
[source,yaml]
3748
----
38-
scaffolder:
39-
notifications:
40-
servicenow:
41-
production:
42-
baseUrl: ${SERVICENOW_PROD_URL}
43-
username: ${SERVICENOW_USER}
44-
password: ${SERVICENOW_PASS}
49+
servicenow:
50+
instanceUrl: ${SERVICENOW_INSTANCE_URL}
51+
oauth:
52+
grantType: client_credentials
53+
clientId: ${SERVICENOW_CLIENT_ID}
54+
clientSecret: ${SERVICENOW_CLIENT_SECRET}
4555
----
46-
+
47-
scaffolder.notifications.servicenow.<instance_name>:: Defines a unique key for a ServiceNow instance used by the Scaffolder.
4856

49-
== Catalog annotations
57+
.OAuth with Password Grant
58+
[source,yaml]
59+
----
60+
servicenow:
61+
instanceUrl: ${SERVICENOW_INSTANCE_URL}
62+
oauth:
63+
grantType: password
64+
clientId: ${SERVICENOW_CLIENT_ID}
65+
clientSecret: ${SERVICENOW_CLIENT_SECRET}
66+
username: ${SERVICENOW_USER}
67+
password: ${SERVICENOW_PASS}
68+
----
5069

51-
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:
70+
== Frontend UI configuration
71+
The frontend plugin configuration defines how ServiceNow data appears on component entity pages.
5272

53-
* `servicenow.com/service-id`: Maps the entity to a specific ServiceNow Service ID.
54-
* `servicenow.com/category:` Filters incidents by a specific ServiceNow category.
73+
[source,yaml]
74+
----
75+
dynamicPlugins:
76+
frontend:
77+
backstage-community.plugin-servicenow:
78+
entityTabs:
79+
- path: /servicenow
80+
title: ServiceNow
81+
mountPoint: entity.page.servicenow
82+
mountPoints:
83+
- mountPoint: entity.page.servicenow/cards
84+
importName: ServicenowPage
85+
config:
86+
layout:
87+
gridColumn: 1 / -1
88+
height: 75vh
89+
----

0 commit comments

Comments
 (0)