Admin Guide, User Manual, Rest API, SnowMirror Monitor, ServiceNow Upgrade, Error Codes, Release Notes

1. Introduction

SnowMirror Performance API provides a better performance compared to out-of-the-box REST or SOAP APIs. Performance API is a global-scoped application in ServiceNow. It achieves better download times by turning off ACL checks, turning off business rules and streaming the results.

If you want to try it out, feel free to download it and follow instruction in this documentation.

The Performance API is now in its preview phase. It’s been thoroughly tested and is ready for use. We are eager to hear any feedback from our customers. The Performance API is available only in Cluster edition, but we are offering test licenses to anyone who is interested.

2. How it Works

Performance API is a global-scoped application that you need to install into ServiceNow. The API exposes a new endpoint where SnowMirror can connect.

It achieves better performance by:

  • Turning off ACL checks - turns out, ACL checks take substantial time to evaluate. By default, Performance API does not check ACLs. Turning off ACL checks makes the greatest difference in download times compared to out-of-the-box API. This behavior is configurable. You can enable ACL checks on all tables or on selected tables.

  • Turning off business rules - by default, Performance API does not run business rules. This behavior is configurable.

  • Streaming responses - Performance API writes data to the response stream as soon as possible. SnowMirror reads the stream on the fly - i.e. it does not wait until it receives the full response. Therefore, API writes data to the stream and at the same time, SnowMirror processes the data.

  • Decreasing the size of responses - Performance API decreased the size of responses. Responses don’t contain repeated column names and empty fields are sent compressed.

3. Sample download times

Here are examples of download times from our testing environment. SnowMirror was configured to use up to 4 parallel connections (i.e. the default configuration).

Table Rows Columns Description REST API Performance API

Random custom table

7.5 million

7

A custom table with randomly generated data.

1 hour

9 minutes

Random custom table

60 thousand

305

A custom table with randomly generated data.

14 minutes

3 minutes

sys_dictionary

160 thousand

69

System table.

15 minutes

1 minute

4. Security

To be able to use Performance API, your user needs to have snowmirror_performance_api role assigned. The role is available once you install Performance API update set.

5. Installation

You have to install update set to ServiceNow. Then, you have to configure SnowMirror to start using Performance API.

5.1. ServiceNow

  1. Download SnowMirrorPerformanceApi.xml update set.

  2. Login to ServiceNow instance as a user with rights to install applications.

  3. In left navigation pane go to "Update sets" and select "Retrieved update sets".

  4. On opened page, select option "Import update sets from XML". Find the update set on your computer and click Open.

  5. Click "Upload".

  6. On Retrieved Update sets page, open your update set.

  7. Click "Preview Update Set". Once loaded, click "Commit Update Set".

  8. The update set created a role named snowmirror_performance_api. Assign this role to your user so that it can communicate with Performance API.

5.2. SnowMirror

  1. Make sure you use SnowMirror 5.6.0 and later.

  2. Login to SnowMirror.

  3. Go to Settings → ServiceNow page.

  4. Set "API" field to "Performance".

  5. Click "Test Connection" button to see if it works.

  6. Click "Save".

6. Licensing

Performance API is available only for customers with Trial or Cluster license. If you want to try out Performance API and you have Enterprise license, drop us an email at info@snow-mirror.com.

7. Configuration

7.1. Performance Tuning

By default, we download data in batches of 10,000 records ("Read Batch Size"). To improve download times even more, feel free to play with batch size.

You can increase "Read Batch Size" to 50,000 or even 100,000 records. On the other hand, the higher the "Record Batch Size" is, the longer it takes to process a request on ServiceNow side. I.e. ServiceNow semaphores will be blocked for a longer continuous period of time.

Batch Size can be changed:

7.2. ServiceNow

In ServiceNow, Performance API is configurable via system properties:

Property Description

snowmirror.performance-api.acl.check

Decides whether SnowMirror Performance API checks ACLs.
Possible values:

  • false/not defined/empty value: Performance API does not check ACLs.

  • true: Performance API checks ACLs.

snowmirror.performance-api.acl.includes

Comma separated list of tables which should always check ACLs. If ACL checks is disabled, we will check ACLs only for these tables.

snowmirror.performance-api.acl.excludes

Comma separated list of tables which should not check ACLs. If ACL checks is enabled, we will not check ACLs only for these tables.

snowmirror.performance-api.business-rules.enabled

Decides whether SnowMirror Performance API runs business rules. Possible values:

  • false/not defined/empty value: Performance API does not run business rules.

  • true: Performance API runs business rules.

snowmirror.performance-api.business-rules.includes

Comma separated list of tables which should always run business rules. If running business rules is disabled, we will run business rules only for these tables.

snowmirror.performance-api.business-rules.excludes

Comma separated list of tables which should not run business rules. If running business rules is enabled, we will not run business rules only for these tables.

7.3. SnowMirror

In SnowMirror, Performance API can be configured via Advanced Properties. Here is a list of all advanced properties. By default, you are not expected to change the properties. You will never have to use most of the properties.

Property Description

serviceNow.rest.performanceApi.urlPrefix

URL prefix of SnowMirror’s Performance API REST API. Default value: api/gvs

serviceNow.rest.performanceApi.name

Name of the API. It is a part of the target URL. Default value: performance_api

serviceNow.rest.performanceApi.version

The version of the REST API to use. When empty, the latest version is used.

serviceNow.rest.performanceApi.streaming.enabled

Should we use a streaming parser where possible? Allowed values: true, false. Default value: true</value>

serviceNow.rest.performanceApi.params.debug

Should the Performance API log to ServiceNow logs? Default value: empty string. Allowed values: empty value, off, trace, debug, info.

serviceNow.rest.performanceApi.params.retrieveLogs

Should we retrieve logs of Performance API in responses? Use with care! Logs are gathered in memory in ServiceNow. Suitable only for smaller requests, especially if "trace" of "debug" levels are enabled. Default value: false. Allowed values: true, false.</value>

serviceNow.rest.performanceApi.params.responseStyle

How the response JSON should look like. Default value: empty string. Allowed values: empty value, array, field, default.

serviceNow.rest.performanceApi.params.compressEmptyFields

Should we compress empty fields in "array"-style responses? Default value: empty string. Allowed values: empty value, true, false.

serviceNow.rest.performanceApi.params.maxDurationInSeconds

For how many seconds is Performance API allowed to process a single request. Default value: empty string. Allowed values: a number. Default value: 600

serviceNow.number.of.records.performanceApiWithAcl

How many records to download in one batch using Performance API if ACLs are enabled. It should be much lower than "serviceNow.number.of.records.performanceApi" because ACL checks are expensive. Default value: 1000.