How to replace the Java Client with the xMatters integration agent

This article explains how to modify an existing deployment to use the xMatters integration agent instead of the Java Client.

Issue Summary

In some cases, an existing deployment may change in a way that causes it to no longer meet the requirements for a Java Client deployment; for example, if the operating system is upgraded. This article explains how to configure the integration agent to host an implementation for an existing Java Client integration.

Resolution

Step One:

Configure an integration service on the event domain related to the deployed integration that will be set up to use the integration agent instead of the Java Client. This is configured in the xMatters web user interface on the event domain details page.

If you cannot configure an integration service, you may be missing the required licenses: contact your xMatters administrator.

NOTE:

For advanced integrations that use the xMatters mobile access component (formerly known as the Mobile Gateway), an integration service should already exist. Note that you cannot re-use this integration service; you must create a new integration service for legacy mode. The recommended naming convention for this is to use the event domain name, appended with "_legacy"; e.g., "bmcim_legacy". For the remaining instructions in this article, use the new integration service name, NOT the legacy version.

Step Two:

Create a new subdirectory for the integration service under the integrationservices directory in the integration agent installation folder. The naming convention for the subdirectory should indicate which integration it contains by using the integration service name created in Step One. For example, the BMC Impact Manager integration would use the event domain name, bmcimxap, as specified in the integration guide.

Step Three:

Copy the Java Client integration file (usually the XML file found in the components/alarmpoint-java-clientdirectory in the integration archive package) to the subdirectory created in Step Two. For example, the BMC Impact Manager integration file would be /integrationservices/bmcimxap/BMC-Impact-Manager.xml.

Add the mapped-input data required by the integration agent to the top of the xml file. (For an example of this content, see the attached BMC-Impact-Manager.xml file.)

Step Four:

Create a new integration service configuration file in the subdirectory you created in Step Two. The name of the file should match the name of the related integration service created in Step One. This file can be generated by referencing one of the example integrations, such as "ping", or by following the instructions in the xMatters integration agent guide.

For example, the BMC Impact Manager integration would require a file called bmcimxap.xml created under /integrationservices/bmcimxap that contained the following content (note the addition of the mapped-input parameter and data):

<?xml version="1.0" encoding="utf-8"?>
<integration-service version="1.0" xmlns="http://www.alarmpoint.com/schema">
   <domain>bmcimxap</domain>
   <name>bmcimxap</name>
   <initial-state>active</initial-state>
   <script lang="js">
     <!--
      | The relative path (resolved against the directory containing this file), of
      | an empty file.  The file must exist, but its contents will be ignored.
      |
      | NOTE: The path may be Unix or Windows-formatted, although it is
      | recommended that Unix-formatting be used since it works under
      | both environments.
      |
      | NOTE: Depending on the OS, paths may be case-sensitive.
      +-->
      <file>bmcimxap.js</file>
   </script>
   <javaclient>
     <!--
      | The relative path (resolved against the directory containing this file),
      | of a JavaClient integration XML.
      |
      | NOTE: The path may be Unix or Windows-formatted, although it is
      | recommended that Unix-formatting be used since it works under
      | both environments.
      |
      | NOTE: Depending on the OS, paths may be case-sensitive.
      +-->
      <file>BMC-Impact-Manager.xml</file>
   </javaclient>
   <classpath/>
   <mapped-input method="add" subclass="action">
     <parameter type="string">person_or_group_id</parameter>
     <parameter type="string">severity</parameter>
     <parameter type="string">incident_id</parameter>
     <parameter type="string">sim_cell</parameter>
     <parameter type="string">host_address</parameter>
     <parameter type="string">client_address</parameter>
     <parameter type="string">mc_host</parameter>
     <parameter type="string">mc_object</parameter>
     <parameter type="string">mc_object_class</parameter>
     <parameter type="string">mc_parameter</parameter>
     <parameter type="string">mc_tool</parameter>
     <parameter type="string">mc_tool_class</parameter>
     <parameter type="string">causes</parameter>
     <parameter type="string">effects</parameter>
     <parameter type="string">message</parameter>
     <parameter type="string">priority</parameter>
     <parameter type="string">status</parameter>
     <parameter type="string">event_class</parameter>
</mapped-input>
</integration-service>

NOTE: The XML File format is explained in greater detail in the  xMatters integration agent guide, in the Integration Service Configuration File section.

Step Five:

Create an empty Javascript file in the subdirectory  you created in Step Two. The name of the file should match the name of  the script file listed in Step Four. For example, the /integrationservices/bmcimxap/bmcimxap.xml file created in Step Four list the script file name as bmcimxap.js.

Step Six:

The integration service configuration needs to be referenced in the integration agent configuration file. Open the IAConfig.xml file in the /conf directory and add a new path element under the service-configs element that points to the integration service configuration file created in Step Three. For example, for the BMC Impact Manager integration service, the entry would resemble the following:

<path>bmcimxap/bmcimxap.xml</path>  

Step Seven:

Restart the integration agent, if it was running, to pick up the new changes.

Management System Configuration

All Java Client integrations use the APClient.bin.exe as the submission mechanism into xMatters. You will need to update the file to point to the installation path of the integration agent. This process should be described in the integration documentation.

Mapped Data

When using the APClient.bin to submit requests to the Java Client, the first mapped data parameters always refers to the target event domain. In the integration agent, this parameter must be the name of the integration service. By convention, the event domain and integration service usually share the same name, however this is not a requirement and they can have different values.

xMatters Reference

DTN-2457, SUP-4499, JDN-1167

Originally created by Don Clark

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk