ServiceNow

Data SourceENTERPRISE

ServiceNow datasource
Enterprise

Enterprise plugins, along with support and assistance from the core team behind Grafana, are available with Grafana Enterprise.

Upgrade Now

    Grafana Enterprise ServiceNow data source


    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.

    WARNING: BACK UP 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.


    This is the ServiceNow Datasource that is used to connect to ServiceNow instances.

    Table of contents

    1. Screenshots
    2. Installation
    3. Usage
    4. FAQ

    Features

    • Queries
      • Stat API Queries
      • Table API Queries
        • Incidents, Changes, and any other table
    • Annotations
    • Transformations
    • Template Variables

    Screenshots

    Installation

    Prerequisites

    Versions

    If your version of ServiceNow is not on this list, then it was not officially tested using this datasource.

    There is not a significant difference between each version, and some may be the exact same.

    Version
    New York
    APIServiceNow VersionVersion
    Table APINew Yorkv2
    Aggregate APINew Yorkv1

    Permissions

    You will need a user with permissions for reading data from relevant tables.

    The following tables are required:

    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.
    incidentUsed in the healthcheck to validate the Table API and the Aggregate API are functioning

    The supplied user will also need access to any table that is selected.

    To maximize performance of the plugin's query editor and reduce latency from the ServiceNow API, the service account supplied should not have access to more tables than necessary.

    Having access to too many tables could result in increased latency from the ServiceNow Table API.

    Create a role for Grafana that gives access to a minimal required set of tables.

    Developer instance

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

    Configuration

    Select datasources on the left panel of Grafana.

    select datasources

    Select Add Datasource:

    add datasources

    Type in servicenow to find the datasource plugin:

    filter datasources

    Fill in the details of your ServiceNow instance.

    If you do not have credentials or access to an instance, set one up.

    Click Save & Test, after which ServiceNow displays a green Plugin health check successful message.

    test datasource

    Example provisioning file

    Note: Update the two fields that follow with your username and password.

    # config file version
    apiVersion: 1
    
    deleteDatasources:
      - name: ServiceNow
        orgId: 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
    

    Example Dashboards

    Pre-made dashboards are included with the plugin and can be imported through the datasource configuration page, under the dashboards tab.

    import dashboards

    Usage

    There are two "methods" of returning data in the query editor.

    • TableAPI
    • AggregateAPI

    Users can currently choose between querying pre-defined tables, like:

    • Changes
    • Incidents

    Or, as of v2.0.0, data can be queried from any table, which is available to the user, and which they used to set up the ServiceNow data source.

    TableAPI queries

    The TableAPI 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.

    For example, a severity of 1 without this flag would only display 1. If the flag is enabled, the value displayed will be 1 - High.

    According to the ServiceNow API documentation, this can have a negative performance impact.

    [...] specifying the display value may cause performance issues since it is not reading directly from the database and may include referencing other fields and records.

    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.

    The following fields are available when not using a custom table (this list will expand in the future):

    Active
    Asset
    Group
    Assigned To
    Escalation
    Issue Number
    Description
    Priority
    State
    Type
    Change Risk
    Change State
    Start Date
    End Date
    On Hold
    

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

    Date Filters
    Time FieldOperatorsValue
    Opened AtAt or Before <br> Today <br> Not Today <br> Before <br> At or Before <br> After <br> At or Aftertimestamp <br> javascript:gs.daysAgo(30)
    Activity Due
    Closed At
    Due Date
    Expected Start
    Reopened Time
    Resolved At
    Work End
    Work Start
    Ignore Time

    For additional date values, see: https://developer.servicenow.com/app.do#!/api_doc?v=newyork&id=r_SGSYS-dateGenerate_S_S

    Operators (general/string-based)
    • Starts With
    • Ends With
    • Like
    • Not Like
    • Equals
    • Not Equals
    • Is Empty
    • Is one of
    • Is not one of
    • Is anything
    • Is emptystring
    Operators (time-based)
    • Today
    • Not Today
    • Before
    • At or Before
    • After
    • At or After
    • Relative (on or after)
    • Relative (on or before)
    • Relative (after)
    • Relative (before)
    • Relative (on)
    Operators (number-based)
    • Exact match
    • Does not match
    • Empty
    • Not empty
    • Greater than
    • Less than
    • Less than or equal
    • Greater than or equal
    Operators (boolean-based)
    • Equals
    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.

    AggregateAPI queries (Stats)

    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
    

    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:

    Using an HTTP Proxy

    When using an HTTP Proxy, Grafana will need the following environment variable(s) set to the location of the proxy:

    • 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

    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

    FAQ

    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 or modify an existing user with the needed roles

      1. The role you create in Step 2
      2. personalize_dictionary
      3. personalize_choices
      4. cmdb_read (this will grant read access to all cmdb tables)
    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.

    Sign up Now

    Version

    Includes:
    • Incident Overview

    • Change Overview

    Dependencies:
    • Grafana 7.0.x