Plugins 〉ServiceNow

Data Source
grafana
Enterprise

ServiceNow

  • Overview
  • Installation
  • Change log
  • Related content

ServiceNow data source for Grafana

The ServiceNow data source plugin allows you to query and visualize data from ServiceNow within Grafana.

Requirements

The ServiceNow data source has the following requirements:

Install the ServiceNow data source plugin

To install the data source, refer to Installation

Configure ServiceNow

We recommend creating a new user for Grafana or using a service user. The ServiceNow user provided requires access to the following tables:

TableReason
sys_db_objectUsed to retrieve a list of available tables to query.
sys_dictionaryUsed to retrieve the list of fields when querying a table.
sys_choiceUsed to retrieve the list of choices when filtering table results using a choice field.
sys_glide_objectUsed to collect information about data types including names, base types, and so on.
incidentUsed in the healthcheck to validate the Table API and the Aggregate API are functioning

It is recommended that the user being used only has access to the necessary tables. If the user has access to too many tables, then you may encounter performance issues in the query editor.

Developer instance

To create and set up a developer instance of ServiceNow, go to the ServiceNow Developer page to create an account.

Configure the data source in Grafana

Add a data source by filling in the following fields:

HTTP fields

NameDescription
HTTP URLURL of the ServiceNow instance.
Whitelisted CookiesGrafana Proxy deletes forwarded cookies by default. Specify cookies by name that should be forwarded to the data source.

Authentication fields

FieldDescription
Basic authEnter a ServiceNow user name and password
TLS Client AuthBuilt-in option for authenticating using Transport Layer Security
Skip TLS VerifyEnable to skip TLS verification
With CredentialsEnable to send credentials such as cookies or auth headers with cross-site requests.
With CA CertEnable to verify self-signed TLS Certs
Forward OAuth IdentityForward the identity of the oauth user signed in to Grafana, for cases where the same oauth provider is used for both Grafana and the data source

Custom HTTP Header Data sources managed by provisioning within Grafana can be configured to add HTTP headers to all requests going to that datasource. The header name is configured in the jsonData field and the header value should be configured in secureJsonData.

Configure the data source with provisioning

It is possible to configure data sources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for data sources on the provisioning docs page

apiVersion: 1

datasources:

  • name: ServiceNow type: servicenow-datasource enabled: true access: proxy url: https://dev59952.service-now.com basicAuth: true basicAuthUser: ADD_YOUR_USER_HERE jsonData: basicAuthUser: ADD_YOUR_USER_HERE tlsSkipVerify: true secureJsonData: basicAuthPassword: ADD_YOUR_PASSWORD_HERE version: 1 editable: true isDefault: true

Query the data source

There are two query methods: Table and Stats.

Table query

Returns data suitable for displaying in a table panel. It allows for an ordered selection of fields to display plus filtering options. The query editor also provides a field to limit the number of rows returned by a query.

query editor table - query

Example table panel showing results from query above:

query editor table - example

Show

The Show row provides a selector for a field to be displayed. Multiple fields can be also be specified. The fields will be returned in the exact order specified.

Display Values

The Display Values flag will cause the query to return human-friendly values, or "Display Values", instead of numeric values. There are three different options available

OptionDescription
AllPreferred way. This mode is for displaying human friendly display values. Also integer fields will be rendered as numbers and Choice fields will be displayed with human friendly labels.
TrueThis is similar to all mode. But integer fields will be rendered as formatted strings.
FalseWith this mode, all the fields displayed with actual values instead of labels. This may have better performance than other modes. (Note: Choice fields like severity/state will be displayed as integer IDs instead human friendly labels )

For example, a severity of 1 with false flag would only display 1. If the flag is set to true/all, the value displayed will be 1 - High.

According to the ServiceNow API documentation, all and true modes may be slower than false mode. Read more about Display value / sysparm_display_value in ServiceNow Documentation

Filters (general)

The Filters row provides the ability to narrow down the displayed rows based on multiple field and value criteria.

All filters are combined with an AND or an OR operation.

When selecting a custom table, fields are automatically populated from the Service Now API.

Values

