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