SnowMirror Administrator Guide

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.

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.

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

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.

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

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.

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.

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

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 17.

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, version 17.

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

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.

SnowMirror uses two databases.

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.

SnowMirror runs on all modern web browsers such as Google Chrome, Mozilla Firefox and Internet Explorer 8 or higher.

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

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.

Optionally, you can install SnowMirror as a service. The service will automatically start when operating system starts.

If you have installed SnowMirror manually from an archive file, just follow these steps.

We upgrade Java regularly. However, we don’t upgrade with every new version. In case you decide to upgrade Java to the latest version yourself, please follow the steps below.

We upgrade Apache Tomcat regularly. However, we don’t upgrade with every new version. In case you decide to upgrade Apache Tomcat to the latest version yourself, please follow the steps below.

If you choose an internal database as a security realm you have to create administrator account. You will use these credentials to login into SnowMirror. The account will have all permissions granted.

You can also choose timezone in which all dates will be presented to you. It is a setting of the user interface and does not affect how date are stored in database.

If you choose LDAP as a security realm you have to:

The meaning of all the field is explained in LDAP chapter.

This is the default and recommended setup. One installation is Active and the second one is Passive. No additional settings is required.

Only one (the Active) installation is running the synchronizations. The second one is waiting and kicks in only if the first installation crashes and stops talking to the configuration database.

If you decide to set both installations as Active you have to consider how it will impact the performance of your ServiceNow instance. With Active-Active setup you can easily overload your ServiceNow instance.

Both installations run the synchronizations and therefore they utilize more ServiceNow resources. Let’s look at all the important properties you may have to tweak.

Node Count - each installation will connect to up to Node Count of ServiceNow nodes. Both installations may use the same ServiceNow nodes.

Sessions Per Node Count - each installation will create up to Sessions Per Node Count of session per ServiceNow node. With two Active installations in place, SnowMirror can create up to 2 * Sessions Per Node Count sessions per ServiceNow node.

Synchronizations Count - this property is shared among your installations. SnowMirror will not run more that Synchronizations Count number of synchronization in parallel.

Worker Threads Count - each installation will have its own worker threads. With two Active installations in place, SnowMirror can issue up to 2 * Worker Threads Count requests at the same time. This is where you can possibly overload your ServiceNow instance.

HTTP Connections Count - each installation will have its own connection. With two Active installations in place, SnowMirror will create up to 2 * HTTP Connections Count HTTP connections

You can tackle the overload issue by setting the appropriate properties (Sessions Per Node Count, Worker Threads Count, HTTP Connections Count) to two times smaller values.

On the downside, if only one synchronization is running it have a smaller number of threads available. Therefore, it is not as fast as possible. If at least two synchronizations are running in parallel, such a problem does not exist.

For SnowMirror to be able to send notifications SMTP server has to be configured. On the page Settings / Notifications Management / SMTP Server you can specify its URL, port and credentials and security option.

Security option defines if and how the communication with SMTP server is encrypted:

At the bottom of the page there is a button called Test Connection. It validates the configuration and send testing email to the email address you provide it the dialog window.

To create a new notification you need to provide an e-mail address. You can also choose specific synchronization you want to be informed about. If you want to receive information about all synchronizations, leave the Synchronization column on default All Synchronization option.

All added notifications are in a notification table. To cancel sending of notifications you can delete them by selecting a checkbox next to desired email address and clicking on Delete button.

Let’s look at the events you may be notified about.

SnowMirror provides three authentication options.

To configure which security realm you want to use, go to Setting → User Management and click the "Configure Security Realm" button.

Choose "Internal Database" in the Security Realm field. Then, don’t forget to create a user Create a New User with administrator permissions before you log out. Otherwise, you’d lock yourself out and would not be able to login and change settings.

LDAP configuration is a bit more complicated than Internal database so let’s look at all the attributes in detail.

After you fill in all the fields, you should test your configuration using "Test Connection" button. This is really important because if the configuration is invalid you would lock yourself out and won’t be able to login to SnowMirror at all.

After Test connection popup window opens, provide credentials of the user you will use to log in to SnowMirror. We will test if the user can log in and what permissions are assigned to him.

If everything went fine, you will see a green message. If something goes wrong, we print an error message.

SnowMirror supports Single Sing-On over SAML 2.0 protocol and Web SSO profile.

If you use Internal database security realm, you can create a new user. You have to provide its username, password, timezone and roles. See User Roles chapter so that you can decide which role you want to assign to the user. There is usually no need to add more than one role (except for the API Caller role).