Value selection depends on the type of filter selected.

  • Boolean filters have True/False options
  • Text filters will allow typing any value
  • Date filters display the date-picker calendar if choosing a date is required
  • Some operators, such as is anything or Today, do not display an additional field for input.

Sort By

The Sort By row provides the ability to narrow down the displayed rows based on multiple field and value criteria.

All filters are combined with an AND operation. Support for additional operators will be added.

Limit

A row limit can be specified to prevent returning too much data. The default value is 25.

Time Field

The Time Field is what turns your queried data into a time series. Your data being handled as a time series means that values in your selected "time field" that do not fall within your dashboard / panel's time range will not be displayed.

If this value is not toggled on, a special value "Ignore Time" is provided to allow results "up until now" and also to enable the filters to control what data is displayed.

The Time Field default is Opened At, but it can be changed to any available field that holds a time value.

Stats query

The AggregateAPI will always return metrics, with the following aggregations: avg, min, max, sum. Filtering is also available to narrow queries.

query editor stats

Show

The Show row provides a selector for a metric to be displayed. Multiple metrics can be also be specified.

Filters (general)

Aggregate Filters provide the ability to narrow down the displayed metrics based on field and value criteria, similar to the table option.

All filters are combined with an AND operation. Support for additional operators will be added.

Stat filter options are the same as the TableAPI.

Aggregation

There are four types of metric aggregations, plus a "count":

  • Average
  • Minimum
  • Maximum
  • Sum
  • Count - this returns the "number" of metrics returned by a query
Group By

This selector provides the ability to split metrics into lesser aggregates. Grouping by "priority" would return the metrics with a "tag" of priority and the unique values separated.

Field References

As of v2.0.0, field references are now supported.

Fields which are references to other tables are collapsed by default:

field reference collapsed

They will then expand to display the fields once they are clicked:

field reference expanded

Field references will only expanded to one level deep e.g. consider the following structure:

Field (Reference) ->
--- Field 1
--- Field 2 (Reference)
    --- Field 4
    --- Field 5
    --- Field 6 (Reference)
        --- Field 7
        --- Field 8 (Reference)
            ...
--- Field 3

Currently, only the first reference can be expanded, leading to the following:

Field (Reference) ->
--- Field 1
--- Field 3

Templates and variables

To add a new ServiceNow query variable, refer to Add a query variable. Use your ServiceNow data source as your data source for the following available queries:

After creating a variable, you can use it in your ServiceNow queries by using Variable syntax. For more information about variables, refer to Templates and variables.

Templating

Instead of hard-coding names in your queries, you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed on your dashboard.

See the example below in the Query Variable section on how to add a query variable and reference that with a Template value.

Query Variable

If you add a template variable of the type Query, you can write a query that can return items like category names, key names, or key values that are shown as a dropdown select box.

For example, you can have a variable that contains all values for categories by specifying a query like this in the templating variable Query setting.

When choosing the Query setting, a Filter section is displayed, allowing you to choose a Type and Field. Currently, Type is limited to Incidents and Changes. When selecting a type, you are provided with a list of fields applicable to that Type. Once a Type and Field are selected, a preview of values will be displayed at the bottom showing the options available for that Type/Field. Those values will be displayed in a drop down on the Dashboard, which you can use along with Templating to filter data on your Dashboard Panels.

For example, if you add a Variable named category then select Type = Incidents and Field = Category, you will see a list of options for Category. If you then add a Filter to a panel, and select Category Equals ${category}, the panel data will show only data for that Category that is selected from the Dashboard drop down.

Import the Incidents By Category dashboard to see an example.

Using Variables in Queries

There are two syntaxes:

$<varname> Example with a template variable named hostname:

[[varname]] Example with a template variable named hostname:

Annotations

Annotations give you the ability to overlay events on graphs.

The Annotations query supports the same options as the standard query editor.

Transformations

Transformations can be useful when using an aggregation query with group by clauses.

transformations-query-editor

Labels to Fields

Example of using the Labels to fields transformation:

transformations

Import a dashboard for ServiceNow

Follow these instructions for importing a dashboard.

Imported dashboards can be found in Configuration > Data Sources > select your ServiceNow data source > select the Dashboards tab to see available pre-made dashboards.

