Handling Integration Agent script processing errors with apia_discard

Integration scripts can fail to process notification requests for a variety of reasons, such as malformed or missing data, failed HTTP requests to the management system*, or syntax errors in scripts. These processing errors can result in the failure of notification delivery.

Most integration services do not have a mechanism to send an alert when request processing fails, but this capability can be added to existing integrations by implementing an apia_discard function.

*The apia_discard function also handles response and annotation data coming from xMatters to the Integration Agent. If this data cannot be processed, then it is handled by apia_discard in the same fashion as notification request data from the management system.

Integration script retries and apia_discard

When processing errors are encountered, the Integration Agent retries the failed operation two more times, and then attempts to invoke the apia_discard function. At this time a message is written to the Integration Agent log: "INFO - Calling JavaScript method apia_discard."

Despite the slightly misleading name, the apia_discard function doesn't actually discard the data; instead, it provides an alternative set of script instructions that can be used to process the data if the main integration script doesn't succeed.

If the apia_discard function does not exist, then a message is written to the Integration Agent log and the notification data is discarded.

By adding an apia_discard function, you can cause your integration service to send an alert to you when notification data cannot be processed. Depending on the type of integration and your specific requirements, you can arrange for the unprocessed data to be sent to you via your main integration service or by a different integration.

Sending unprocessed request data via the original integration service

You may want to simply send a notification to your existing xMatters event domain, containing the unprocessed data that caused the error. The example below accomplishes this objective:

/*                                                                 */
/*  Example apia_discard function                                  */
/*                                                                 */
function apia_discard(apxml, exception, numAttempts, createTimestamp)
{
	ServiceAPI.getLogger().error("APIA_Discard: Discarding APXML " + apxml + "\nafter " + numAttempts + " attempts to process.  APXML created at time: " + (new java.util.Date(createTimestamp)).toString() + ".  \nException is: \n" + exception.getMessage());

	// Designate the xMatters user who will receive the discarded data and error details
	apxml.setToken("person_or_group_id", "bsmith");

	// Add the exception data to the data that will be sent to xMatters
	apxml.setToken("apia_discard_exception", exception.getMessage());

	// Send the original data plus the exception message to xMatters.
	return apxml;
}

You can simply paste the above code into your main integration script. For example, if you are using the CA Spectrum integration:

  1. Back up your main integration script (e.g., <IAHome>\integrationservices\caspectrum-2-0\caspectrum.js) and then open it with a text editor.
  2. Paste the above code at the end of the file.
  3. Change "bsmith" to the xMatters user ID of a suitable administrator.
  4. Save the file.
  5. Restart the Integration Agent.

Note: The "return apxml" instruction at the end of the above function causes the Integration Agent to send the notification request to the same integration service in xMatters that received the notification request from the management system. In other words, if the notification request was sent to the CA Spectrum integration service on the Integration Agent, but the notification data could not be processed, then the data will be sent to the CA Spectrum integration service on the xMatters server.

Using a different integration service to send the unprocessed data

If your existing integration is not suitable for this type of notification, then you can use a different integration. For example, the "Generic" integration service is included with every Integration Agent and xMatters instance and provides a simple way to send one-way notifications to a user or group.

/*                                                                                    */
/*  Example apia_discard function (with redirection)                                  */
/*                                                                                    */
function apia_discard(apxml, exception, numAttempts, createTimestamp)
{
	ServiceAPI.getLogger().error("APIA_Discard: Discarding APXML " + apxml + "\nafter " + numAttempts + " attempts to process.  \nException is: \n" + exception.getMessage());

	// Designate the xMatters user who will receive the discarded data and error details
	apxml.setToken("person_or_group_id", "bsmith");

	// Add the exception data to the data that will be sent to xMatters
	apxml.setToken("message", "The following data could not be processed and has been discarded:\n" + apxml + "\nafter " + numAttempts + " attempts to process.  \nException is: \n" + exception.getMessage());

	// Redirect the data plus the exception message to be delivered to xMatters by the generic integration
	ServiceAPI.sendAPXML(apxml, "generic", "generic");
}

