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..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,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] 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..089e518cff3 --- /dev/null +++ b/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 +|=== 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 new file mode 100644 index 00000000000..b06146f6c7c --- /dev/null +++ b/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. diff --git a/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc b/modules/shared/proc-link-servicenow-tickets-to-catalog-entities.adoc new file mode 100644 index 00000000000..85be0a47670 --- /dev/null +++ b/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: +---- + +`servicenow.com/`:: + Annotation pattern for linking to ServiceNow records. Replace `` 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. \ No newline at end of file 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 new file mode 100644 index 00000000000..20e9e514d7f --- /dev/null +++ b/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. +==== diff --git a/modules/shared/ref-servicenow-configuration-parameters.adoc b/modules/shared/ref-servicenow-configuration-parameters.adoc new file mode 100644 index 00000000000..b04c26df534 --- /dev/null +++ b/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 +---- \ No newline at end of file