Version compatibility

Current version of plugin was tested against NewYork version of the ServiceNow. There is not a significant difference between each version, and some may be the exact same.

If your version of ServiceNow is not on this list, then it was not officially tested using this datasource. Basic features are expected to work in latest releases of ServiceNow such as Orlando, Paris and Quebec.

Version
New York
APIServiceNow VersionVersion
Table APINew Yorkv2
Aggregate APINew Yorkv1

Breaking changes

Upgrading to V2.0

Existing dashboards should continue working on 2.0. If there are any issues with existing dashboards no longer working, then know that this is not intended and your feedback is valued. Be sure to include copies of your panel JSON or dashboard JSON when submitting a support issue.

Backup your dashboards

It is imperative that you back up your dashboards before upgrading to v2.0. The query schema in v2.0 has changed, and migrations were added to change old queries to new ones as they are changed.

If you encounter any issues and need to downgrade, it is unlikely that your dashboards will continue working after downgrading.

Learn more

Using an HTTP Proxy

When using an HTTP Proxy, Grafana will need one of the following environment variables set:

  • HTTP_PROXY (or http_proxy)

    • Full path - http://host:port
    • or just: host:port
  • HTTPS_PROXY (or https_proxy):

    • Full path - https://host:port
    • or just: host:port

What if we don't have the ITSM Roles Plugin?

Administrator access is required to perform the following actions

Option 1: Grant Grafana user admin privileges to allow access to all tables.

Option 2: Create a role and apply ACLs to all tables that need to be accessed by Grafana

Administrator access is required to perform the following actions

  1. The logged in administrator needs to elevate access to security_admin

    1. Click the profile icon on the top right navigation panel. It's the one with the drop down carrot indicator
    2. From the dropdown click "Elevate Roles"
    3. From the modal that is shown, check the box next to "security_admin"
    4. Click OK
  2. Create a new role with whatever naming convention you'd like

    1. Navigate to the roles section in the left hand navigation System Security => Users and Groups => Roles
    2. Click "New" at the top
    3. Enter a name for the role and a relevant description
    4. Click Submit
  3. Create a new user and attach the role created in step 2

  4. Create Table ACLs for the required tables and fields

    1. Create ACL for the sys_db_object table

      1. In the second search header column "Name", type sys_db_object and press enter
      2. The filtered result should show "Table". Click to navigate into the record
      3. On the tab section, choose "Controls"
      4. On the bottom portion of the page, make sure "Access Controls" is the selected tab
      5. Click New to create a new ACL
      6. Change the "Operation" selection to read
      7. In the "Requires Role" section towards the bottom, double click "Insert New Row" and search for the role you created
      8. Click the green check mark after you have selected the role you have created
      9. Click Submit at the bottom to create the ACL then click continue when the modal appears
    2. Create ACLs for specific sys_db_object fields. The following steps will need to be repeated for each of the following fields: Name, Label, Display Name, and Extends table

      1. While still on the table record view for sys_db_object, select the "Columns" tab in the tab group closest to the top of the screen
      2. Locate the field name and select it
      3. In the bottom tab section click "New" in the access controls tab
      4. Change the operation to read
      5. Double click the insert a row text in the bottom "Requires role" table
      6. Search for the role you created and click the green check mark
      7. Click Submit
      8. Make sure that you've repeated these steps for all required fields: Name, Label, Display Name, and Extends table
    3. Repeat the steps from 4.1 on Change, Incident and any other non-CMDB tables that you would like to query from Grafana. Do not repeat the steps from 4.2, that step is only required for sys_db_object.

How to provide required access to the grafana user?

Administrator access is required to perform the following actions

