This article covers how to use the Web API tile to query data from ServiceNow and display this data in SquaredUp DS.
Should you use the Web API tile or the dedicated ServiceNow tile?
The ServiceNow tile is available in SquaredUp DS v4.4 and above, and 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.
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 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 ServiceNow tile The permissions of the ServiceNow account you are using for your ServiceNow providerplugin affect what you can see and do in the ServiceNow tile.
We recommend using a service account, which means you create an account specifically to use with the ServiceNow providerplugin. You have different options for setting up this service account:
ServiceNow permissions assignment with roles Give the ServiceNow account the ITIL and rest_api_explorer roles.
ServiceNow permissions assignment with ACLs, in place of roles If you don't want to use the ITIL role (for licensing or security reasons) 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.Using accounts without the ITIL role may cause data streams to error.
When you are using an account without the roles specified in this article, then the functionality of the ServiceNow tileplugin is limited:.
You'll see an error if 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 grant the specific permissions required more granularly by creating a custom role and assigning the specific ACLs or assigning the ACLs themselves directly to a user account:
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 providerplugin.
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 providerplugin. 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 instances of the ServiceNow providersplugin.
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.
To allow the ServiceNow views to be pulled into the ServiceNow Grid visualization the ServiceNow account must also have the 'admin' role in ServiceNow.
A Connect edition license (or above) is required for this feature. To upgrade please contact [email protected].
Log on to SquaredUp DS 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/ where instancename 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 where instancename 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 How to configure SquaredUp DS to use a proxy.
Create a new dashboard and click on Integrations > Web API.
Select Web API (Grid).
The scope section (v4.2 and above) allows you to specify a scope of SCOM objects (see How to scope tiles), 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), (see Enterprise Applications) you might want 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.
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 to table/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: You might like to use one of the mustache style code snippets provided (SquaredUp DS 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 DS 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. 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 Enterprise Applications).
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, 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.
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.
