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

1. SnowMirror Requirements

SnowMirror is a Java-based application which mirrors data from ServiceNow into your local database. It mirrors data using ServiceNow API: either SOAP web services or REST API.

Moreover, the SnowMirror application comes with SnowMirror Monitor which provides insight into SnowMirror directly from ServiceNow.

snowmirror diagram arch

What you need:
- ServiceNow Instance
- ServiceNow User with sufficient Rights
- Server with one of supported operating systems - Operating System
- Database into which all mirrored data will be stored

1.1. ServiceNow

SnowMirror can download data using SOAP API or REST API. Generally, it does not matter which one you choose.

For ideal communication between ServiceNow and SnowMirror we recommend you to activate some plugins and set up authentication credentials with sufficient rights.

1.1.1. SOAP API vs REST API

Generally, it does not matter which API you use. Most users use SOAP API because SnowMirror has supported it longer than REST API. For the largest customers, we created a custom-made Performance API - see details below or in Performance API documentation.

SOAP API REST API Performance API

Performance

Most of the time, the performance of SOAP and REST APIs is roughly the same. However, some customers reported that SOAP performs better, and some customers reported that REST performs better. You would have to test both APIs to see if you can observe any differences on your instance.

A custom-made API which provides the best performance because it is able to bypass ACL checks. It is mostly suitable for the largest customer with the largest amounts of data.

Timeout

Generous. ServiceNow provides a lot of time to process requests. Therefore, SOAP is usually preferred by customers with really large tables.

Limited. By default, ServiceNow provides up to 60 seconds to process a request. From time to time, this is not enough. Therefore, you have to increase Transaction Quota.

Generous. Configurable from SnowMirror. By default, a transaction can run for up to 10 minutes.

ServiceNow Plugins

You should activate Aggregate Web Service plugin so that SnowMirror is able to count records. See Plugins chapter for details.

It does not require any plugin.

It is a custom-made API. You have to install it to your ServiceNow instance via an update set.

Encryption

Communication between SnowMirror and ServiceNow is encrypted using standard TLS protocol.

Authentication

Basic Authentication

Basic Authentication or OAuth2

Basic Authentication or OAuth2

Non-active Columns

It can download only active columns.

It can download active columns and optionally non-active columns.

It can download active columns and optionally non-active columns.

Empty Integer Fields

When an integer field is empty in ServiceNow, SOAP API returns 0. It does not return an empty value. There is nothing SnowMirror can do about it, that is how ServiceNow SOAP API works.

Works as anyone would expect: it sends an empty value when an integer field is empty.

Works as anyone would expect: it sends an empty value when an integer field is empty.

Emojis

Ignores 4-byte characters like emojis (smileys).

Supports 4-byte characters like emojis (smileys).

Supports 4-byte characters like emojis (smileys).

1.1.2. Plugins

SnowMirror uses aggregate functions (counting records, finding out max. value, …​.) to provide the best user experience and to provide the best performance possible.

These functions are built in into REST API. If you use SOAP API, you have to activate Aggregate Web Service plugin to make them available. SnowMirror works even without this plugin. For the best performance, we recommend you to activate the plugin before running SnowMirror.

Plugin Activation

  1. To activate the plugin, open ServiceNow instance as an administrator.

  2. Search for Plugin application in menu bar and open application.

  3. On the top of the page type plugin name "aggregate" in search box and hit ENTER.

  4. Check if the plugin Status is ACTIVE otherwise open the plugin.

  5. On the plugin page click on Activate/Upgrade link in Related Links section and activate the plugin.

For more information please follow the official documentation on activating ServiceNow plugins.

1.1.3. User Access Rights

The communications with ServiceNow API is secured. SnowMirror uses basic HTTP authentication to secure both SOAP and REST API calls.

SnowMirror requires a user account with a read access to some system tables and to all mirrored tables. You can use an account with admin role. It is easy to set up and is suitable for evaluation. If you don’t want to use admin account, please see Security chapter for detailed description of all needed rights.

1.2. Application Requirements

SnowMirror is a Java web application, meaning it runs centrally on a server, and users interact with it throughout web browser from any computer.

1.2.1. Hardware

SnowMirror runs on any reasonably fast PC. See the minimal recommended hardware configuration.

  • Dual-core CPU (Intel or AMD)

  • 2 GB RAM

  • 1 GB HDD for installation

  • Additional 5 GB for log files

These requirements expect that only SnowMirror runs on that machine. You will need to run separate database server for mirror database. Of course, you may use your existing infrastructure for that database.

Estimating required storage space

SnowMirror keeps a log of all activities - the estimated storage required for these logs is around 80 MB per year.

SnowMirror also creates separate activity log for each synchronization run. The storage required for these logs vary depending on how many synchronizations you have, how often you synchronize them and how many records are being synchronized. Naturally, the longer you use SnowMirror more space for logs is required. See the examples below.

Table 1. Examples of required storage for activity logs
Amount of data Estimated storage required per year

Big (~150,000 updated records) synchronization every day

~ 45 MB per year

Big (~150,000 updated records) synchronization every hour

~ 1 GB per year

Smaller (~10,000 updated records) synchronization every day