Option 1: Perform the following steps to create an user for grafana to connect servicenow

  1. Elevate admin user to security admin to perform the following actions.
  2. Create a Role called grafana_reader_role. This can be anything.
  3. Create a User called grafana_user_1. This can be anything as well.
  4. Assign the below roles to the above user grafana_user_1 or whatever you created in step 3.
    • grafana_reader_role OR whatever you created in step 2.
  5. Create ACL rules which provide following permissions to the above role. To perform the following actions, admin user needed to be elevated to security admin.
    • read access to sys_db_object table
    • read access to sys_db_object.name field
    • read access to sys_db_object.label field
    • read access to sys_db_object.sys_name ( In ACL editor, it will be shown as Table[sys_db_object] => Display Name)
    • read access to sys_db_object.super_class ( In ACL editor, it will be shown as Table[sys_db_object] => Extends Table )
    • read access to sys_dictionary table
    • read access to sys_dictionary.* fields
    • read access to sys_choices table
    • read access to sys_choices.* fields
    • read access to sys_glide_object table
    • read access to sys_glide_object.* fields
  6. Provide read access to incident table. To perform this actions, admin user needed to be elevated to security admin.
  7. Repeat step 6 for the remaining table which the user need to read the data from.

Below steps explains on how to perform the above actions in detail.

  1. The logged in administrator needs to elevate access to security_admin

    1. Click the profile icon on the top right navigation panel. It's the one with the drop down carrot indicator
    2. From the dropdown click "Elevate Roles"
    3. From the modal that is shown, check the box next to "security_admin"
    4. Click OK
  2. Create a new role with whatever naming convention you'd like

    1. Navigate to the roles section in the left hand navigation System Security => Users and Groups => Roles
    2. Click "New" at the top
    3. Enter a name for the role and a relevant description
    4. Click Submit
  3. Create a new user or modify an existing user with the role you created in step 2

  4. Create Table ACLs for the required tables and fields

    1. Create ACL for the sys_db_object table

      1. In the second search header column "Name", type sys_db_object and press enter
      2. The filtered result should show "Table". Click to navigate into the record
      3. On the tab section, choose "Controls"
      4. On the bottom portion of the page, make sure "Access Controls" is the selected tab
      5. Click New to create a new ACL
      6. Change the "Operation" selection to read
      7. In the "Requires Role" section towards the bottom, double click "Insert New Row" and search for the role you created
      8. Click the green check mark after you have selected the role you have created
      9. Click Submit at the bottom to create the ACL then click continue when the modal appears
    2. Create ACLs for specific sys_db_object fields. The following steps will need to be repeated for each of the following fields: Name, Label, Display Name, and Extends table

      1. While still on the table record view for sys_db_object, select the "Columns" tab in the tab group closest to the top of the screen
      2. Locate the field name and select it
      3. In the bottom tab section click "New" in the access controls tab
      4. Change the operation to read
      5. Double click the insert a row text in the bottom "Requires role" table
      6. Search for the role you created and click the green check mark
      7. Click Submit
      8. Make sure that you've repeated these steps for all required fields: Name, Label, Display Name, and Extends table
    3. Repeat the steps from 4.1 on Change, Incident and any other non-CMDB tables that you would like to query from Grafana. Do not repeat the steps from 4.2, that step is only required for sys_db_object.

Option 2: Grant Grafana user admin privileges to allow access to all tables. ( STRONGLY NOT RECOMMENDED )

Administrator access is required to perform any of the above options

For more information, visit the docs on plugin installation.

Change Log

[2.2.4] - 2021-08-26

  • Increases health check limits to reduce the possibility of false negatives

[2.2.3] - 2021-08-19

  • Fix for v1.5 sort and limit migrations

[2.2.2] - 2021-08-17

  • Fix to prepend v1.5 conjunctions during migration

[2.2.1] - 2021-07-29

  • Migrate v1.5 conjunctions

[2.2.0] - 2021-07-21

  • ALL Display value mode added. This will be helpful when displaying numeric and string fields in same table.
  • Handle empty numeric string as null instead 0
  • UX improvement in Time field selector
  • Fixed a bug where panels without refId doesn't return data

[2.1.5] - 2021-06-21

  • Handle missing conjunctions and incorrect conjunctions.

[2.1.4] - 2021-05-05

  • Plugin health check updated with permissions check
  • Fixed an issue which made variable editor unusable
  • More data types handled (calendar_date_time,insert_timestamp,float,longint,percent_complete,price)

[2.1.3] - 2021-04-21

  • Fixed an issue where reference field types are not handled properly in data frame response. (decimal types)
  • Fixed an issue which now allow NQ / New Query filter conjunction along with AND/OR filters
  • Fixed an issue where is empty and is not empty filters were not working
  • Fixed an issue where is empty, is not empty and is anything operators not visible for boolean fields

