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.

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.

Upgrade the Integration Agent

The following steps explain how to upgrade your Integration Agent.

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. 

Step One: Install the new version 

1. Download the latest version of the Integration Agent from the Integration Agent page and extract the contents.

• If you are installing to a Unix environment, be sure to perform the extraction as the user that will be running the Integration Agent OR set the correct permissions to the folder and files in the Integration Agent directories.

• Note any known issues or other differences that may require additional changes to your current or new installation.

NOTE: You may also want to create a backup of the new <IAHOME>/conf directory; you will be modifying the contents of some files in this folder in the following steps.

Step Two: Install the latest Integration Agent utilities

The Integration Agent Utilities bundle (IAUtils) is a collection of scripts and binary code that provides required functionality for many integrations. The bundle is distributed separately from the main Integration Agent installer, but must be installed at the same time. If the IAUtils package is not present when the Integration Agent is started, the start up may fail.

1. Download the IAUtils package (integrationagent-utils-<version>.zip) from the Integration Agent page, and extract the contents to your new <IAHOME> directory.

• Allow the extracted lib and integrationservices folders to merge with the ones created by the Integration Agent extraction in Step One. 

For more information about the IAUtils, refer to the "Installation" chapter of the xMatters Integration Agent Guide.

Step Three: Copy configuration files

1. Copy the following files from the <IAHOME>/conf folder in your previous Integration Agent installation to the matching location in the new installation:

• IAConfig.xml
• deduplicator-filter.xml
• log4j.xml
• .wspasswd

Step Four: Copy integrations

1. Navigate to the <IAHOME>/integrationservices folder in your previous Integration Agent installation.
2. Copy each integration service folder (and all of its files) that you want to use in the new Integration Agent to the <IAHOME>/integrationservices folder.

You can return to this step and copy integrations to the new Integration Folder after you have completed the upgrade, but remember to stop and restart the Integration Agent afterwards.

Windows users only:  Remove the existing service, and ensure the new service is running prior to testing the integration.

1. Open a command window and navigate to the bin folder in your existing installation directory and run remove_service.
2. Navigate to the bin folder in the new installation directory and run install_service, then run start_service.

Step Five: Test your integrations with the new Integration Agent

To make sure that your configuration was correct and the Integration Agent was successfully upgraded, send and respond to a notification using one of your integrations. Once you've confirmed that the management system has received the updated, your upgrade is complete. 

If the Integration Agent does not work as expected, you can revert to the previous version until the problem has been resolved. For help, contact xMatters Customer Support

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.

For complete instructions on how to resolve this error, refer to the article "Integration Agent will not start due to "Base64" exception".

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

Issue:

Starting the Integration Agent generates a stack trace similar to the following (line breaks added for legibility):

2016-10-11 13:53:07,821 [WrapperSimpleAppMain] FATAL - Exit code 86: 
The Mule configuration located at ./conf/mule-config.xml contains an error. 
Reason: MuleManager Failed to initialise (org.mule.config.ConfigurationException)
com.alarmpoint.integrationagent.exceptions.ExitCodeException: Exit code 86: 
The Mule configuration located at ./conf/mule-config.xml contains an error....
Caused by: org.dom4j.DocumentException: 
Error on line 15 of document : cvc-elt.1.a: Cannot find the declaration of element 'deduplicator'. 
Nested exception: cvc-elt.1.a: Cannot find the declaration of element 'deduplicator'.

Answer:

This is due to the deduplicator-filter.xml file not being up to date; i.e., it is from an Integration Agent prior to version 5.1.3. To confirm that your file is correct for this version, open it in a text editor and locate the following line (approximately line 14):

<deduplicator xmlns="http://www.alarmpoint.com/schema"> 

If this line does not exist, or contains a different value, you will need to replace it with the deduplicator filter supplied in the Integration Agent archive and manually transfer your filter settings from the deduplicator-filter.xml file in your previous installation.

Issue:

Attempting to connect the Integration Agent to xMatters On-Demand returns a registration error.

Answer:

This is likely due to a mismatch between your Integration Agent ID and the xMatters Access Control List (ACL). Repeat Step Six above, and ensure that xMatters Support has added your correct Integration Agent ID to the ACL.

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.