On user detail page you can see user’s information summary - his or hers username, selected timezone, roles and permissions.

On the background, SnowMirror downloads meta-data about tables (names, columns, data-types, etc.). For better performance, it caches the meta-data so that it does not have to connect to ServiceNow every time it needs it.

To clear the cache manually, go to Settings menu, choose General Settings and click on Clear All Caches button.

Activity Log Retention removes old activity logs after the specified number of days (30 days by default). It removes activity logs from both configuration database and filesystem. Removing logs from filesystem saves you disc storage whereas removing logs from configuration database improves its performance. This is particularly true if you have a lot of synchronizations running very often.

If you are upgrading from SnowMirror < 3.2.0, this feature is disabled. On new installations it is enabled. You can change the settings on General Settings page.

Allows you to configure consistency check. On fresh installations the consistency check is enabled by default. On existing installations it is disabled.

Snow Mirror keeps an audit log of important events. This option allows you to control which events should SnowMirror audit.

Directories allow you to change directories where attachments, backups and activity logs are stored. Note, that SnowMirror does not move any files after changing the paths.

By default, SnowMirror stores data to mirror database in UTC. UTC is the most convenient and recommended way to store dates and times especially if your organization spans across several timezones. If you need to access and see date and time fields formatted in specific time zone, SnowMirror provides two ways to achieve that:

Allows you to change a type of SnowMirror installation you are currently working on.

The change of the Type is automatically picked up by SnowMirror in a few minutes.

License key is generated string (about 600 characters long) which includes information about SnowMirror application. If you don’t have a license, you can get a trial key on our website.

SnowMirror needs access to both the database and cloud storage. First, we store the data into CSV files. Then, we load it into database table.

SnowMirror needs access to both the database and cloud storage. First, we store the data into CSV files. Then, we load it into database table.

Database
* Server - Address of your database server without a port. An example: yourserver.sql.azuresynapse.net
* Port - Port number on which the database is available. By default, it is 1433.
* Instance - A name of your SQL Server Instance. You should provide either instance name or a port.
* Database - Name of your database.
* Schema - Name of your database schema
* Username - A username to use to access the database.
* Password - Password to use to access the database.
* *Require SSL - Communication with Redshift is always encrypted.

Azure Storage Account

MySQL is a relational database. You can use your own on-premise server, or MySQL in AWS RDS or Azure. We also support AWS Aurora and MariaDB.

Snowflake is an analytical database which always runs in cloud.

SQL Server is a relational database. You can use your own on-premise server, or SQL Server in AWS RDS or Azure.

Amazon S3 is a cloud storage where we store data as CSV files.

SnowMirror needs to be able to read the bucket and work with objects in that bucket. See sample policies that you may have to set up in AWS Console: policy file for S3 bucket with default SSE-S3 encryption, policy file for S3 bucket with SSE-KMS encryption.

Azure Storage is a cloud storage where we store data as CSV files.

Google Storage is a cloud storage where we store data as CSV files.

In this section you can export your synchronization settings or import your previously exported setting. Note that only settings is exported - the actual data in mirror database stay intact.

In case imported file contains synchronizations which already exist SnowMirror will let you choose how to resolve the conflict:

Please note that it is necessary to restart SnowMirror to apply all the performance settings changes.

Node Count - Number of ServiceNow nodes that can be utilized for downloading the data. If you don’t know how many nodes your ServiceNow instance has, click the Discover Nodes button.

Most of the production and almost all the sub-production instances have only two nodes and personal development instances consist of only one node. ServiceNow can increase the number of nodes for production instances according to their operation procedures. Typically, bigger instances or instances with higher load have more nodes. Please note that this number is not under ServiceNow customers’ control. It is fully driven by ServiceNow infrastructure team, and the number can vary over time.

It is recommended to check the node settings from time to time because the number of active nodes can change on the ServiceNow side.

Configuring a lower number of nodes than available is not an issue. Simply, only part of the ServiceNow cluster will be utilized for replication. However, configuring more nodes than available will result in ineffective session management and higher load on available ServiceNow nodes than intended. This cannot be recommended, and it is considered as a misconfiguration on the SnowMirror side.

Edit Advanced Settings - Enable advanced settings only if you are sure what you are doing! Misconfiguration can severely impact performance of your ServiceNow instance. Please contact SnowMirror support to consult the changes.