[2.1.2] - 2021-04-12

  • Chore: Update SDK
  • Fix: Create Incident

[2.1.0] - 2021-03-19

  • Fixed a bug where integer filters were only showing string operators.
  • Added choice dropdown when creating filters.
  • Fixed a bug where unary operators were not working.
  • Fixed a bug where timestamps were not being sent as UTC.
  • Updated the documentation and removed unneeded screenshots.
  • Added doc tooltips for all fields.
  • Set default display value to true.
  • Fixed a bug where sysparm_query was being sent incorrectly.
  • Fixed a bug where filters were not being conjoined correctly with "AND".
  • Fixed a bug when loading old dashboards would not allow users to create more dashboards.
  • Fixed a bug where queries were not automatically ran when updating fields.
  • Fixed a bug where the "Hide query" button was not disabling the query.

[2.0.2] - 2020-12-15

  • Updated documentation.
  • Added tooltips for all fields.
  • Set default display value to true.
  • Fixed issue with filter where it does not work when being migrated.
  • Fixed issue with filter where some string operator fields are returning number operators.
  • Fixed custom fields being duplicated if they have the same name as an API field but with a different case.
  • Fixed display value toggle not being vertically aligned correctly.
  • Set default Time Field as Opened At.
  • Fixed issue with filters not being applied for aggregate API.
  • Fixed issue with filters not using correct conjunction when generating query for API.

[2.0.1] - 2020-12-11

  • Update grafana toolkit for new plugin signing

[2.0.0] - 2020-12-11

  • Added additional operators and filters, including relative time, IN, NOT IN, IS EMPTYSTRING, and IS ANYTHING filters.
  • Fixed several issues where global variables and variables from repeated rows and panels were not being populated.
  • Added a more native calendar selector for selecting dates when filtering on date-related columns.
  • The "Incidents", "Changes", and "Custom Table" options have been consolidated into a single table selection view.
  • Fixed an issue where Duration and CalendarSTC types were not being interpreted properly.
  • Fixed several cases where non-string fields were not being processed or displayed properly.
  • Improved QueryEditor performance by pre-loading necessary fields from the ServiceNow Dictionary Table.
  • Fixed issue(s) where reference fields were not being populated in some views.
  • When updating datasource settings, the healthcheck will respond with an error detailing what table access is missing for the plugin to work properly.
  • Increased the default HTTP timeout.
  • Added support in the Variable Query Editor for querying all fields and tables that the user has access to.
  • Added support in the Variable Query Editor for querying the Aggregate / Stats API.
  • Added additional backend validation that will result in more detailed error messages.
  • Fixed an issue where selecting a reference field resulted in an error. Selecting a reference field will now result in displaying the sys_id, which can be used when making reference queries.
  • Fixed an issue where date and datetime formats were not being parsed correctly.
  • Added Grafana 7.2+ annotation rendering, which allows users to use the standard query editor for creating annotations and annotation ranges.
  • Fixed an issue where queries with a Group By clause were not rendering properly>
  • Added query metadata that will show users the ServiceNow API query executed to retrieve panel data in the "Query Inspector"
  • Fixed an issue where the list of fields was not searchable

[1.4.0] - 2020-08-12

  • Added an "OR" option to the Filter component
  • Added ability to query any available table in ServiceNow
  • Frontend maintenance improvements
  • Changing query types, methods, or tables clears the query editor
  • Added support for automatically creating a Grafana notification channel
  • Added annotation support

[1.3.0] - 2020-05-19

  • Improved timeseries support
  • Works with Grafana 7+

[1.2.0] - 2020-05-14

  • Release with signing for Grafana 7.0.0

[1.1.1] - 2020-02-13

Added

  • Template variable support
  • Query variables
  • Unit tests

[1.0.1] - 2020-02-05

Fixed

  • Handles "spaces" in query names
  • Queries now sent in UTC
  • Update go modules and npm packages

[1.0.0] - 2019-12-15

Initial release

[0.0.1] - 2019-11-13

Preview release