SupportConsoleDevelopersStart a trialContact

Chapter 8. ServiceNow custom actions in Red Hat Developer Hub

Integrate ServiceNow with Red Hat Developer Hub to manage ServiceNow records by using Scaffolder actions and view ServiceNow data on entity pages.

In Red Hat Developer Hub, you can use ServiceNow custom actions to fetch and register resources within the catalog.

The custom actions in Developer Hub help you automate the management of records. By using the custom actions, you can:

  • Create, update, or delete a record
  • Retrieve information about a single record or many records

The ServiceNow custom actions plugin is community-sourced.

8.1. ServiceNow entity linking methods
Copy link

To view and manage ServiceNow incidents directly in Red Hat Developer Hub (RHDH), 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.

Red Hat Developer Hub 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.

8.1.1. Direct mapping (Backstage Entity ID column)
Copy link

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 RHDH 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

8.1.2. Flexible mapping (Custom column mapping)
Copy link

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 RHDH 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

8.1.3. Comparison of linking methods
Copy link

FeatureDirect mappingFlexible 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

Update the Red Hat Developer Hub 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 provisioned a custom configuration by following the steps in Provisioning and using your custom Developer Hub configuration, including the section on authoring a custom dynamic-plugins.yaml file.
  • You have administrator access to an Red Hat OpenShift Container Platform cluster.
  • Red Hat Developer Hub is installed on the cluster.

Procedure

  1. Open your Red Hat Developer Hub ConfigMap for editing.

  2. Add the ServiceNow backend and frontend plugin packages to the dynamic-plugins.yaml section, including the connection and UI configuration: 

    kind: ConfigMap
apiVersion: v1
metadata:
  name: rhdh-plugin-config
data:
  dynamic-plugins.yaml: |
    includes:
      - dynamic-plugins.default.yaml
    plugins:
      # -----------------------------------------------------------------
      # ... Your pre-existing custom dynamic plugins would be listed here
      # -----------------------------------------------------------------

      # ServiceNow Backend Plugin
      - package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-servicenow-backend:<tag>'
        disabled: false
        pluginConfig:
          servicenow:
            instanceUrl: ${SERVICENOW_BASE_URL}
            basicAuth:
              username: ${SERVICENOW_USERNAME}
              password: ${SERVICENOW_PASSWORD}

      # ServiceNow Scaffolder Module / Actions
      - package: 'oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-scaffolder-backend-module-servicenow:<tag>'
        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:<tag>'
        disabled: false
        pluginConfig:
          dynamicPlugins:
            frontend:
              backstage-community.plugin-servicenow:
                entityTabs:
                  - path: /servicenow
                    title: ServiceNow
                    mountPoint: entity.page.servicenow
                  - path: /my-servicenow
                    title: My ServiceNow tickets
                    mountPoint: entity.page.my-servicenow
                mountPoints:
                  - mountPoint: entity.page.servicenow/cards
                    importName: ServicenowPage
                    config:
                      layout:
                        gridColumn: 1 / -1
                        height: 75vh
                      if:
                        anyOf:
                          - hasAnnotation: servicenow.com/entity-id
                  - mountPoint: entity.page.my-servicenow/cards
                    importName: ServicenowPage
                    config:
                      layout:
                        gridColumn: 1 / -1
                        height: 75vh
                      if:
                        allOf:
                          - isKind: user
                          - isMyProfile

    where:

    <tag>

    Enter your RHDH version of Backstage and the plugin version, in the format bs_<backstage-version>__<plugin-version> (note the double underscore delimiter). To find these versions, complete the following steps:

    1. Find your Backstage version in the RHDH release notes preface.

    2. Locate the plugin version in the Dynamic Plugins Reference guide. For example, for RHDH 1.10 based on Backstage 1.49.4, use the format bs_1.49.4__<plugin-version>.

      Tip

      To ensure environment stability, use a SHA256 digest instead of a version tag. See Determining SHA256 Digests.

  3. Save the changes to the ConfigMap.
  4. Wait for the RHDH Operator to redeploy the pods. The plugins are available once the pods are in a Running state.

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 Red Hat Developer HubConfigMap 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 Red Hat Developer Hub catalog.