~ 3 MB per year

Smaller (~10,000 updated records) synchronization every day

~ 72 MB per year

Then the total storage required per year can be calculated as:

Storage per year = 80 MB + (number of big daily synchronizations * 45 MB + (number of small daily synchronizations * 3 MB + (number of big hourly synchronizations * 1000) MB + (number of small hourly synchronizations * 72) MB

1.2.2. Java

Java is a piece of software that has to be installed on your computer. SnowMirror does not work without it. Currently, we support Eclipse Temurin 22.

On Windows, an up-to-date version of Java is included in the installation package. On Linux or Mac, you have to install it yourself. Please use Eclipse Temurin - package type JDK, architecture x64, version 22.

Java Is Provided Free Of Charge

Eclipse Temurin JDK is provided free of charge. Please, avoid releases of Oracle JDK. These are paid and come with Oracle’s commercial support.

1.2.3. Application server

SnowMirror runs on Apache Tomcat web server which is included in the installation package. We upgrade the Tomcat to the latest version on a regular basis.

1.2.4. Databases Or Cloud Storage

SnowMirror uses two databases.

  • Configuration database - stores metadata, i.e. what to synchronize, when to synchronize, etc.

  • Mirror database - stores data mirrored from ServiceNow

Configuration DB and mirror DB may use different database servers. However, the best practice is to have one database server containing two databases. For more information see Database Configuration section. You can install and maintain the database server yourself, or you can create the database in cloud services like Amazon RDS and Azure Databases.

Alternatively, you can store data into cloud storage as CSV files.

Table 2. Supported databases
Database Version On-Premise AWS RDS Azure Comments

Amazon Redshiftsince 5.0.0

All versions

✓

N/A

N/A

It can be used as a mirror database. It cannot be used as a configuration database.

Azure Synapsesince 4.10.0

All versions

✓

N/A

N/A

It can be used as a mirror database. It cannot be used as a configuration database.

Microsoft SQL Server

2008, 2008 R2, 2012, 2014, 2016, 2017, 2019, 2022

✓

✓

✓

MySQL

5.5, 5.6, 5.7, 8.0

✓

✓

✓

We also support AWS Aurora.

MariaDB

5.5, 10.x

✓

✓

✓

Oracle

11g, 12c, 18c, 19c, 21c, 23c

✓

✓

N/A

PostgreSQL

9.2, 9.3, 9.4, 9.5, 9.6, 10, 11, 12, 13, 14, 15, 16

✓

✓

✓

We also support AWS Aurora.

Snowflakesince 4.5.0

All versions

✓

N/A

N/A

It can be used as a mirror database. It cannot be used as a configuration database.

H2

>= 2.0.0, 1.4.199

✓

N/A

N/A

Embedded file-based database. Suitable only for evaluation.
Table 3. Supported Cloud Storages
Cloud Storage Supported Comments

Amazon S3since 5.0.0

✓

It can be used as a mirror database. It cannot be used as a configuration database.

Azure Storagesince 5.0.0

✓

It can be used as a mirror database. It cannot be used as a configuration database.

Google Cloud Storagesince 5.0.0

✓

It can be used as a mirror database. It cannot be used as a configuration database.

1.2.5. Browser

SnowMirror runs on all modern web browsers such as Microsoft Edge, Google Chrome and Mozilla Firefox.

Internet Explorer is not supported. The last SnowMirror that supported IE was 5.1.15.

1.2.6. Operating System

SnowMirror is operating system agnostic. It can run on any system which supports Java.

Operating System Version

Microsoft Windows Server

2003 32 bit, 2008 R2 64 bit, 2012 R2 64 bit, 2016, 2019, 2022

Microsoft Windows

XP 32/64 bit, 7 32/64 bit, 10 32/64 bit, 11

Linux

2. Installing SnowMirror

SnowMirror can be installed either using Windows Installer or manually from a ZIP package. Using the Windows Installer is the easiest and and most straightforward way to install and configure SnowMirror. On Linux you have to do the installation and configuration manually.

You can download SnowMirror from our website.

Direct links look like:

  • https://snow-mirror.com/downloads-enterprise/snow-mirror-VERSION.exe

  • https://snow-mirror.com/downloads-enterprise/snow-mirror-VERSION.zip

If you need checksum files, you can find them at https://snow-mirror.com/downloads-enterprise/checksum/snow-mirror-VERSION.exeOrZip.CHECKSUM-TYPE. Checksums available: md5, sha1, sha256, sha512

2.1. Prerequisites

You need two databases on your database server - configuration database and mirror database. See Database Configuration chapter.

If you don’t have the databases yet, you can use H2 database which is embedded into SnowMirror. This will give you an opportunity to test SnowMirror even before your database administrators create the databases for you. Just note, that H2 is not suitable for production environment.

2.2. Windows Installer

2.2.1. Express installation

Express installation installs SnowMirror with default settings and uses embedded H2 database to store configuration data. This is not recommended on production environments. On production environments, use Custom installation and choose a different database server.

  1. Run the Installer - Go to a location to where you downloaded SnowMirror installation file and run it.

  2. First Step - Simply click next.