The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.
This knowledge base article is designed to help you (and your xMatters consultant!) convert older (APXML-based) integrations to use the xMatters REST API, allowing access to xMatters communication plans, with their modern drag-and-drop forms, advanced message layout features, flexible response options, and more.
This conversion is an important factor for anyone still using Action Script-based integrations, given our announcement about the end-of-life for Action Script.
Older integrations generally accept notification requests from APClient.bin, which prepares a message to be sent to xMatters by the Integration Agent. The Integration Agent receives the request in an enhanced XML format called APXML, and typically the Integration Agent will enhance the request before sending it to xMatters.
The APXML message format is not compatible with the xMatters REST API in xMatters On-Demand. Fortunately, the Integration Agent can convert APXML messages to JSON format, which is suitable for sending to communication plans.
The following links contain more information about the topics discussed in this article:
- xMatters 5.x documentation - visit this page to download the latest xMatters Integration Agent guide. It contains lots of information about using the Integration Agent with both APXML and the REST API.
- xMatters REST API - our complete reference for all things REST.
- On-Demand online help - everything you need to know about configuring and using xMatters On-Demand.
- xMatters integrations - check here to see if there is already a communication plan or REST-based integration available for the product you are integrating with.
Converting your integration will require several steps:
- Install or import the latest communication plan into your xMatters hosted instance.
- Update your Integration Agent scripts so that they work with the new communication plan.
- Update the Integration Agent settings on the management system.
If there is a newer version of your integration that includes a communication plan, then you can install it on the xMatters instance and much of your work will be done. Then you'll just need to ensure that the fields in the communication plan form match the properties that the Integration Agent sends in its REST post.
If there is no communication plan for the integration that you are working with, you can import the communication plan from the "Sample Relevance Engine" distributed with the Integration Agent. Once you've imported this communication plan, you can populate the form with fields that match the properties sent from the Integration Agent, and you can create outbound integration webhooks that meet your needs.
You'll also need to create an integration user account with the REST Web Service User role. You'll need this User ID and password when updating the integration service on the Integration Agent. For instructions on how to do this, along with a host of other helpful tips for preparing xMatters On-Demand for integrations, see Configuring xMatters in the Integration Directory help.
You will need to update the Integration Agent scripts to send notification requests via REST posts instead of via APXML messages. For this to succeed, you will need to add a configuration file containing the integration user's credentials mentioned above, plus the URL of the communication plan to which the notification requests will be sent. Also, the integration will need to be moved to the "applications" event domain.
Only one minor change will be required on the components on the management system: the name of the integration's event domain will need to be updated.
Because every integration is different, the following steps attempt a best-practices overview of how best to convert an APXML integration to use the REST API.
1. Create an integration user
If you haven't already, create an integration user with the REST Web Service User role for your integration, as described here.
Be sure to make a note of the user's credentials.
2. Import or create the communication plan in On-Demand.
Do one of the following:
- If there is an existing packaged integration for the product you are integrating with, import it into your On-Demand instance.
- If you are working with a product for which there is no existing packaged integration, create a new one or import the "Sample Relevance Engine" plan. (You can find sampleRelevanceEngine.zip in the <IAHOME>\integrationservices\applications\sample-relevance-engine folder of any Integration Agent.)
Once your plan is created or imported, add the integration user to the Sender Permissions for each form in the plan.
While you're in the web user interface, make sure the form is deployed for web services, and then grab the Web Service URL for the form and copy it to a handy text file. (You'll need these URLs to configure the Integration Agent.
3. Upgrade the Integration Agent
If you haven't already, upgrade your Integration Agent to the latest version and test your existing integration to make sure that it is working correctly. (Nothing worse than trying to convert an integration that doesn't actually work!)
4. Prepare and modify the configuration files
Follow these steps to update the configuration files in the Integration Agent:
- Copy your integration folder from <IAHOME>\integrationservices to <IAHOME>\integrationservices\applications (this is now the <current integration folder>).
- Copy the configuration.js file from <IAHome>\integrationservices\applications\sample-relevance-engine into <current integration folder>.
- Using the instructions in the Integration Agent guide (or this KBA), create an encrypted password file containing the integration user's password in <current integration folder>.
- Open the configuration.js file in a text editor and make the following changes:
- Set the value of the WEB_SERVICE_URL parameter to the Web Service URL of the communication plan form.
- Set the value of the INITIATOR parameter to the User ID of your integration user.
- Set the value of the PASSWORD parameter to the path and filename of the encrypted password file.
- Save and close the configuration.js file.
- Open your Integration Agent's IAConfig.xml file and locate the <path> tag within the </service-configs> section near the end of the file. This tag indicates the location of your integration scripts, so change it to point to the new location within the applications folder. For example, you would change <path>generic/generic.xml</path> to <path>applications/generic/generic.xml</path>. Make sure to save the file.
- Open the integration's XML definition file (using the same example as the previous step, this would be <IAHOME>\applications\generic\generic.xml). Within the XML file, change the value of the <domain> tag to "applications"; i.e., change <domain>generic</domain> to <domain>applications</domain>.
5. Update the integration scripts
Now you can update the integration scripts.
First, open the main integration script and add the following lines immediately after the final import or load instruction (which ever comes last):
Now, to update the main integration script to use the REST API, do one of the following:
If the integration receives notifications via apclient.bin:
At the end of the apia_input function, replace
If the integration receives notifications via HTTP POST:
Near the end of the apia_http function, comment out the submitAPXML instruction and append the following:
6. Clean up the last few bits
The last step is to update the management system to make sure it's calling the "new" integration.
On the management system, change the event domain that is specified when the Integration Agent is invoked. In most integrations, the management system invokes apclient.bin with the "--map-data" argument. In these cases, the first argument will be the integration service name; for example:
apclient.bin --map-data generic <followed by the rest of the parameters>
If this is the case for your integration, add "applications|" before your integration service name; for example:
apclient.bin --map-data "applications|generic" <the rest of the parameters>
Note: The double-quotes and the vertical bar are required.
In integrations such as BMC Remedy or HP OMi, where the Integration Agent is invoked via HTTP request, you will need to update the URL to include "applications_".
For example, if the URL is "http://localhost:8081/http/bmcremedy40_bmcremedy40", change it to "http://localhost:8081/http/applications_bmcremedy40".
For the HP Service Manager integration, in the AlarmpointConfig script, ensure that the "xmatters_servicemanager_im_domain" variable begins with "applications\"; i.e.:
If you're not sure where to make these changes, check the guide for your integration.
7. Restart and test!
Make sure to restart your Integration Agent, and then test your integration to make sure it's working.
xMatters internal reference: DTN-6935