Sessions Per Node Count - Number of concurrent sessions per ServiceNow node. Each node has a certain number of semaphores, by default 4. This setting also means the max number of semaphores to utilize. Important: Increasing this number might impact other ServiceNow integrations. Default is 2.

Please note that each ServiceNow node has a certain number of so-called integration semaphores (by default 4). This is basically the number of concurrent integration requests that the node can handle at the same time. If all semaphores are in use, then all the new incoming requests are being queued and have to wait until a semaphore is available again.

ServiceNow infrastructure team can modify the number of integration semaphores. However, this cannot be requested, ServiceNow does it according to their own operation procedures (i.e. according to the load of the instance).

Increasing the number of sessions per node improves the replication performance, but it might negatively impact other integrations.

Worker Threads Count - Total number of threads for downloading the data from a ServiceNow instance. This thread pool is shared across all synchronizations. Recommended value is Node Count x Sessions Per Node Count.

If the number is higher than the recommended value, then the threads might be blocked by the number of HTTP connections anyway. Increasing this number does not make much sense. The only theoretical situation might be very slow mirror database which would utilize the threads more than just with the HTTP traffic.

HTTP Connections Count - Maximum number of concurrent HTTP connections to ServiceNow. Typically, equals to the number of worker threads. Recommended value is Node Count x Sessions Per Node Count.

If the number is higher than recommended (together with worker threads) then it effectively increases the load of ServiceNow nodes. The same as increasing the number of sessions per node, only worse way. Increasing this number does not make much sense.

Synchronizations Count - Number of synchronizations that can run in parallel. Other synchronizations must wait in a queue.

The replication throughput is limited by the worker thread pool anyway. So, this number does not affect the performance at all. It only means how big is the number of threads for the main scheduler. Increasing the number to very high numbers might have memory consumption consequences and results in slower SnowMirror.

You should not set this to a value higher than 32. Otherwise, you may run out of connections to the configuration database.

Mirror DB Max. Pool Size - Maximum size of a connection pool managed by SnowMirror. Should be higher than the number of worker threads.

Data Threads Count - Total number of threads dedicated to data processing. Data processing includes inserts/updates/deletes of data in mirror database. This thread pool is shared across all synchronizations. Recommended value is the same value as Worker Threads Count.

DB Commit Batch Size - Size of a database batch statement. This is the number of records being inserted at once in the mirror DB. Default is 250. Recommended value is the same as Records Batch Size.

DB Read Batch Size - Size of a database batch statement. This is the number of records being selected at once in the mirror DB. Default is 250. Recommended value is the same as Records Batch Size.

Keys Batch Size - Number of sys_ids downloaded in a single request. Default is 10,000. Increasing this batch size usually does not have significant performance effect.

Higher numbers will result is longer response/transaction times which is not optimal from the ServiceNow perspective. Each table might give different results.

Records Batch Size - Number of full records downloaded in a single request. Default is 250. Increasing this batch size usually does not have significant performance effect.

Higher numbers will result is longer response/transaction times which is not optimal from the ServiceNow perspective. Each table might give different results.

The performance page contains Discover Nodes button. This is useful if you don’t know how many nodes your ServiceNow consists of.

ServiceNow does not provide the number of nodes. Therefore, SnowMirror sends requests repeatedly and checks the established sessions. Based on the cookies content we can discover how many nodes responded to us.

Before tuning the configuration, you should click the Validate button to find out if the configuration is valid or not. Please note that a misconfiguration can negatively impact ServiceNow performance.

If you changed the configuration, and you are not sure if it is correct you can always go back. There is the Restore Defaults button which sets all the properties to its default values.

In case you need our help with analyzing the stats, you can download stats into a text file and send them to us by an email.

The file can be downloaded by clicking "Download" link on the top of the page.

Monitors a pool of HTTP connections which are used for communication with ServiceNow.

Monitors a number of threads in which synchronizations are executed.

Monitors data processing thread pool.

Monitors sessions which are use for communication with ServiceNow.

Example:

In this example, SnowMirror uses two ServiceNow nodes and keeps two sessions on each one.

Monitors connections to mirror database.

Monitors request and response times. The stats are split into multiple sections - the first one shows stats for all requests on all nodes. The others show stats only for the individual nodes.

Example:

In this example:

^since 4.9.7 Provides information about status of SnowMirror Monitor.

For changing timezone click on the planet icon next to timezone in the left bottom.

