Upgrading to a new version of the Integration Agent

This article explains how to upgrade from a previous installation of the xMatters Integration Agent to the latest version, and how to migrate any existing integrations running on your existing version.

Note: For detailed system requirements, and installation instructions for new deployments, refer to the online documentation. 

Conventions

This article uses the <IAHOME> placeholder to refer to the Integration Agent installation folder. For example, in a default Unix installation of the Integration Agent version 5.1.8, the IAConfig.xml file is located in /opt/xmatters/integrationagent-5.1.8/conf 

To simplify this reference and account for potential differences in the actual installation folder, the documentation would refer to the folder and file as <IAHOME>/conf/IAConfig.xml

Process overview

Because the xMatters Integration Agent does not include an installer, patching an existing Integration Agent installation requires only that you extract the latest version of the Integration Agent archive onto your server, and then migrate selected files from your existing deployment. This ensures that you will have a working Integration Agent to fall back on if you encounter complications while configuring the new version.

The procedure described in this document will help you upgrade your agents as quickly and efficiently as possible. It is best to install the new Integration Agent on the same server as the existing one, and keep them both in place until you're sure that the new one is working properly.

This provides several benefits:

• It simplifies the task of migrating data from the old agent to the new one.
• It minimizes downtime.
• It allows you to easily rollback your changes if something isn't right.

Incompatible versions

The following files have been modified in recent releases of the Integration Agent, and older versions of these files are incompatible with the 5.1.8 and later releases:

If you are upgrading from an older Integration Agent and have customized or modified these files, your changes must be manually migrated into the new files.

NOTE: This release of the Integration Agent includes changes to the mule.sh file. If you have modified this file, you will need to merge your changes with the file included in the patch.

It is strongly recommended that you complete these steps on a non-production or staging environment before attempting to upgraded your production deployment. You will need to repeat these steps for each Integration Agent in your deployment. 

Upgrading the Integration Agent on Windows

1. Install the new Integration Agent (including the JRE and the Integration Agent Utilities).
   • The files can be downloaded from here.
   • Consult the Integration Agent Quick Start Guide for installation steps (you can stop after the "Install the Integration Agent and IAUtils" and "Add a JRE to your Integration Agent installation location" steps - you'll complete the configuration in the steps below).
2. Make a backup copy of the new agent's conf folder; e.g., conf.oob.
3. Copy the files from the old Integration Agent's conf folder to the new agent's conf folder, EXCEPT for log4j.xml and activemq.xml
4. Copy the integrationservices folder to the new Integration Agent.
5. Stop the old agent.
   • Open a command prompt with administrator privileges, navigate to the new Integration Agent's bin folder, and type sc stop apia
6. Start the new Integration Agent in console mode, and test.
   • In the same command window, type start_console.bat
7. When you're satisfied that the new agent is working properly, delete the Windows service that automatically starts the old agent, and install a Windows service to auto-start the new Integration Agent:
   • In the command window, use Ctrl-C to stop the Integration Agent, then type remove_service.bat
   • In the same command window, type install_service.bat

Upgrading the Integration Agent on Unix

1. Install the new Integration Agent (including the JRE and the Integration Agent Utilities).
   • The files can be downloaded from here.
   • Consult the Integration Agent Quick Start Guide for installation steps (you can stop after the "Install the Integration Agent and IAUtils" and "Add a JRE to your Integration Agent installation location" steps - you'll complete the configuration in the steps below).
2. Make a backup copy of the new agent's conf folder; e.g., conf.oob.
3. Copy the files from the old Integration Agent's conf folder to the new agent's conf folder, EXCEPT for log4j.xml and activemq.xml
4. Copy the integrationservices folder to the new Integration Agent.
5. Stop the old agent.
   • Open a terminal prompt, navigate to the old agent's bin folder, and stop it using the stop_daemon.sh script (or press Ctrl-C if the agent was invoked with the start_console.sh script.)
6. Navigate to the new agent's bin folder, start the new Integration Agent using start_console.sh, and then test.
7. When you're satisfied that the new Integration Agent is working properly, stop the agent by pressing Ctrl-C.
8. If your old agent was configured to automatically start and stop as a service, update your scripts so that they invoke the new Integration Agent instead of the old one.

Common issues

• When installing an Integration Agent on Windows, the JRE must be version 1.8.x and it must be the 32-bit architecture. The agent will not start if you use a 64-bit JRE or a higher version than JRE 1.8. If you aren't sure whether you have a 32-bit JRE, open a command prompt in <IAHome>\jre\bin and type

java.exe -d64

The response should be

Error: This Java instance does not support a 64-bit JVM.

Specific information about Java and JREs is in the Integration Agent guide.

• For installations on Linux, we recommend 64-bit Java. The version must be 1.8.x.
• On Linux, the folders containing the agent must belong to the same user account that will be starting and stopping the Integration Agent. We recommend that you install and run the agent as a non-root user.
• If you install the new agent on the same server as the old one (as we recommend), then you won't be able to start the new agent until the old one has been shut down (or vice versa.) This is because both agents will be trying to use the same ports. Remember to stop one agent before trying to start the other one.

Troubleshooting

Issue:

The Integration Agent fails to start, and the logs indicate a "Base64" error similar to the following:

Cannot import "Base64" since a property by that name is already defined.

Answer:

This occurs because the Integration Agent version 5.1.8 uses Java 1.8, which offers new functionality, and includes a class called Base64. Previous Integration Agents used earlier versions of Java which did not include this class, and therefore had to explicitly import Base64 from another source.

Contact xMatters Support for help with this problem.

Issue:

Attempting to get the status of the Integration Agent returns an error similar to the following (line breaks added for legibility):

./iadmin.sh get-status
 
The command could not be executed because of the following problem:
com.alarmpoint.integrationagent.exceptions.GetStatusException: 
The Integration Agents status could not be determined because of an exception.
If this exception was thrown while executing a different command (e.g., suspend),
then that command succeeded. Consult the log file for further details.

Answer:

You are running another instance of the Integration Agent that is using the ports required by the new Integration Agent. Make sure you have properly stopped ALL running Integration Agent processes or services, and then restart your Integration Agent. (For reference, the ports in question are defined in the IAConfig.xml file.)

Additional resources

• For more trouble shooting tips, refer to Using the Support-Zip Tool to Troubleshoot Integrations.
• For assistance with any other issues, contact xMatters Customer Support.