The Perspectium Replicator Agent leverages two java virtual machine instances, or processes, to run.

The java processes can be started as a service or interactively through the executables in the bin folder.

When you are provisioned your credentials you may have been given two different addresses. Such as:

• https://user.perspectium.net
• amqps://user.perspectium.net

The choice between these different protocols will vary per customer (largely firewall rules). ServiceNow does not handle AMQP connections so do not use it as the endpoint URL for any of your <instance_connection> directives.

There are no issues with replication between different versions of the update sets and agents. The core structure of the messages we send across has been consistent across version releases.

We have included a tool to easily gather the common files (configurations and logs) that the Support team requests during troubleshooting. Running this and attaching it with the initial issue request will help speed up the troubleshooting process.

Within Windows it can be run by double clicking the createReport.bat file, V3.18.0.

The tool can be run at the command line of the root Perspectium directory, not bin, and will output a line telling you if it ran successfully and the name of the generated .zip file. The file will contain the name of your agent and the current date.

# Windows Systems
bin\createReport.bat
Report successfully generated as file: ReplicatorReport.name.date.zip
 
# OS X and Linux Systems
bash bin/createReport

The files included are:

• /conf/agent.xml
• /conf/config.xml
• /conf/log4j2.xml
• /conf/wrapper.conf
• /logs/* (all the logs)
• /bin/(instance schemas)

Note: It will package the files as they are, so if you have unencrypted sensitive data within them then you should edit the files appropriately before creating the report.

With the release of V3.12.0 we have included a tool to help validate the current configuration of your agent.xml. When launched it will test access to the default and configured message bus connections. It will display other diagnostic information for your current agent name, version, and tasks. It will also test your connection to your database and outside instances such as ServiceNow as necessary.

By default you will connect to our our monitor.perspectium.net server for monitoring data. So unless you have specified your Heartbeat and Reporting connection you will see the attempts to connect here.

For Windows in V3.17.0 go to the bin folder of the agent's installed directory and double click on the validateConfiguration.bat file. This will automatically run the configuration validation test.

The tool can be run at the command line of the root Perspectium directory, not bin, like so:

# Windows Systems
bin\validateConfiguration.bat
 
# OS X and Linux Systems
bash bin/validateConfiguration

Here is an example of a successful validation:

Successful Subscribe

Configuration Validation Report: Fri Feb 02 09:13:40 PST 2018

Agent Information:
	Agent version: Argon_3270
	Agent name: 'example_agent'

Configured Tasks:
	Task: example_agent_subscribe Type: subscribe
		example_agent_subscribe instances: 4

		Attempting to connect to the Message Broker Service at: amqps://example.perspectium.net as user: myUser - SUCCESS
		Attempting to connect to the database: psp_repl at host: localhost port: 3306 as user: myUser - SUCCESS
		Attempting to fetch schema from: https://example.service-now.com- SUCCESS
	
Validation Completed, results: SUCCESS

Report has been saved in file: ConfigurationValidationReport.log

Here is an example of a failed validation:

Failed Validation. The user will be unable to Subscribe or Share

Configuration Validation Report: Fri Feb 02 09:18:58 PST 2018

Agent Information:
	Agent version: Argon_3270
	Agent name: 'example_agent'

Configured Tasks:
	Task: example_agent_subscribe Type: subscribe
		example_agent_subscribe instances: 4

		Attempting to connect to the Message Broker Service at: https://example.perspectium.net as user: badUser - *** FAILED ***
		Verify your firewall has port 443 open for outbound traffic.
		Verify your <message_connection> entry is properly configured.
		Attempting to connect to the database: psp_repl at host: localhost port: 3305 as user: badDBUser*** FAILED *** Unable to connect to database: Cannot create PoolableConnectionFactory (Communications link failure
		The last packet sent successfully to the server was 0 milliseconds ago. The driver has not received any packets from the server.)
		Verify your database parameters are properly configured.
		Attempting to fetch schema from: https://example.service-now.com- SUCCESS
	
Validation Completed, results: *** FAILED ***

The errors above show a failure to create connections to both MBS and the database, while the connection to the instance was fine. In this case the failures were just due to bad credentials and using the wrong port to connect to my database (3305 instead of 3306).

• Double check your endpoint URL and credentials. If correct, please contact Perspectium support

Europium

As of the Europium release, the Perspectium Replicator Agent supports MySQL 8. With this upgrade, heightened validation occurs with respect to how the Agent handles foreign characters (specifically, UTF-8 characters with 3+ bytes), and character encoding can differ between the Agent and local databases. As a result, you may be unable to replicate foreign characters to certain columns such as the incident column. The reason for this change is that the MySQL Connector/J driver only supports encoding for 3-byte UTF-8 characters instead of the standard 4-byte.

If you are replicating foreign characters (UTF-8 characters with 3+ bytes) to a local database using the Perspectium Replicator Agent, you will need to set the value for the default-character-set property in your MySQL configuration file to utf8mb4.

• Troubleshooting for Replicator Agent Installation Errors
• Troubleshooting for Replicator Agent Configuration Errors