When you create a new database, you can specify a character set (what character is the DB able to store) and collation (how the DB sorts the characters). See our requirements in the table below.

SnowMirror needs the following database permissions:

If you want to encrypt communication between SnowMirror and your database, you have to set config.jdbc.encryption property.

Usually, Enforce Strict Security is enabled. If that is your case, you need to specify the roles for your ServiceNow user which is used for connection from SnowMirror. See the chapters below.

If Enforce Strict Security option is disabled all users have access to all SOAP operations and are able to use SnowMirror application without any configuration changes. User does not need any roles to access any of the tables in this mode.

SnowMirror requires read access to several system tables and the tables you are going to be mirroring. Therefore, you have to create a new role and grant it all required permissions.

We provide you with and an update set which creates all necessary roles and ACLs for you. You can do that work manually too.

Depending on which API (SOAP, REST) you use, you need a different roles assigned.

Starting from Fuji release, you will have to set Allow access to this table via web services in the table definition for the tables that you wish to synchronize. By default, all system tables do have this option enabled.
If you do not allow this option, you will face 403 Forbidden exception in synchronization Activity log.

If you use REST API for communication with ServiceNow you can utilize OAuth2 protocol for authorization. OAuth2 allows SnowMirror to access your ServiceNow instance using access tokens rather than passing credentials with each request. OAuth2 defines several ways (so called "grants") how clients can obtain access tokens. SnowMirror uses Resource Owner Password Credentials grant.

Before you start using OAuth2 you have to register SnowMirror in your ServiceNow instance. This chapter describes how to do that.

This chapter contains a short overview of Basic and OAuth2 authentication methods.

This chapter describes if and when your ServiceNow data is encrypted or un-encrypted.

You can ignore the warning and continue to SnowMirror. The better thing to do is to use your own trusted certificate. See next chapters to learn how to do that.

SnowMirror is configured to use HTTPS, but it uses a default untrusted certificate. This guide shows how to import your own certificate into SnowMirror.

The certificate being imported must contain both public key and private key. Usually, they are bundled in a single PFX or P12 file. You have to import the file into snowMirror-https.jks file. You can do it from command line as follows.

This chapter describes how to generate a new key pair (public key and private key) and how to use it instead of the default one.

When you generate a new public/private key, you need to have it signed so that it shows up as trusted in your browser. To sign it, you may be asked to generate CSR (Certificate Signing Request). Here’s how to do it:

When your certificate authority approves your request, it provides you a response. You have to import that response to snowMirror-https.jks file.

You may receive a response in multiple different formats. Based on the format of your response, follow the instructions below.

To get data from the audit log, you’re expected to connect to your configuration database and query it using SQL. See description of the audit table below.

SnowMirror recognizes following events.

By default, ServiceNow grants you up to 60 seconds to process a request. After 60 seconds, the requests times-out. Usually, that is enough. However, sometimes it may be necessary to increase this time-out limit. You can do that in your ServiceNow instance by configuring Transaction Quotas.

This chapter explains, how to exclude your user from the default quota and how to create a new quota specifically for SnowMirror.

By default, SnowMirror calls SOAP API and REST API with certain parameters and HTTP headers. If you wish to specify your own parameters and HTTP headers, please go to Settings → Advanced Properties page and change following properties.

Synchronizations may be configured to automatically check for schema changes using Auto Schema Update Settings. They may also notify users about those schema changes. How does SnowMirror works with the meta-data cache when Auto Schema Update or Notifications are enabled?

Every time a synchronization is executed, SnowMirror clears meta-data of that synchronization from cache. Because of that, schema changes are discovered as soon as possible and that is really nice. On the other hand, SnowMirror has to make requests to ServiceNow to download the meta-data. SnowMirror installations with plenty of synchronizations or aggressive schedules may benefit (performance-wise) from making less meta-data requests.

You can change that behavior on Settings → Advanced Settings page by setting "snowMirror.cache.clearBeforeSynchronization" property to false. With such settings, a synchronization do not clear cache every time it is executed. Therefore, the number of meta-data requests is minimized. Schema changes will be discovered with up to 24 hours delay.

In case the migration fails, please switch back to H2 database:

The chapters above describe, how to move SnowMirror installation from one server to another and keep your databases intact. In this chapter, we describe how to make a copy of your environment. For example, you have a testing (trial) environment, and you want to create an exact copy of that environment.

Creating a new virtual machine and making a copy of your databases is out of context of this documentation. Once you have a copy of your databases, follow the instructions below.