Integration Agent requests to xMatters fail due to '202' response

This article describes how web service requests from the Integration Agent to a hosted xMatters instance may fail due to a 202 response, and provides instructions for updating integration scripts to handle 202 responses.

Issue details

Many integration scripts and Integration Agent utility scripts do not include logic to handle 202 responses. This can cause the script to stop processing the current notification request, even though the request has been accepted by xMatters and notifications can be expected to succeed.

Requests that may fail due to this condition include:

  • submitApxml
  • getUserDetails
  • getEvents
  • setEventStatus

A 202 response does not signify that the request has failed; rather, it indicates the request content has been accepted for processing, and processing is not yet complete. Incorrect handing of the 202 response by the integration service can cause the following undesirable consequences:

  • Subsequent processing of the notification request (such as an annotation being sent to the management system) may be abandoned.
  • The client may be concerned about resulting error messages in the Integration Agent log files.

Updating integration scripts to handle 202 responses

In most integrations, the code that handles sending requests to xMatters is encapsulated in the XMRESTAPI functions. The exception is the submitApxml function, which is typically found in the main integration scripts rather than the XMRESTAPI files.

Therefore, you will usually need to modify the XMRESTAPI script file and the main integration files to resolve the problem.

To update the XMRESTAPI functions to handle 202 responses:

  1. Back up <IAHome>\lib\integrationservices\xmrestapi.js and then open it with a text editor.
  2. Search for:
    XMRESTAPI.RESPONSE_SUCCESS = "200";
  3. On a separate line, append:
    XMRESTAPI.RESPONSE_SUCCESS_ACCEPTED = "202";
  4. Next, search for:
    if ( response.status !== undefined && response.status != XMRESTAPI.RESPONSE_SUCCESS ) { 
  5. Replace it with:
    if ( ( response.status !== undefined && response.status != XMRESTAPI.RESPONSE_SUCCESS ) && ( response.status != XMRESTAPI.RESPONSE_SUCCESS_ACCEPTED ) )

To update the main integration scripts to handle 202 responses:

  1. Search the integration script files for any instance of "XMRESTAPI.RESPONSE_SUCCESS".
    • Typically, the code will be very similar to:
      if (response.status == XMRESTAPI.RESPONSE_SUCCESS) { 
  2. Back up any such script files and open them with a text editor.
  3. Append "|| (response.status == XMRESTAPI.RESPONSE_SUCCESS_ACCEPTED)"
    • For example, replace:
      if (response.status == XMRESTAPI.RESPONSE_SUCCESS) { 

      with:

      if ( (response.status == XMRESTAPI.RESPONSE_SUCCESS) || (response.status == XMRESTAPI.RESPONSE_SUCCESS_ACCEPTED) ) { 
  4. Search for and update any other instances of the above code (typically there will be just one).
  5. Save the files and restart the Integration Agent.

 

xMatters internal reference:
DTN-6369 Originally by Jeremy Brown

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk