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 Dashboard Server.
Should you use the Web API tile or the dedicated ServiceNow tile?
The ServiceNow tile offers easier configuration than the Web API tile. You can display incidents and change request with the ServiceNow tile. If you want to use any other data from ServiceNow, you need to use the Web API tile.
The Web API tile can display other data in addition to incidents and change requests, it gives you more flexibility and advanced configurations.
You can also watch the Webinar: Web API and ServiceNow
For more information about using the dedicated ServiceNow tile see How to use the ServiceNow tile.
This article covers these areas:
- Prerequisites
- Configuration in ServiceNow
- Adding ServiceNow as a Web API provider in Dashboard Server
- Walkthrough: Configuring the Web API tile for ServiceNow
Prerequisites
- 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.
- If you use a proxy server you may need to configure the proxy
(How to configure Dashboard Server to use a proxy) . - A ServiceNow account. It depends on the roles of the ServiceNow account you use for the ServiceNow provider what functions are available in the ServiceNow tile.
How the ServiceNow account affects the
The permissions of the ServiceNow account you are using for your ServiceNow
We recommend using a service account, which means you create an account specifically to use with the ServiceNow
ServiceNow admin account
Give the ServiceNow account the admin role. This will give you full functionality in the
ServiceNow tile.ServiceNow non-admin account with ACLs
If you don't want to use the admin role due to security concerns, give the ServiceNow account only the rest_api_explorer role and use ACLs to give the account more rights.
This will limit the functionality of the ServiceNow tile a little bit (see table below). How to add the necessary ACLs to your ServiceNow accountWhen you are using a non-admin ServiceNow account for a
provider , the functionality of the ServiceNowtile is limited: You'll see an error when you used a scope for your tile
In the View dropdown, only the non-admin default view is available (contains a default set of columns)
Under Filter, default filters are not available, only user-created ones are visible
You can reinstate some of the functionality of non-admin ServiceNow accounts by using ACLs.
ACLs can be added in two ways:
Adding them directly to a user account, meaning you are adding the ACLs to the service account you are using for the ServiceNow
provider .Adding them to a role. We recommend that you create a new role specifically just for adding the ACLs to it. Then you need to assign the role to the service account you are using for the ServiceNow
provider .A benefit of adding the ACLs to a role is that it makes them easier to manage and you can assign the role to different users (in this case, service accounts) if you want to use different service accounts for different ServiceNow
provider s.
You need to add the following ACLs:
sys_filter
sys_dictionary.*
sys_dictionary
sys_db_object
sys_ui_list
sys_db_object.*
sys_ui_list.*
What tile functions do those ACLs add when I use a non-admin ServiceNow account?
The tile can be scoped
Under Filter, all default filters are visible
The ACLs don't affect the views. The View dropdown still shows only the non-admin default view. You need to use an admin Service account to see all the views.
ServiceNow non-admin account without ACLs
If you don't want to create ACLs and use only roles, give the ServiceNow account the roles rest_api_explorer and web_service_admin.
This will limit the functionality of the ServiceNow tile a little bit (see table below).
ServiceNow admin account | ServiceNow non-admin account with ACLs | ServiceNow non-admin account without ACLs | |
Being able to scope the tile | yes | yes (due to the ACLs) | yes (due to the web_service_admin role) |
Being able to see all views in the View dropdown, not only the default view | yes | no | no |
Being able to see all default filters, not only user-made ones | yes | yes (due to the ACLs) | no |
To allow the ServiceNow views to be pulled into the ServiceNow Grid visualization the ServiceNow account must also have the 'admin' role in ServiceNow.
Configuration in ServiceNow
- In your ServiceNow account in the Application Navigator (left-hand menu) go to System OAuth and click Application Registry.
- Click Create an OAuth API endpoint for external clients.
- Give it an easy to remember name like
Dashboard Server
and leave the other default settings as they are. - Once you've created the endpoint, open the entry to view the client ID and client secret. Click the padlock next to the client secret to see it.
- Copy client ID and client secret into a notepad for use later.
Adding ServiceNow as a Web API provider in Dashboard Server
- Log on to Dashboard Server and navigate to the right-hand menu ☰ > system > Integrations
- Under Integrations click on Web API, and then OAuth and type in a suitable name, e.g. ServiceNow.
- Change the grant type to password.
- The base URL should look something like
https://instancename.service-now.com/api/now/
whereinstancename
is your instance. If ServiceNow is installed on-premises, this may be something different. This URL is prepended to every request URL. - The token URL will be something like
https://instancename.service-now.com/oauth_token.do
whereinstancename
is your instance. - username and password are exactly those used to sign into the account which was setup with the permissions mentioned in the prerequisites.
- client id and secret are taken from the notes you made earlier.
- Leave the authorization scope empty
- Click save.
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
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.
Take a look at the ServiceNow documentation on the ServiceNow Aggregate API
You can also watch the How to integrate SquaredUp and ServiceNow tutorial Video.
Create a new dashboard and click on the Web API tile.
Select Web API (Grid).
The scope section allows you to specify resources, which can be used later in the tile configuration to insert resource properties into the query. For this walkthrough you can leave the scope empty.
In the provider section select the ServiceNow provider that you created.
In the http mode section paste
table/incident
into the URL box to make this a GET request totable/incident
. This base URL is prepended to the URL.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 number of results to the first twenty.name:
sysparm_query
value:active=true
. This will show open tickets only.
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.
In the grid columns section, hide the
sys_id
column, rename and reorder other columns as you like. Some columns, likeassigned_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.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 behttps://<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.
Click done.