Add the code to your integration as described above (don't forget to change the userID of the recipient).

In this case you will notice that the "return apxml" instruction has been replaced with "ServiceAPI.sendAPXML". This causes the notification request data to be sent to a different integration service in xMatters than the one that received the data from the management system. In other words, if the notification request was sent to the CA Spectrum integration service on the Integration Agent, but the notification data could not be processed, then the data will be sent to the Generic integration service on the xMatters server.

Note: You may need to do a couple of things to activate the Generic integration on your Integration Agent and your xMatters instance. The process is very simple and is described in the "Enabling the Generic integration" section of the article, Sending alerts when script processing fails.

Integration services that don't use apclient.bin

The above instructions will work if your integration receives its notification requests via the apclient gateway (i.e., if your management system uses apclient.bin** to send notification requests). Alternatively, if your management system sends notification requests via direct HTTP post to the Integration Agent (typically via port 8081), then your apia_discard script will need to be slightly different:

/*                                                                 */
/*  Example apia_discard function for apia_http integrations        */
/*                                                                 */
function apia_discard(httpRequestProperties, exception, numAttempts, createTimestamp)
{
	importClass(Packages.org.apache.commons.httpclient.Header);
	importClass(Packages.org.apache.commons.httpclient.HttpVersion);
	importClass(Packages.org.mule.providers.http.HttpResponse);

	//  Create a response to be sent back to the management system
	var response = new org.mule.providers.http.HttpResponse();
	response.setStatusLine(HttpVersion.HTTP_1_1, 400);
	response.setBodyString("The request was discarded due to " + exception + " after " + numAttempts+ " attempts");

	ServiceAPI.getLogger().error("APIA_Discard: Discarding notification data after " + numAttempts + " attempts to process.  \nException is: \n" + exception.getMessage() );


	// Create a new apxml message to send via xMatters
	var apxml = ServiceAPI.createAPXML();
	apxml.setMethod("ADD");
	apxml.setSubclass("action");
	apxml.setToken("message", "A notification request could not be processed by the integration service.  The exception was: \n" + exception.getMessage() + "\nand the request body from the management system is: \n" + httpRequestProperties.getProperty("http.request") );

	// Designate the xMatters user who will receive the discarded data and error details
	apxml.setToken("person_or_group_id", "bsmith");

	// Redirect the data plus the exception message to be delivered to xMatters by the generic integration
	ServiceAPI.sendAPXML(apxml, "generic", "generic");

	// Send an error response to the management system
	return response;
}

For example, if you are using the HP BSM/OMi integration:

  1. Back up your main integration script (e.g., <IAHome>\integrationservices\hpomi-3-0\hpomi.js) and then open it with a text editor.
  2. Paste the above code at the end of the file.
  3. Save the file.
  4. Restart the Integration Agent.

**A rare exception is the HP Service Manager integration, which receives its notification requests via the apclient gateway but does not use apclient.bin. In the case of the HPSM integration, one of the APXML-based implementations of apia_discard can be used.

Apia_discard and non-legacy integrations

The above examples are specific to "legacy" integrations (i.e., integrations in which the Integration Agent does not use the REST API to send the notification requests to xMatters). However, the newer REST-based integrations will also make use of an apia_discard function (if one is present) when notification data cannot be processed. The above script examples can be used as templates for a REST-based integration.

REST-based integrations can coexist with legacy integrations, so it is entirely possible to have a REST-based integration running on the same Integration Agent as a legacy integration. This means that you can use the Generic integration service to deliver notification request data that could not be processed by a REST-based integration service.

Testing and validation

To confirm that the apia_discard function works as expected, you can use the following code to force a processing failure. This example uses the Generic integration to send the notification of failure (using the second apia_discard example above), so your results will vary if you have chosen a different notification mechanism.

To test the apia_discard function on a staging server, rename the apia_input function in your main integration and then add the sample code. For example, if your main integration script is caspectrum.js:

  1. Make a backup copy of caspectrum.js.
  2. Open caspectrum.js in a text editor.
  3. Replace:
    function apia_input(apxml)
    

    with:

    function apia_input_renamed(apxml)
    
  4. Immediately before the above code, paste the following:
    /*
    	Sample code for testing and validation of apia_discard functionality. 
    */
    function apia_input(apxml)
    {
    	IALOG.info("Entering apia_input with apxml:" + apxml);
    
    	importPackage(Packages.com.alarmpoint.integrationagent.exceptions.retriable);
    	var ex = new java.lang.Throwable("Exception created for apia_discard testing");
    	throw new RetriableException(ex, 3, 5000);
    }
    
  5. Save the file.
  6. Restart the Integration Agent.

To test this code, open a command prompt in <IAHome>\bin and paste the following command:

apclient.bin --map-data "applications|caspectrum" "testing the apia_discard function"

The "applications|caspectrum" will have to be replaced with the "<domain>" and "<name>" parameters from your integration's XML definition file (e.g., caspectrum.xml).

The expected result of this test is:

  • In the Integration Agent log there will be three instances of a message similar to the following, at five-second intervals:
    WARN - Integration Service (applications,caspectrum) was unable to process a request due to a retriable exception: java.lang.Throwable: Exception created for apia_discard testing... 
    
  • After the third message, the log will contain:
    INFO - Calling JavaScript method apia_discard.
    ERROR - APIA_Discard: Discarding APXML ...(snip)... after 3 attempts to process.  
    
  • This will be followed by a message indicating that the notification request has been redirected to the Generic integration service, which has forwarded the data to xMatters:
    INFO - The Integration Service (generic, generic) is enqueueing the following APXML message for delivery to xMatters: ...
    
  • Finally, an event will be available for viewing in the xMatters user interface, with the original notification content and the exception message available in the "message" property.

Further reading

Additional information about apia_discard functionality is available in the xMatters Integration Agent guide.

 

xMatters Reference

Information created and supplied by Jeremy Brown. (DTN-6220)

 
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk