SnowMirror Administrator Guide

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.

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

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

Non-active Columns

It can download only 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.

Emojis

Ignores 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

To activate the plugin, open ServiceNow instance as an administrator.
Search for Plugin application in menu bar and open application.
On the top of the page type plugin name "aggregate" in search box and hit ENTER.
Check if the plugin Status is ACTIVE otherwise open the plugin.
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 Redshift^since 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 Synapse^{since 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.
Snowflake^since 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 S3^since 5.0.0	✓	It can be used as a mirror database. It cannot be used as a configuration database.
Azure Storage^since 5.0.0	✓	It can be used as a mirror database. It cannot be used as a configuration database.
Google Cloud Storage^since 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

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.

Run the Installer - Go to a location to where you downloaded SnowMirror installation file and run it.
First Step - Simply click next.
License Agreement - Please go through a license agreement and then confirm by clicking on "I agree".
Selecting the action - Select "Express Install" option and click next.
Summary - Here you can see summary. It shows installation location, used ports, Windows service and such.
Installing - Window with a progress bar.
Finish - Final screen. After clicking on "Finish", your default browser will be opened and application itself will load.

2.2.2. Custom installation

Run the Installer - Go to a location to where you downloaded SnowMirror installation file and run it.
First Step - Simply click next.
License Agreement - Please go through a license agreement and then confirm by clicking on "I agree".
Selecting the action - Select "Custom Install" option and click next.
Selecting the Location - If you would like to install SnowMirror into a location different to default one, feel free to click "Browse" and select your desired location. Once you are done selecting a location, just click "Next".
Configuring Ports and Host - This screen is here for you to change host name and ports.
- HTTP Port Number - this is the port where you can access SnowMirror through your browser
- Control Port Number - this is the port that receives shutdown requests
- Host Name - together with HTTP port you will use this to access your SnowMirror from a browser
- Installation Name - name of this SnowMirror installation. If you are installing SnowMirror in a cluster you have to choose a different name for each installation. The name is used for distinguishing the installations.
- Installation Id - related to a cluster. Leave it empty if you are not using a cluster. If you are installing a first installation in a cluster, leave this empty. For any subsequent installation copy contents of "snow-mirror/data/installationId" file to this field.
Selecting the Database - Here you choose can which database you are going to use

This step is about selecting configuration database. If you wish to read more about mirror db, please see mirror db section

Now you can input information necessary to correctly set mirror database.
- Database Type: Choose a database you are going to use
- Server: Address of a server where the database is running
- Port: A port on which the database is running
- Database: Database name, SID etc.
- Username: username of a database user through which the SnowMirror is going to access the database
- Password: password for that user
  
  Postgres, SQL Server - If you wish to use different schema than public, it is possible too. Just fill the field Schema with the name of your desired schema.
Setting the Service - If you want to run SnowMirror as a service, leave the checkbox checked. Windows service is good if you want to run SnowMirror automatically after the operating system starts up. You can change the service name. This is useful if you need to install multiple instances of SnowMirror.
You can also change the system account under which the service will be running, e.g. if you create a special account on server just for running a SnowMirror.
Summary - Here you can see summary. It shows installation location, used ports, Windows service and such.
Installing - Window with a progress bar.
Finish - Final screen. After clicking on "Finish", your default browser will be opened and application itself will load.

2.3. Windows Silent Installation

^since 4.8.0 A silent installer allows you to automate SnowMirror installation. It does not have a user interface. Instead, you run it from a command line.

To run the installation in a silent mode, you have to provide "/S" parameter. Here is how you run it:

start /wait snow-mirror-1.2.3.exe /S

Silent Installer Parameters

Parameter	Description
LicenseAccept*	Do you accept the license agreement? Values: Y
Action	What do you want to do? Values: install, upgrade install = new installation upgrade = upgrade existing installation to a new version Default value: install
Dir	Absolute path where to install SnowMirror? Default value: C:\Program Files\SnowMirror
ServiceInstallation	Do you want to install SnowMirror as a Windows service? Values: Y, N Default value: Y
ServiceName	Name of the service. Default value: SnowMirror
ServiceAccountUser	Name of the account to run the service. Default value: LocalSystem
ServiceAccountPassword	Password of the account to run the service. If you are using the default LocalSystem, you must not provide any password.
ConfigDbType*	What kind of database server do you want to use? Values: mysql, mssql, oracle, postgres, h2
ConfigDbDriver	On SQL Server, you can choose which JDBC driver to use to connect to your DB. Values: jtds, microsoft. Default value: microsoft
ConfigDbServer	Network name of your database server.
ConfigDbName	Name of your database.
ConfigDbPort	Port number where you can reach the database server. Values: 0 - 65535
ConfigDbSchema	Name of your database schema. Default value on SQL Server: dbo
ConfigDbInstance	Name of your SQL Server instance.
ConfigDbSid	SID of your Oracle database.
ConfigDbService	Service name to use to connect to your Oracle DB.
ConfigDbUsername	A username to use to log in to your database.
ConfigDbPassword	A password to use to log in to your database.
ConfigDbSsl	Do you want to use encrypted SSL connection? Available for SQL Server, MySQL, MariaDb and PostgreSQL. Values: IGNORE - Do not configure SSL at all. Default settings of the database driver is used. NONE - Use unencrypted connection. SSL - Use encrypted connection. If not supported by the server, raise an error. SSL_WITH_CERT_VERIFICATION - Use encrypted connection. If not supported by the server, raise an error. Verify that server’s certificate is signed by a trusted CA. Default value: IGNORE
Scheme	Protocol to use to connect to SnowMirror. Values: http, https Default value: http
Host	Hostname on which SnowMirror will be accessible. Default value: name of your computer
Port	Port number on which SnowMirror is accessible. Default value: 9090
ControlPort	Port number on which SnowMirror receives shutdown requests. Default value: 8005
InstallationName	Name of this SnowMirror installation. Useful only if you want to utilize HA cluster. Default value: SnowMirror
InstallationId	Identifies SnowMirror installation. In HA cluster, all nodes share the same Installation Id. If you do not use HA cluster, you can leave the field empty. Default value is empty.
JvmMs	Memory allocated by SnowMirror after it starts in MB.
JvmMx	Maximum memory that SnowMirror can allocate in MB.

Parameter

Description

LicenseAccept*

Do you accept the license agreement? Values: Y

Action

What do you want to do?

Values: install, upgrade

install = new installation
upgrade = upgrade existing installation to a new version

Default value: install

Dir

Absolute path where to install SnowMirror? Default value: C:\Program Files\SnowMirror

ServiceInstallation

Do you want to install SnowMirror as a Windows service?

Values: Y, N
Default value: Y

ServiceName

Name of the service. Default value: SnowMirror

ServiceAccountUser

Name of the account to run the service. Default value: LocalSystem

ServiceAccountPassword

Password of the account to run the service. If you are using the default LocalSystem, you must not provide any password.

ConfigDbType*

What kind of database server do you want to use? Values: mysql, mssql, oracle, postgres, h2

ConfigDbDriver

On SQL Server, you can choose which JDBC driver to use to connect to your DB. Values: jtds, microsoft. Default value: microsoft

ConfigDbServer

Network name of your database server.

ConfigDbName

Name of your database.

ConfigDbPort

Port number where you can reach the database server. Values: 0 - 65535

ConfigDbSchema

Name of your database schema. Default value on SQL Server: dbo

ConfigDbInstance

Name of your SQL Server instance.

ConfigDbSid

SID of your Oracle database.

ConfigDbService

Service name to use to connect to your Oracle DB.

ConfigDbUsername

A username to use to log in to your database.

ConfigDbPassword

A password to use to log in to your database.

ConfigDbSsl

Do you want to use encrypted SSL connection? Available for SQL Server, MySQL, MariaDb and PostgreSQL.

Values:

IGNORE - Do not configure SSL at all. Default settings of the database driver is used.
NONE - Use unencrypted connection.
SSL - Use encrypted connection. If not supported by the server, raise an error.
SSL_WITH_CERT_VERIFICATION - Use encrypted connection. If not supported by the server, raise an error. Verify that server’s certificate is signed by a trusted CA.

Default value: IGNORE

Scheme

Protocol to use to connect to SnowMirror.

Values: http, https

Default value: http

Host

Hostname on which SnowMirror will be accessible. Default value: name of your computer

Port

Port number on which SnowMirror is accessible. Default value: 9090

ControlPort

Port number on which SnowMirror receives shutdown requests. Default value: 8005

InstallationName

Name of this SnowMirror installation. Useful only if you want to utilize HA cluster. Default value: SnowMirror

InstallationId

Identifies SnowMirror installation. In HA cluster, all nodes share the same Installation Id. If you do not use HA cluster, you can leave the field empty. Default value is empty.

JvmMs

Memory allocated by SnowMirror after it starts in MB.

JvmMx

Maximum memory that SnowMirror can allocate in MB.

2.4. Installation On Linux

Create SnowMirror directory /opt/SnowMirror. You are free to choose a different directory.
```
mkdir /opt/SnowMirror
```
Download Java Runtime Environment (JRE) and SnowMirror and put them to the /opt/SnowMirror/tmp folder.

Java is available on https://adoptium.net/temurin/releases/ page - download "Linux x64" package. Use OpenJDK 17.

SnowMirror ZIP package is available on our website.

In the scripts below, we use upper-case text CURRENT_JRE_VERSION and CURRENT_SNOW_MIRROR_VERSION. Please replace it with an actual version of Java and SnowMirror.
1. Unpack both JRE and SnowMirror:
  cd /opt/SnowMirror/tmp tar zxvf jre-CURRENT_JRE_VERSION-linux-x64.tar.gz unzip snow-mirror-CURRENT_SNOW_MIRROR_VERSION.zip
2. Copy the content of JRE to /opt/SnowMirror/jre and the content of SnowMirror to /opt/SnowMirror.
  cp -r /opt/SnowMirror/tmp/jreCURRENT_JRE_VERSION/. /opt/SnowMirror/jre cp -r /opt/SnowMirror/tmp/snow-mirror-CURRENT_SNOW_MIRROR_VERSION/. /opt/SnowMirror
3. Remove temporary folder
  cd /opt/SnowMirror rm -rf /opt/SnowMirror/tmp

Edit snowMirror.properties

snowMirror.host property - by default, it is set to "localhost". That means, you can access SnowMirror only from the machine where you installed it. If you want to be able to access SnowMirror from outside this machine, set the property to its network name. See Application URL Configuration for details on how to change the host name.

Provide a connection to your configuration database:

Database Server	config.db.type	config.jdbc.url
SQL Server	mssql	jdbc:jtds:sqlserver://SERVER:PORT/snowmirror;instance=INSTANCE-NAME
Oracle	oracle	jdbc:oracle:thin:@SERVER:PORT:SID jdbc:oracle:thin:@SERVER:PORT/SERVICE-NAME
MySQL	mysql	jdbc:mysql://SERVER:PORT/snowmirror
PostgreSQL	postgres	jdbc:postgresql://SERVER:PORT/snowmirror
H2 (Embedded)	h2	jdbc:h2:~/h2/snowmirror

Database Server

config.db.type

config.jdbc.url

SQL Server

mssql

jdbc:jtds:sqlserver://SERVER:PORT/snowmirror;instance=INSTANCE-NAME

Oracle

oracle

jdbc:oracle:thin:@SERVER:PORT:SID
jdbc:oracle:thin:@SERVER:PORT/SERVICE-NAME

MySQL

mysql

jdbc:mysql://SERVER:PORT/snowmirror

PostgreSQL

postgres

jdbc:postgresql://SERVER:PORT/snowmirror

H2 (Embedded)

jdbc:h2:~/h2/snowmirror

Please, replace the bold parts in "config.jdbc.url" with actual values.

Also, provide username (config.jdbc.username) and password (config.jdbc.username).

Start SnowMirror.
```
/opt/SnowMirror/run.sh
```
Open SnowMirror in your favorite web browser on the following URL: http://VALUE-OF-snowMirror.host-PROPERTY:VALUE-OF-snowMirror.port-PROPERTY

The default value is http://localhost:9090.

2.4.1. Service Installation

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

Open Terminal
Copy a script responsible for starting and stopping SnowMirror init.d directory.
```
sudo cp /opt/SnowMirror/bin/init.d/snowmirror.sh /etc/init.d/snowmirror
```
Make the init script executable:
```
sudo chmod a+x /etc/init.d/snowmirror
```
Place symlinks in the run-level directories to start and stop this script automatically.
1. For Debian based systems:
  update-rc.d snowmirror defaults
2. For RedHat based systems:
  chkconfig --add snowmirror
  The snowmirror.sh script contains chkconfig settings

2.5. What Is Installed

We have described the installation process on both Windows and Linux server. Let’s have a look at files we installed.

File & Directory	Description
/snowMirror.properties	Main configuration file. Contains a connection to the configuration database and SnowMirror base URL. If you want to know more about setting a different base url or changing port, please see chapter Deployment URL
/snowMirror-https.jks	Contains a certificate and a private key. Used when you configure SnowMirror to use HTTPS protocol.
/run.bat	Starts SnowMirror on Windows. Used only if a service is not installed.
/run.sh	Starts SnowMirror on Linux.
/shutdown.bat	Stops SnowMirror on Windows. Used only if a service is not installed.
/shutdown.sh	Stops SnowMirror on Linux.
/Uninstall.exe	Uninstalls SnowMirror from Windows.
/Uninstall.info	Stores data needed for uninstallation.
/bin	Contains Apache Tomcat web server.
/conf	Apache Tomcat configuration files.
/jre	Java runtime environment binaries.
/lib	Apache Tomcat classes and libraries.
/license	License files.
/logs	Folder used for both SnowMirror and Tomcat logs.
/logs/activityLogs	Folder used for synchronizations logs. Each synchronization run has its own log file. The files are located by this pattern: <synchronizationId>/<yyyy-MM>/<logId>.log.
/snow-mirror	Contains all SnowMirror specific application files like configurations, WAR file, documentation and data directory for embedded H2 database and a folder for mirrored attachments.
/snow-mirror/data	When embedded H2 database is used, this folder stores database files.
/snow-mirror/docs	Folder contains SnowMirror documentation.
/snow-mirror/conf	SnowMirror configuration files. Do not modify. If you need no make a change, modify the main configuration file /snowMirror.properties.
/snow-mirror/monitor	Installation files for SnowMirror Monitor.
/snow-mirror/role	Update sets which create SnowMirrorAgent role and SnowMirrorRestApiAgent role.
/snow-mirror/webapp	SnowMirror war archive.
/webapps	Used by Apache Tomcat.
/work	Used by Apache Tomcat.

File & Directory

Description

/snowMirror.properties

Main configuration file. Contains a connection to the configuration database and SnowMirror base URL. If you want to know more about setting a different base url or changing port, please see chapter Deployment URL

/snowMirror-https.jks

Contains a certificate and a private key. Used when you configure SnowMirror to use HTTPS protocol.

/run.bat

Starts SnowMirror on Windows. Used only if a service is not installed.

/run.sh

Starts SnowMirror on Linux.

/shutdown.bat

Stops SnowMirror on Windows. Used only if a service is not installed.

/shutdown.sh

Stops SnowMirror on Linux.

/Uninstall.exe

Uninstalls SnowMirror from Windows.

/Uninstall.info

Stores data needed for uninstallation.

/bin

Contains Apache Tomcat web server.

/conf

Apache Tomcat configuration files.

/jre

Java runtime environment binaries.

/lib

Apache Tomcat classes and libraries.

/license

License files.

/logs

Folder used for both SnowMirror and Tomcat logs.

/logs/activityLogs

Folder used for synchronizations logs. Each synchronization run has its own log file. The files are located by this pattern: <synchronizationId>/<yyyy-MM>/<logId>.log.

/snow-mirror

Contains all SnowMirror specific application files like configurations, WAR file, documentation and data directory for embedded H2 database and a folder for mirrored attachments.

/snow-mirror/data

When embedded H2 database is used, this folder stores database files.

/snow-mirror/docs

Folder contains SnowMirror documentation.

/snow-mirror/conf

SnowMirror configuration files. Do not modify. If you need no make a change, modify the main configuration file /snowMirror.properties.

/snow-mirror/monitor

Installation files for SnowMirror Monitor.

/snow-mirror/role

Update sets which create SnowMirrorAgent role and SnowMirrorRestApiAgent role.

/snow-mirror/webapp

SnowMirror war archive.

/webapps

Used by Apache Tomcat.

/work

Used by Apache Tomcat.

If you want to make sure no directory is missing or you are not sure how SnowMirror installation should look like, please checkout the following directory structure. We omitted directories nested too deep and all files.

.
├── bin
│   ├── experimental
│   └── init.d
├── conf
│   └── Catalina
├── jre
│   ├── bin
│   ├── lib
│   ├── man
│   └── plugin
├── lib
├── logs
│   └── activityLogs
├── snow-mirror
│   ├── conf
│   ├── data
│   ├── docs
│   ├── license
│   ├── monitor
│   ├── trusted-certificates
│   └── webapp
├── temp
│   └── attachment
├── webapps
│   └── ROOT
└── work
    └── Catalina

2.6. Uninstall SnowMirror

2.6.1. Windows

Go to installation folder.
Open Uninstall.exe and follow the instructions.

2.6.2. Windows Silent

Open cmd.exe as an Administrator
Run "C:\Program Files\SnowMirror\uninstall.bat" I_Agree

(Do you see the I_Agree parameter? That is to confirm that you really want to uninstall SnowMirror.)

2.6.3. Linux

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

Stop SnowMirror
Delete "/opt/SnowMirror" directory.

2.6.3.1. Uninstall Linux Service

Open a Terminal.
Log in as root user.
Remove Service:
1. For Debian based systems:
  update-rc.d -f snow-mirror remove
2. For RedHat based systems:
  chkconfig --del snow-mirror

2.7. Post-Installation Steps

Especially in corporate environment, you may be concerned about security. To increase the security of SnowMirror installation, please follow the step below before you go through Configuration Wizard.

Enable communication via HTTPS.
SnowMirror uses Java. You can upgrade to the latest version and manage updates yourself.
SnowMirror uses Apache Tomcat. You can upgrade to the latest version and manage updates yourself.
Turn off advanced properties. See details of what they do in another chapter.

2.7.1. Java Upgrade

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.

Download the latest Java 17 from https://adoptium.net/temurin/releases/?version=17

On Linux, download tar.gz package. On Windows, download ZIP package (not "msi" package).
Download only JDK, not JRE. Use only the latest "11" version.
Stop SnowMirror
Rename "jre" folder to "jre-bak"
Unpack the new Java "jre" folder.

Import certificates into "cacerts" files:

Linux:

cd /opt/SnowMirror
if [ -f "snowMirror.jks" ]; then jre/bin/keytool -importkeystore -srckeystore snowMirror.jks -destkeystore jre/lib/security/cacerts -storepass changeit -srcstorepass changeit -noprompt; fi

Windows:

cd "C:\Program Files\SnowMirror"
IF EXIST "snowMirror.jks" jre\bin\keytool -importkeystore -srckeystore snowMirror.jks -destkeystore jre/lib/security/cacerts -storepass changeit -srcstorepass changeit -noprompt

Start SnowMirror

2.7.2. Apache Tomcat Upgrade

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.

Download the latest ZIP package of Tomcat 10: https://tomcat.apache.org/download-10.cgi
Stop SnowMirror
Rename folders:
- "bin" → "bin-bak"
- "conf" → "conf-bak"
- "lib" → "lib-bak".
Unpack "bin", "conf" and "lib" folders from the latest Tomcat package.
Copy:
- "bin-bak/setenv.bat" → "bin/setenv.bat"
- "bin-bak/setenv.sh" → "bin/setenv.sh"
- "conf-bak/web.xml" → "conf/web.xml"
- "conf-bak/server.xml" → "conf/server.xml"
- "lib-bak/tomcat-jasperlistener.jar" → "lib/tomcat-jasperlistener.jar"
Start SM

3. Running the Setup Wizard

When you access SnowMirror for the first time, you will be redirected to the configuration wizard. It will walk you through basic SnowMirror configuration. Once you finish the Configuration Wizard data will be stored to the database and SnowMirror will be immediately ready to use.

3.1. License

On this page you can provide a license which you received to your mailbox.

3.2. ServiceNow

This page allows you to enter information which SnowMirror uses to create connections to ServiceNow. You can see the most important settings right away. To see the less widely used settings you have to click the Advanced Settings checkbox.

After making changes you should click "Test Connection" button to verify the settings. The button tests whether SnowMirror can create a connection to ServiceNow and whether is is able to access the data it needs. If the tester complains about not having enough privileges to access data you will have to grant us the access directly in your ServiceNow instance.

3.3. Database

Allows you to configure connection to your mirror database where we store data from ServiceNow. We are able to store data into tables in relational database or into files in cloud storage

Database:
- Built-in database (evaluation only) - we store data into a file-based database. Useful only for quick evaluation.
- My own database server - allows you to connect to your database or cloud storage.
Database Type: Choose your database vendor or cloud storage. Click on your database vendor to see how to configure it.
- Relation databases: Amazon Redshift, Azure Synapse, MySQL, Oracle, PostgreSQL, Snowflake, SQL Server
- Cloud storages: Amazon S3, Azure Storage, Google Storage
Test Connection button: Click this button to check, whether we can reach the database or cloud storage, authenticate, read and write data.

3.4. SMTP Server

Application allows users to subscribe to synchronization notifications. To deliver email to these users the SMTP server must be configured. If you want to enable notifications please specify URL of SMTP server and credentials. You can test the configuration using Test Connection button.

3.5. Security Realm

SnowMirror provides two authentication options.

Internal Database - Users and their credentials are stored in configuration database. You manage the users, their credentials and permissions using Settings page.
LDAP - Users and their credentials are stored outside SnowMirror in your company’s LDAP (most usually Active Directory). You manage the users, their credentials and permission in your LDAP.

3.5.1. Internal Database

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.

3.5.2. LDAP

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

configure a connection to your LDAP server on this page
create SnowMirror roles in your LDAP (see LDAP Groups chapter and LDAP Sample Configuration chapters).

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

Always use Test connection button to verify your configuration. If you enter an invalid connection information, you lock yourself out, and you will not be able to login and change settings. Look at the screenshot above. We clicked the "Test connection" button, and we were able to login, and the user has a role assigned to him.

3.6. Summary

Here you can see a summary of all settings. If you want to change the configuration, you can do so by clicking on "Change *" in a particular section.

3.7. Finish

After clicking the "Finish" button SnowMirror stores and processes all the settings. The Login page shows up and SnowMirror is ready to use.