Documentation Plugins ServiceNow Configure

Configure the ServiceNow data source

This document explains how to configure the ServiceNow data source in Grafana, set up authentication, and prepare your ServiceNow instance.

Before you begin

Before configuring the data source, ensure you have:

• Grafana permissions: Organization administrator role.
• Grafana version: 11.6.7 or later.
• ServiceNow account: A user account with access to the tables you want to query. Grafana recommends creating a dedicated user or using a service account.
• Grafana license: Grafana Cloud Pro, Advanced, or a Pro trial, or Grafana Enterprise with an activated license.

Add the data source

To add the ServiceNow data source:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type ServiceNow in the search bar.
4. Select ServiceNow.
5. Click Add new data source.

Configure authentication

The ServiceNow data source supports two authentication methods. Select the method from the Authentication Type drop-down.

Basic authentication

Basic authentication uses a ServiceNow username and password.

OAuth authentication

OAuth authentication uses a ServiceNow username and password along with an OAuth Client ID and Client Secret.

Configure additional settings

The data source provides the following additional settings:

Custom headers

You can add custom HTTP headers that are sent with every request to ServiceNow. Use custom headers when your ServiceNow instance requires additional headers for proxy configurations or custom middleware.

Secure socks proxy

If your Grafana instance has the secure socks proxy feature enabled, you can toggle Enabled under Secure Socks Proxy to route data source connections through the proxy.

HTTP proxy

When routing Grafana traffic through an HTTP proxy, set one of the following environment variables on the Grafana server:

• HTTP_PROXY (or http_proxy): http://<HOST>:<PORT>
• HTTPS_PROXY (or https_proxy): https://<HOST>:<PORT>

Verify the connection

Click Save & test to verify the connection. A successful connection displays Plugin health check successful.

When Use Sys Tables? is enabled, the health check verifies access to each required system table and provides specific error messages if any permissions are missing. Refer to Troubleshoot ServiceNow for solutions to common health check errors.

Configure ServiceNow permissions

To use the Use Sys Tables? option, the ServiceNow user needs read access to the following tables:

Set up a ServiceNow user with ACL rules

The following steps require ServiceNow administrator access and are performed in your ServiceNow instance. These steps are only necessary when the Use Sys Tables? option is enabled. For more information about elevated privileges and ACL rules, refer to the ServiceNow elevated privilege documentation.

1. Elevate the administrator user to security_admin:

   1. Click the profile icon in the top-right navigation.
   2. Click Elevate Roles.
   3. Check the box next to security_admin.
   4. Click OK.

2. Create a role for Grafana:

   1. Navigate to System Security > Users and Groups > Roles.
   2. Click New.
   3. Enter a name (for example, grafana_reader_role) and description.
   4. Click Submit.

3. Create or update a user for Grafana:

   1. Create a new user (for example, grafana_user) or select an existing user.
   2. Assign the role you created in step 2 to this user.

4. Create ACL rules for the required system tables:

   1. Create a table-level read ACL for sys_db_object:
      1. Navigate to System Security > Access Control (ACL).
      2. In the Name column, search for sys_db_object and select the Table record.
      3. Select the Controls tab.
      4. In the Access Controls section, click New.
      5. Set Operation to read.
      6. In the Requires Role section, add the role you created.
      7. Click Submit.
   2. Create field-level read ACLs for sys_db_object. Repeat for each field: Name, Label, Display Name, and Extends table:
      1. On the sys_db_object table record, select the Columns tab.
      2. Select the field.
      3. In the Access Controls section, click New.
      4. Set Operation to read.
      5. Add the role you created.
      6. Click Submit.
   3. Create table-level read ACLs for sys_dictionary, sys_choice, sys_glide_object, and incident using the same process as step 4.1.

5. Add read access for any additional tables you want to query from Grafana (for example, change_request).

Developer instance

To create a ServiceNow developer instance for testing, go to the ServiceNow Developer page.

Provision the data source

You can define the data source using YAML files as part of Grafana’s provisioning system. For more information, refer to Provisioning Grafana.

Basic authentication example

Refer to the Provisioning configuration reference for all available keys.

YAML Copy

apiVersion: 1

datasources:
  - name: ServiceNow
    type: grafana-servicenow-datasource
    access: proxy
    url: https://<INSTANCE_ID>.service-now.com
    basicAuthUser: <USERNAME>
    jsonData:
      authMethod: basicAuth
      useSysTables: true
      queryTimeoutSeconds: 30
    secureJsonData:
      basicAuthPassword: <PASSWORD>

OAuth authentication example

YAML Copy

apiVersion: 1

datasources:
  - name: ServiceNow
    type: grafana-servicenow-datasource
    access: proxy
    url: https://<INSTANCE_ID>.service-now.com
    basicAuthUser: <USERNAME>
    jsonData:
      authMethod: serviceNowOAuth
      oauthClientID: <CLIENT_ID>
      useSysTables: true
      queryTimeoutSeconds: 30
    secureJsonData:
      basicAuthPassword: <PASSWORD>
      oauthClientSecret: <CLIENT_SECRET>

Terraform example

You can provision the ServiceNow data source using the Grafana Terraform provider. The following example configures the data source with OAuth authentication:

hcl Copy

resource "grafana_data_source" "servicenow" {
  type = "grafana-servicenow-datasource"
  name = "ServiceNow"
  url  = "https://<INSTANCE_ID>.service-now.com"

  basic_auth_enabled  = true
  basic_auth_username = "<USERNAME>"

  secure_json_data_encoded = jsonencode({
    basicAuthPassword = "<PASSWORD>"
    oauthClientSecret = "<CLIENT_SECRET>"
  })

  json_data_encoded = jsonencode({
    authMethod         = "serviceNowOAuth"
    oauthClientID      = "<CLIENT_ID>"
    useSysTables       = true
    queryTimeoutSeconds = 30
  })
}

For basic authentication, set authMethod to basicAuth and omit the OAuth fields.

Provisioning configuration reference

The following tables list all available provisioning keys:

jsonData fields:

secureJsonData fields: