Home / , / ServiceNow Data Source

ServiceNow Data Source

ServiceNow company logo

In Geovonic Connect for ArcGIS, data sources provide connectivity to third-party business systems. The ServiceNow data source allows you to fetch real-time data from your ServiceNow instance to display in your ArcGIS web mapping applications using the REST API.

Geovonic Connect for ArcGIS works with both the standard out-of-the-box REST APIs and the Custom Scripted REST APIs. This article describes how to configure integration with ServiceNow.

You can find details of the APIs available in your ServiceNow instance using these functions:

  • Standard APIs: Search for Table API, part of the REST API Explorer
  • Custom Scripted APIs: Search for Scripted REST API, part of System Web Services.

Data Source Configuration

The ServiceNow data source configuration requires three fields: –

  • Base URL – The base URL for the REST API – e.g. https://dev12345.service-now.com/api
  • Test Endpoint Path – An API path that can be used to validate the connection properties. For example,
    /now/table/sys_user?sysparm_fields=name&sysparm_limit=1 will pull make a call to the user table.
  • Auth Method – Select the authentication method to use with your API.
  • If using Basic Auth: –
    • Username – the username of the account that Geovonic Connect will use to login to your ServiceNow instance.
    • Password – the password for the account.
  • If using OAuth2, configure the OAuth2.0 client credentials generated in ServiceNow.
  • HTTP Headers – not normally required. Used to add HTTP headers to every request.
  • Max Concurrency – the maximum number of concurrent requests Geovonic Connect will make to your ServiceNow API. Prevents overloading the API with large numbers of requests.
  • Timeout – how long to wait for ServiceNow API to respond before failing.

It is important when configuring any integration service to follow the Principle of Least Privilege. Any credentials used for the data source should only be able to access the minimum amount of information to meet the needs of your Geovonic Connect application. For example, do not provide the admin credentials for your ServiceNow if Geovonic Connect only needs to access a single API. Best practice is to create a new user with the least required privileges.

Layer Link Configuration

The ServiceNow layer link configuration defines the relationship between attributes on your ArcGIS features and records held in ServiceNow.

  • Path – The path to your API. This will be appended to the Base URL configured in the data source. You can include feature attributes using the {{ATTRIBUTE}} syntax or clicking on the [+] button to select from a list of attributes.
  • Query Parameters – Parameters to include in the request. One entry per line in the format ‘param=value’. Values can include feature attributes using {{ATTRIBUTE}} syntax.
  • Headers – Additional headers to be included on the request. One entry per line in the format ‘Header-Name: value’. Values can include feature attributes using {{ATTRIBUTE}} syntax. Defining headers here will overwrite the same header defined in the data source.
  • Response JSON Path – For the standard Table API, use result. For custom scripted APIs, include the JSON path of the data being returned from the API call. This can either be a single object or simple array.
  • Test Data – Define attribute values that will be used when validating your layer link configuration. If attribute values are not defined here, a single random feature from your feature layer will be used for validation.

Path is the only mandatory parameter.

Example Configuration

This example configuration uses the ServiceNow Table API to retrieve data from a Businesses table.

Path: /now/table/x_123456_nyc_bu_0_business You can find the path names for your tables in the ServiceNow REST API Explorer.

Query Parameters:

sysparm_query=number={{BusinessID}}
sysparm_fields=name,number,sys_id,address,owner_name,sys_updated_on,contact_info
sysparm_display_value=true

These parameters result in the following query being sent to ServiceNow: –

  • sysparm_query – Find records where the column name number is equal to the BusinessID attribute on your ArcGIS feature layer.
  • sysparm_fields – Provides the list of columns to be returned from the ServiceNow table.
  • sysparm_display_value – The value of true instructs ServiceNow to return display friendly values rather than system data values.

HTTP Headers: <blank>

Response JSON Path: result When using the standard ServiceNow Table API, use the value of result. Custom APIs may have a different response format.

Test Data Attribute Values: <optional>

By default when testing the ServiceNow query, Connect for ArcGIS will pick a random feature from your linked feature layer to populate the attribute values (in this case BusinessID). If your ServiceNow table does not contain a match for the randomly selected feature, the validation will fail with a no results message. Use the Test Data Attribute Values box to specify known values that will return data. For example:

{{BusinessID}}=NY01003

Search Configuration

The ServiceNow search configuration defines the relationship between records held in ServiceNow and the features contained in your ArcGIS feature layer.

  • Path – The path to your API. This will be appended to the Base URL configured in the data source. You can include feature attributes using the {{ATTRIBUTE}} syntax or clicking on the [+] button to select from a list of attributes.
  • Query Parameters – Parameters to include in the request. One entry per line in the format ‘param=value’. Values can include feature attributes using {{ATTRIBUTE}} syntax.
  • Headers – Additional headers to be included on the request. One entry per line in the format ‘Header-Name: value’. Values can include feature attributes using {{ATTRIBUTE}} syntax. Defining headers here will overwrite the same header defined in the data source.
  • Response JSON Path – For the standard Table API, use result. For custom scripted APIs, include the JSON path of the data being returned from the API call. This can either be a single object or simple array.
  • Test Data – Define attribute values that will be used when validating your layer link configuration. If attribute values are not defined here, a single random feature from your feature layer will be used for validation.

Path is the only mandatory parameter.

Example Configuration

This example configuration uses the ServiceNow Table API to perform a search against the Businesses table using the business name.

Input Fields: Name - Text - Downtown Deli

The sample value (Downtown Deli) will be used when testing the search configuration. It should be a valid value that will return at least one result.

Path: /now/table/x_123456_nyc_bu_0_business You can find the path names for your tables in the ServiceNow REST API Explorer.

Query Parameters:

syspardm_query=nameCONTAINS{{Name}}
sysparm_fields=number

These parameters result in the following query being sent to ServiceNow: –

  • sysparm_query – Find records where the column name contains the user-entered value in the Name input field.
  • sysparm_fields – Tells ServiceNow to return the number column. This will be used to match against features in your ArcGIS feature layer.

HTTP Headers: <blank>

Response JSON Path: result When using the standard ServiceNow Table API, use the value of result. Custom APIs may have a different response format.

Test Data Attribute Values: Not required

Feature Layer Attribute Map:

  • Attribute: BusinessID
  • Value: number

This tells Geovonic Connect that the number value returned from ServiceNow matches the BusinessID attribute on your ArcGIS feature layer.

Note: Click on the Refresh fields… link to populate the available fields for the value column.

Helpful Links