8 minute readApplies to: v4

How to use the Web API tile with ServiceNow

This article covers how to use the Web API tile to query data from ServiceNow and display this data in SquaredUp.

We recommend you use the newer ServiceNow tile available in SquaredUp v4.4, which offers easier configuration and the ability to use the donut visualisation. However, for more flexibility and advanced configurations you may prefer to use the Web API tile with ServiceNow as described in this article.

You can also watch the Webinar: Web API and ServiceNow

This article covers these areas:

  1. Configuration in ServiceNow
  2. Adding a ServiceNow provider in SquaredUp.
  3. Configuring the Web API tile for ServiceNow

Prerequisites

  • SquaredUp v4 with the Enterprise or EAM edition – this gives you the Web API tile. The SquaredUp server must have access to your ServiceNow instance on port 443 (HTTPS), since it is the server that connects to ServiceNow, and not your users' browser.
  • A ServiceNow instance.
  • The username and password of the account to use for requests (we recommend a service account). This ServiceNow user must have the 'web_service_admin' role and check 'Allow access to this table via web services'. You may need some help from a ServiceNow admin to get an account with the correct privileges.
  • If you use a proxy server you may need to configure the proxy to allow the Web API tile to communicate with ServiceNow.

Configuration in ServiceNow

  1. In the Application Navigator (left-hand menu) go to System OAuth and click Application Registry.
  2. Click Create an OAuth API endpoint for external clients.
  3. Call it something like SquaredUp to make it easier to remember, all the other defaults should be fine.
  4. Once you've created the endpoint, open the entry to view the client ID and secret (click the padlock next to the client secret to see it!) and copy these into a notepad for use later.

Adding a ServiceNow provider in SquaredUp

  1. Log on to SquaredUp and navigate to the right-hand menu ☰ then system and then click on the web api perspective.
  2. Click Add new provider.
  3. Change the provider type to OAuth and type in a suitable name, e.g. ServiceNow.
  4. Change the grant type to password.
  5. The base URL should look something like https://instancename.service-now.com/api/now/ where instancename is your instance. If ServiceNow is installed on-premises, this may be something different. This URL is prepended to every request URL.
  6. The token URL will be something like https://instancename.service-now.com/oauth_token.do where instancename is your instance.
  7. username and password are exactly those used to sign into the account which was setup with the permissions mentioned in the prerequisites.
  8. client id and secret are taken from the notes you made earlier.
  9. Leave the authorisation scope empty
  10. Click add provider.

If the configuration is correct you will see a green tick.

If the provider is not authorized it could be that some of the provider configuration is incorrect (for example the username, password, secret etc), or if you use a proxy it could be that the proxy is not configured. See How to configure SquaredUp to use a proxy.

Walkthrough: Configuring the Web API tile for ServiceNow

This walkthrough takes you through configuring a simple tile to show a list of the open incidents.

You'll find the ServiceNow document with the relevant information here: ServiceNow Aggregate API

You can also watch the How to integrate SquaredUp and ServiceNow tutorial Video.

  1. Create a new dashboard and click on the Web API tile.
  2. Select Web API (Grid).
  3. The scope section (v4.2 and above) allows you to specify a scope of SCOM objects, which can be used later in the tile configuration to insert SCOM object properties into the query. For this walkthrough you can leave the scope empty.

    If you wish to add a scope you could click on group and search to find a suitable group of computers. You need a group that contains servers monitored by ServiceNow which we can query later.

    Or for a perspective for use with Enterprise Applications (EAs), you might want to to scope to the servers that are specified on the EA map by selecting something similar to the following:

    This /<YourApplicationName> Map / ... / Windows Computer

    The above will scope the tile to all the objects of class Windows Computer on this EA's map.

  4. In the provider section select the ServiceNow provider that you created.
  5. In the http mode section paste table/incident into the URL box to make this a GET request to table/incident. This base URL is prepended to the URL.
  6. In the headers & data section click add under data to add the following parameters to the request to select the correct data and format for the grid:

    • name: sysparm_display_value value: true. This will show the display value of any columns which are IDs by default.
    • name: sysparm_fields value: sys_id,urgency,short_description,severity,state,assigned_to. This will only select the fields we are interested in. You can compile a list of fields using the REST API Explorer on your own ServiceNow instance.
    • name: sysparm_limit value: 20. This will limit the amount of results to the first twenty.
    • name: sysparm_query value: active=true. This will show open tickets only.

    You might like to use one of the mustache style code snippets provided (SquaredUp v4.2 and above). You'll need to go back and define a scope for the Web API tile first, then you can either start with one of the snippets provided, or write your own dynamic query string. SquaredUp v4.2 and above support multi-object query building based on a list of objects from the tile's scope, and the use of JavaScript to manipulate the SCOM property values using functions such as split() and substring().

    When you click the mustache editor button {{}} you will see a list of example scope code snippets, along with the snippet result based on the selected scope context for the tile.

    Web API Snippets

    We're working on a dashboard, but the Web API tile scope and dynamic queries can be particularly useful on perspectives. For example, you might like to show ServiceNow asset information for a dynamic list of servers found as children of an Enterprise Application (EA) object. See Scoping tiles on perspectives.

  7. In the response data section, paste result into the box.

    Rows of data should now be shown.

    The grid columns and grid options sections allow you to configure the columns and column names.

  8. In the grid columns section, hide the sys_id column, rename and reorder other columns as you like. Some columns, like assigned_to will be returned as [object Object]. Click edit next to these columns, and then click the {} icon, then select the display value to have these display correctly.
  9. In the grid options section, we can set the row link to make each row hyperlink to that ServiceNow incident. To make each row replace the sys_id with the one from that object the URL should be https://<your-instance>.service-now.com/nav_to.do?uri=%2Fincident.do%3Fsys_id%3D{{sys_id}}

    For more help customizing the columns of data see How to use the Grid designer when configuring tiles.

  10. Click done.

How to use the ServiceNow Tile

Webinar: Web API and integration with ServiceNow

Tutorial Video: How to integrate SquaredUp and ServiceNow

ServiceNow Aggregate API

ServiceNow REST API Explorer

How to use the Web API tile

How to use custom labelling

Webinar: Custom labelling

Webinar: Introduction to perspectives

How to use the Web API tile with Splunk

How to use the Grid designer when configuring tiles

How to configure SquaredUp to use a proxy

Squared Up Ltd. (c) 2020Report an issue with this article