Procedure

  1. Open your software template YAML file.
  2. In the spec.steps section, add the ServiceNow action that corresponds to your goal.

  3. 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: 

    steps:
  - id: create-incident
    name: Create ServiceNow Incident
    action: servicenow:now:table:createRecord
    input:
      tableName: incident
      requestBody:
        short_description: "Printer is offline"
        description: "The office printer is not accessible via the network"
        severity: "3"

  4. Optional: To perform other operations, use the appropriate action ID and parameters:

    GoalAction IDKey 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 Red Hat Developer Hub interface.

8.1.7. ServiceNow configuration parameters
Copy link

The ServiceNow integration requires specific parameters in your configuration files to establish a connection between Red Hat Developer Hub and your ServiceNow instances. Use these parameters to define authentication methods, instance URLs, and UI layouts.

Define the following parameters in the app-config.yaml file or the dynamic-plugins.yaml section of the Red Hat Developer Hub ConfigMap to enable the backend and frontend plugins.

ParameterDescriptionRequirement

instanceUrl

The base URL of your ServiceNow instance. For example, 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

8.1.7.2. ServiceNow scaffolder configuration
Copy link

The ServiceNow Scaffolder module requires a separate configuration block. Note that this module uses baseUrl instead of instanceUrl.

ParameterDescriptionRequirement

baseUrl

The base URL of your ServiceNow instance.

Required

username

The service account username.

Required for Basic authentication

password

The service account password.

Required for Basic authentication

8.1.7.3. Authentication examples
Copy link

The following examples demonstrate how to structure different authentication methods in your configuration.

8.1.7.4. Basic authentication example
Copy link

servicenow:
  baseUrl: ${SERVICENOW_PROD_URL}
  username: ${SERVICENOW_USER}
  password: ${SERVICENOW_PASS}

8.1.7.5. OAuth with Client Credentials
Copy link

servicenow:
  instanceUrl: ${SERVICENOW_INSTANCE_URL}
  oauth:
    grantType: client_credentials
    clientId: ${SERVICENOW_CLIENT_ID}
    clientSecret: ${SERVICENOW_CLIENT_SECRET}

8.1.7.6. OAuth with Password Grant
Copy link

servicenow:
  instanceUrl: ${SERVICENOW_INSTANCE_URL}
  oauth:
    grantType: password
    clientId: ${SERVICENOW_CLIENT_ID}
    clientSecret: ${SERVICENOW_CLIENT_SECRET}
    username: ${SERVICENOW_USER}
    password: ${SERVICENOW_PASS}

8.1.7.7. Frontend UI configuration
Copy link

The frontend plugin configuration defines how ServiceNow data appears on component entity pages. 

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

To use ServiceNow custom actions, you must first activate the plugin.

Prerequisites

  • Red Hat Developer Hub is installed and running.
  • You have created a project in the Developer Hub.

Procedure

  1. Add a package with plugin name and update the disabled field in your dynamic-plugins.yaml file as follows: 

    plugins:
  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-scaffolder-backend-module-servicenow:<tag>
    disabled: false
    pluginConfig:
      servicenow:
        instanceUrl: ${SERVICENOW_BASE_URL}
        basicAuth:
          username: ${SERVICENOW_USERNAME}
          password: ${SERVICENOW_PASSWORD}

    where:

    <tag>

    Enter your RHDH version of Backstage and the plugin version, in the format bs_<backstage-version>__<plugin-version> (note the double underscore delimiter). To find these versions, complete the following steps:

    1. Find your Backstage version in the RHDH release notes preface.

    2. Locate the plugin version in the Dynamic Plugins Reference guide. For example, for RHDH 1.10 based on Backstage 1.49.4, use the format bs_1.49.4__<plugin-version>.

      Tip

      To ensure environment stability, use a SHA256 digest instead of a version tag. See Determining SHA256 Digests.

    Note

    The default configuration for a plugin is extracted from the dynamic-plugins.default.yaml file, however, you can use a pluginConfig entry to override the default configuration.

  2. Set the following variables in your app-config.yaml file to access the custom actions: 

    servicenow:
  # The base url of the ServiceNow instance.
  baseUrl: ${SERVICENOW_BASE_URL}
  # The username to use for authentication.
  username: ${SERVICENOW_USERNAME}
  # The password to use for authentication.
  password: ${SERVICENOW_PASSWORD}

