User Tools

Site Tools


This is for installing the Replicator Agent on windows systems for versions 3.24.0 and under. For the newer Argon versions and above see here.

Agent Installation on Windows Systems


First off, you should have received a ZIP file such as the following:

Contact if you have not received this file. You may also download from the Agent Releases page if you know which version to get.


Once you've unzipped the file you should have a file called: perspectium-replicator-installer.jar. This is the file we will use to run the agent installer.

Agent Requirements

These are the requirements needed to ensure that your agent can be executed properly and has the ability to be upgraded in the future.


System Requirements
Memory 8GB minimum
Processor Cores 4 minimum
Hard Disk Space 100GB minimum
Network Interface GigE

Network Access

The Replicator agent requires only outbound access to the Perspectium cloud and the ServiceNow instance.

Perspectium products require that your firewall settings allow traffic to and from your Perspectium MBS. This can be through any one of the following three ports: AMQP, AMQPS, or HTTPS. You will specify which protocol you will be using through the URL of the <message_connection>.

The Agent also requires that your firewall settings allow traffic to and from your ServiceNow instance. To test this access you can consult this page.

Network Requirements
AMQPS Outbound Port TCP/5671 outbound to your Perspectium MBS (amqps://
AMQP Outbound Port TCP/5672 outbound to your Perspectium MBS (amqp://
HTTPS Outbound Port TCP/443 outbound to your Perspectium MBS (
HTTPS Outbound Port TCP/443 outbound to your ServiceNow instance


Both 32 and 64 bit versions of Java are supported. The Java version must be Java 8 or higher. As of the Fluorine release, Java versions 9 and 10 are supported. It's strongly recommended that you use a server type JVM instead of a client or desktop version.

A 32 bit version of Java is required if you're running the agent on a Windows server for Agent versions under 3.24.0.

You can determine that Java is in your current path and the version by issuing the following command from the command prompt:

java -version

If you don't see something like the following then please contact your system administrator for help.

java version "1.8.0_181"

Make note of the path to Java. One way to determine the path to Java on most linux distros is to issue the following command:

which java

On Windows this is typically located in “C:\Program Files \Java\…”

On either windows/linux the installer will generally find the path to the java installation and auto-fill this for you.

Verify that Java is in your PATH system (environment) variable as some installations of Java may not add it properly. If it is not there, add the path of the JRE's bin direct as indicated here.

Supported Databases

Database Version
Oracle 11g, 12c Release 1: 12.1 -
SQL Server (MSSQL) 2012, 2016 recommended
MySQL 5.6 - 8.0 supported in Europium
SAP Hana SPS 12
Amazon Redshift 4.0-4.1
Amazon Aurora (MySQL compatible) N/A
IBM DB2 11
HP Vertica 8.0 - 9.21
PostgreSQL 42.2.6
Snowflake 3.9

NOTE: Perspectium uses the newest version of each of the associated JDBC drivers, which are included with the install.

NOTE: Perspectium strongly recommends placing the Agent on the same local area network as the database server.

Supported Operating Systems

The following OS versions are supported by the Replicator Agent:

OS Version
Windows Professional & Home 7 - 10
Windows Server 2012 - 2016
Linux Ubuntu 14.04 and 16.04


You should make note of the following settings before starting the installation. The installer will prompt you for them:

General Installer Settings
Installation Path The directory you wish to install to
Java Path java -version
Perspectium Cloud Server, User, and Password Credentials for your agent to access our cloud server

Contact if you did not receive these
Agent Name A name for your agent as provided by Perspectium or as desired
Decryption Key This should match the Encryption Key you specified in the Properties page of the Perspectium ServiceNow Application
SQL Replicator Settings
ServiceNow Instance, User and Password ex:
Database Server, Port, User, Password, Database Name Settings to connect to you database
File Replicator Settings
FileName The file you wish to replicate
Directory Replicator Settings
Directory The directory you wish to share from

The instance user name/ID cannot be an SSO user, it must be a local user that is given the 'perspectium' role and can invoke a processor.

Running The Installer

If you are running the installer to upgrade your agent and previously installed the agent to run as a Windows service, please stop the service before running the installer. The Windows service will have the same name as your agent's name.

To run the installer on windows, double-click on the perspectium-replicator-installer.jar file. Answer the prompts with the settings you identified above.

Sample Installer Prompts (Agent version 3.1.13)

Installer Prompt when selecting the dropdown option other. Allows for User to enter a database type (Agent version 3.17.0)

Generating an automatic installation script

After successful installation of the agent, the user is given an option to generate an automatic install script on the last panel of the agent installer. This is useful to install an agent on another machine using the same settings.

Sample Installer Prompts (Agent version 3.2.3)

You can execute the auto-install.xml by running the following command:

java -jar perspectium-replicator-installer.jar auto-install.xml

Validating Your Configuration

After initial installation you can look at your configuration within the agent.xml file of the conf directory. Here you will see a generic task set up with the credentials you have just input. You can either run it now, however, it is recommended to run our tool to test and validate your current connections. It will run through your Message Bus Connections, Database Connections, and Instance Connections (to ServiceNow or elsewhere) as you have prescribed.

Following these connections it will notify you which pieces failed as well as other diagnostic information about your current configuration. To see how to run this test see here.

Installation as a Service

Since we want the Replicator agent to run all the time we'll want to do a few simple tasks to ensure that it will be automatically started when the computer is started. You should also validate that the Agent is working fully before installing it as a service.


First, let's ensure that the replicator agent will run after we've made the necessary configuration changes.

These bat files may need to be run by someone with administrator privileges and you will be prompted to verify that the command should be run as administrator.

This can be done by performing the following from within the bin directory (perspectium-replicator-agent/bin) double click on the file:


This command won't actually start the agent but it will let us know that it's not running which is important. Within the output of the command you should see the running status of the agent.


First, let's stop the agent by issuing the double clicking on StopAgent.bat. You should see a message stating that the agent is being stopped, and a message when it is stopped.

Stopping Perspectium Replicator Agent...
Stopped Perspectium Replicator Agent.

Double click on the file InstallAgent.bat to install the agent as a service.

That's it! Please refer to the Replication Agent configuration documentation to further leverage the Perspectium Replicator Agent.

Installing Multiple Agents

During the installation process you are prompted for the Agent's name, when installing the Agent as a service it will utilize this name. This name can also be found and edited within the wrapper.conf.

If you want to install multiple agents as services on the same machine, you will need make sure that each Agent has a unique as the Service Name.

For more details see here

Upgrading the Agent

Argon or newer versions

Note: The user must copy and paste the created auto-install.xml along with the perspectium-replicator-installer.jar in the same folder or directory and issue the command stated above. The command can be issued in the command prompt of the system.

If you are upgrading a previously installed agent to a newer release, you will need to stop the currently running agent. Once the agent is stopped, you may proceed to run the install procedure described above. Note that if you generated an automatic installation script with your previous installation, you can run the installer from the command line and pass the automatic installation file as a parameter. Doing so will cause the installer to run and use all the settings you specified in the previous installation. You will not be prompted for this information.

To run the installer with an auto installation script, open a command window and change to the directory where the new installer jar file resides. Next you should locate the auto installation script from your previous install. It is usually in the top directory of the agent installation and if you accepted the default name will be called “auto-install.xml”.

Once you know the location, copy and paste the auto-intall.xml into the same folder or directory as the perspectium-replicator-installer.jar. Now you can run the following command making sure to use the correct name of the installer jar file:

java -jar perspectium-replicator-installer.jar auto-install.xml
replicator_agent_installation_win_legacy.txt · Last modified: 2017/10/13 11:06 by jackson.davenport