First, you will need to stop the DataSync Agent.
Next, make sure that you have backed up your local agent files, namely the files in the conf directory in your Perspectium Replicator Agent directory.
You will also need to request the latest Agent Installer from Perspectium Support.
To start upgrading your DataSync Agent, choose from below:
Upgrading the Agent through the command line
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-datasync-installer.jar.
The following is for Linux only.
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
Upgrading the Agent through the Agent Installer
Open the Agent Installer .jar file. If you didn't receive this file, you can request one from Perspectium Support. A pop-up may appear indicating that the Agent Installer file can't be opened because it is from an unidentified developer. If this happens, click OK to close the pop-up and then navigate to System Preferences > Security & Privacy. Under the General tab, locate the section beginning with Allow apps downloaded from: and click Open Anyway. Then, click Open in the resulting pop-up to open the Agent Installer wizard.
Check the box to accept the terms of the Perspectium End User License Agreement. Then, click Next.
Choose a directory to install the DataSync Agent files in. If you specify a new directory, that directory will first be created and then populated with the Agent files. Then, click Next. On the resulting window, you will be asked to choose the directory where your Java JDK or JRE is installed. In most cases, you can accept the default directory here and then click Next.
NOTE: If you are installing the agent in an existing directory, ensure that you have made backups of your local files.
Type a name for your DataSync Agent; e.g., datasyncforservicenow_to_mysql. Then, choose an option from the Replicator Type dropdown:
| Choose... | If sharing data to a... |
|---|---|
| MySQL_Replicator | MySQL database |
| MSSQL_Replicator | Microsoft SQL database |
| Oracle_Replicator | Oracle database |
Finally, click Next to proceed to the next step.
On the resulting page, enter the following to allow your DataSync Agent to authenticate when connecting to the Perspectium Integration Mesh:
| Field | Information to enter |
|---|---|
| Server | Your Perspectium Integration Mesh URL (excluding "http://", "https://", "amqp://", or "amqps://") e.g., us-east-3-dev.perspectium.net |
| User | Username used to connect to the Perspectium Integration Mesh |
| Enter Password | Password used to connect to the Perspectium Integration Mesh
|
| Retype Password | Password used to connect to the Perspectium Integration Mesh |
| Queue Name | Name of the queue that will store data being shared from your ServiceNow instance to your database. Simply replace the yourqueue text here with the name of your ServiceNow instance; e.g., dev12345 |
| Encryption/Decryption Key | A key of 24+ characters (for base64, TripleDES, and AES-128 encryption) or 32+ characters (for AES-256 encryption), including spaces, which will be used to encrypt data being shared from your ServiceNow instance to your database. |
| Max Reads | A maximum number of data messages that your DataSync Agent will read from the queue each time messages are processed |
| Polling Interval (sec) | Time period (in seconds) for which your DataSync Agent will process messages from your shared queue |
Then, click Next to continue to the next step.
On the resulting page, enter the following information to allow your DataSync Agent to connect to and authenticate with your ServiceNow instance and database server:
| Field | Information to enter |
|---|---|
| Instance | Your ServiceNow instance URL (excluding "http://" or "https://") |
| User | Username used to log into your ServiceNow instance (in firstname.lastname format) |
| Enter Password | Password used to log into your ServiceNow instance |
| Retype Password | Password used to log into your ServiceNow instance |
| Server | Server URL for the database you will be sharing your ServiceNow instance data to (excluding "http://" or "https://") |
| Port | Port number for your database |
| User | Username used to log into your database |
| Enter Password | Password used to log into your database |
| Retype Password | Password used to log into your database |
| Database | Name of your database schema |
Then, click Next to continue to the next step.
On the Summary and Review screen, wait for the processes to finish running and then click Next. Then, on the Perform External Processes screen, wait for the processes to complete and then click Next.
Finally, on the Installation Finished screen, click Done to finish installation of your DataSync Agent.
NOTE: Optionally, you can Generate an automatic installation script on this screen and then choose a directory to save your install script in. This script can then be run on another device to install a DataSync Agent with the same settings you've specified here.
The following system files will be installed within the bin/perspectium_data directory and used for temporary storage/caching when your DataSync Agent is running:
- psp.in.agent.errors
- psp.in.messageset
- psp.out.servicenow.INSTANCE_NAME (where INSTANCE_NAME is from your https://INSTANCE_NAME.service-now.com URL)
- psp.in.servicenow
- TableStatsPublisher
A perspectium.log file will also be installed that contains important log messages for your DataSync Agent. For more information, see monitoring DataSync Agent logs.
NOTE: If the files listed above exceed 1 GB in size, you may delete these files to improve your DataSync Agent performance.
If you created backups of your files, navigate to the directory where your agent is installed, and replace the configuration files. These will typically be your agent.xml and your log4j.xml files.
(Optional) After installing your DataSync Agent, it is highly recommend to confirm that you Agent is configured correctly by running the Agent validateConfiguration tool.
To run the validateConfiguration tool on a Linux device, open a terminal window and change your current directory to the directory where you installed your DataSync Agent files. Then, change your current directory to Perspectium_Replicator_Agent and execute the following command:
bin/validateConfiguration start
To run the validateConfiguration tool on a Windows device, navigate to the bin directory that was installed within the main Agent directory that was specified in Step #3. Then, double-click to run the validateConfiguration.bat file.
Upgrading Java for the agent
Here are the instructions to follow if you're upgrading your Java version in a Windows machine, or moving from 32-bit to 64-bit Java.
- Stop the DataSync Agent
Modify the path for Java
At the bottom of wrapper.conf file, there should be the following lines corresponding to the installed directory of Java and your current version:set.JAVA_HOME=C:\Program Files\Java\jre1.8.0_131
Modify the set.JAVA_HOME variable to the location of your new version of Java. For example, if you are upgrading the version reflected above (Java 1.8.0_131) to version 1.8.0_144, you would modify like so:set.JAVA_HOME=C:\Program Files\Java\jre1.8.0_144
Start the DataSync Agent
Warning
If you did not perform these steps, and the version of Java was upgraded on the Agent's VM, then it will run into issues. It will likely crash and fail to start up.