The ServiceNow custom actions enable you to manage records in the Red Hat Developer Hub.

The custom actions support the following HTTP methods for API requests:

  • GET: Retrieves specified information from a specified resource endpoint
  • POST: Creates or updates a resource
  • PUT: Modify a resource
  • PATCH: Updates a resource

  • DELETE: Deletes a resource

    [GET] servicenow:now:table:retrieveRecord

    Retrieves information of a specified record from a table in the Developer Hub.

    The following table describes the input parameters:

    NameTypeRequirementDescription

    tableName

    string

    Required

    Name of the table to retrieve the record from

    sysId

    string

    Required

    Unique identifier of the record to retrieve

    sysparmDisplayValue

    enum("true", "false", "all")

    Optional

    Returns field display values such as true, actual values as false, or both. The default value is false.

    sysparmExcludeReferenceLink

    boolean

    Optional

    Set as true to exclude Table API links for reference fields. The default value is false.

    sysparmFields

    string[]

    Optional

    Array of fields to return in the response

    sysparmView

    string

    Optional

    Renders the response according to the specified UI view. You can override this parameter using sysparm_fields.

    sysparmQueryNoDomain

    boolean

    Optional

    Set as true to access data across domains if authorized. The default value is false.

    The following table describes the output parameters:

    NameTypeDescription

    result

    Record<PropertyKey, unknown>

    The response body of the request

    [GET] servicenow:now:table:retrieveRecords

    Retrieves information about multiple records from a table in the Developer Hub.

    The following table describes the input parameters:

    NameTypeRequirementDescription

    tableName

    string

    Required

    Name of the table to retrieve the records from

    sysparamQuery

    string

    Optional

    Encoded query string used to filter the results

    sysparmDisplayValue

    enum("true", "false", "all")

    Optional

    Returns field display values such as true, actual values as false, or both. The default value is false.

    sysparmExcludeReferenceLink

    boolean

    Optional

    Set as true to exclude Table API links for reference fields. The default value is false.

    sysparmSuppressPaginationHeader

    boolean

    Optional

    Set as true to suppress pagination header. The default value is false.

    sysparmFields

    string[]

    Optional

    Array of fields to return in the response

    sysparmLimit

    int

    Optional

    Maximum number of results returned per page. The default value is 10,000.

    sysparmView

    string

    Optional

    Renders the response according to the specified UI view. You can override this parameter using sysparm_fields.

    sysparmQueryCategory

    string

    Optional

    Name of the query category to use for queries

    sysparmQueryNoDomain

    boolean

    Optional

    Set as true to access data across domains if authorized. The default value is false.

    sysparmNoCount

    boolean

    Optional

    Does not run a select count(*) on the table. The default value is false.

    The following table describes the output parameters:

    NameTypeDescription

    result

    Record<PropertyKey, unknown>

    The response body of the request

    [POST] servicenow:now:table:createRecord

    Creates a record in a table in the Developer Hub.

    The following table describes the input parameters:

    NameTypeRequirementDescription

    tableName

    string

    Required

    Name of the table to save the record in

    requestBody

    Record<PropertyKey, unknown>

    Optional

    Field name and associated value for each parameter to define in the specified record

    sysparmDisplayValue

    enum("true", "false", "all")

    Optional

    Returns field display values such as true, actual values as false, or both. The default value is false.

    sysparmExcludeReferenceLink

    boolean

    Optional

    Set as true to exclude Table API links for reference fields. The default value is false.

    sysparmFields

    string[]

    Optional

    Array of fields to return in the response

    sysparmInputDisplayValue

    boolean

    Optional

    Set field values using their display value such as true or actual value as false. The default value is false.

    sysparmSuppressAutoSysField

    boolean

    Optional

    Set as true to suppress auto-generation of system fields. The default value is false.

    sysparmView

    string

    Optional

    Renders the response according to the specified UI view. You can override this parameter using sysparm_fields.

    The following table describes the output parameters:

    NameTypeDescription

    result

    Record<PropertyKey, unknown>

    The response body of the request

    [PUT] servicenow:now:table:modifyRecord

    Modifies a record in a table in the Developer Hub.

    The following table describes the input parameters:

    NameTypeRequirementDescription

    tableName

    string

    Required

    Name of the table to change the record from

    sysId

    string

    Required

    Unique identifier of the record to change

    requestBody

    Record<PropertyKey, unknown>

    Optional

    Field name and associated value for each parameter to define in the specified record

    sysparmDisplayValue

    enum("true", "false", "all")

    Optional

    Returns field display values such as true, actual values as false, or both. The default value is false.

    sysparmExcludeReferenceLink

    boolean

    Optional

    Set as true to exclude Table API links for reference fields. The default value is false.

    sysparmFields

    string[]

    Optional

    Array of fields to return in the response

    sysparmInputDisplayValue

    boolean

    Optional

    Set field values using their display value such as true or actual value as false. The default value is false.

    sysparmSuppressAutoSysField

    boolean

    Optional

    Set as true to suppress auto-generation of system fields. The default value is false.

    sysparmView

    string

    Optional

    Renders the response according to the specified UI view. You can override this parameter using sysparm_fields.

    sysparmQueryNoDomain

    boolean

    Optional

    Set as true to access data across domains if authorized. The default value is false.

    The following table describes the output parameters:

    NameTypeDescription

    result

    Record<PropertyKey, unknown>

    The response body of the request

    [PATCH] servicenow:now:table:updateRecord

    Updates a record in a table in the Developer Hub.

    The following table describes the input parameters:

    NameTypeRequirementDescription

    tableName

    string

    Required

    Name of the table to update the record in

    sysId

    string

    Required

    Unique identifier of the record to update

    requestBody

    Record<PropertyKey, unknown>

    Optional

    Field name and associated value for each parameter to define in the specified record

    sysparmDisplayValue

    enum("true", "false", "all")

    Optional

    Returns field display values such as true, actual values as false, or both. The default value is false.

    sysparmExcludeReferenceLink

    boolean

    Optional

    Set as true to exclude Table API links for reference fields. The default value is false.

    sysparmFields

    string[]

    Optional

    Array of fields to return in the response

    sysparmInputDisplayValue

    boolean

    Optional

    Set field values using their display value such as true or actual value as false. The default value is false.

    sysparmSuppressAutoSysField

    boolean

    Optional

    Set as true to suppress auto-generation of system fields. The default value is false.

    sysparmView

    string

    Optional

    Renders the response according to the specified UI view. You can override this parameter using sysparm_fields.

    sysparmQueryNoDomain

    boolean

    Optional

    Set as true to access data across domains if authorized. The default value is false.

    The following table describes the output parameters:

    NameTypeDescription

    result

    Record<PropertyKey, unknown>

    The response body of the request

    [DELETE] servicenow:now:table:deleteRecord

    Deletes a record from a table in the Developer Hub.

    The following table describes the input parameters:

    NameTypeRequirementDescription

    tableName

    string

    Required

    Name of the table to delete the record from

    sysId

    string

    Required

    Unique identifier of the record to delete

    sysparmQueryNoDomain

    boolean

    Optional

    Set as true to access data across domains if authorized. The default value is false.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top