Integration Agent-compatible XMRESTAPI class for Integration Builder

Context

The xMatters REST API (https://help.xmatters.com/ondemand/api/intro-xmatters-apis.htm) is very extensive. This code block provides several helper functions for working with the API. 

Usage

Getting a list of active events matching an "issue_id"

var eventFilter = { 
 status : XMRESTAPI.EVENT_STATUS_ACTIVE, 
 properties : { 'issue_id' : trigger.properties.issue_id }
};

// Check if an active event already exists for this assignee
var events = XMRESTAPI.getEvents( eventFilter );

Getting an xMatters User

xmUser = XMRESTAPI.getPerson( trigger.properties.assignee );

Code

// xMatters REST API
var XMRESTAPI = {};
( function(){
 
 XMRESTAPI.RESPONSE_SUCCESS = "200";
 XMRESTAPI.RESPONSE_DATA_VALIDATION_ERROR = "400";
 XMRESTAPI.RESPONSE_CONFLICT = "409";
 
 XMRESTAPI.EVENT_STATUS_ACTIVE = "ACTIVE";
 XMRESTAPI.EVENT_STATUS_TERMINATED = "TERMINATED";
 
 // private functions
 
 function getEventFilterAsString( filter ) { 
 var text = "";
 
 for ( var property in filter ) {
 var value = filter[property];
 
 if( property == "properties" ) {
 var properties = "";
 for ( var p in value ) {
 if ( properties !== "" ) properties += ",";
 properties += p + "=" + String( value[p]);
 }
 value = encodeURIComponent( properties );
 } else {
 value = String( value );
 }
 
 if ( value !== null ) {
 if ( text !== "" ) text += "&";
 text += property + "=" + value;
 }
 }
 
 return text;
 }
 
 // public functions
 XMRESTAPI.getPerson = function( targetName ) {
 console.log( "XM REST API: getPerson for " + targetName );
 var url = "/reapi/2015-04-01/people?targetName=" + targetName;
 var response = XMIO.get( url );
 
 console.log( "XM REST API: getPerson received " + response.statusCode + " " + response.body ); 
 if ( response.statusCode == "404" ) return null; // person not found
 
 XMRESTAPI.checkResponse( response ); 
 return JSON.parse( response.body );
 };
 
 XMRESTAPI.getEvents = function( eventFilter ) {
 console.log( "XM REST API: getEvents for " + JSON.stringify( eventFilter ));
 var url = "/reapi/2015-01-01/events?" + getEventFilterAsString( eventFilter );
 
 var response = XMIO.get( url );
 
 console.log( "XM REST API: getEvents received " + response.statusCode + " " + response.body ); 
 XMRESTAPI.checkResponse( response ); 
 
 return JSON.parse( response.body );
 };
 
 XMRESTAPI.setEventStatus = function( eventFilter, status ) {
 console.log( "XM REST API: setEventStatus for " + JSON.stringify( eventFilter ) + " to " + status );
 return XMRESTAPI.setStatus( XMRESTAPI.getEvents( eventFilter ), status );
 };
 
 XMRESTAPI.setStatus = function( events, status ) {
 console.log( "XM REST API: setStatus " + status + " to " + events.total + " events" );
 var count = 0;
 
 for ( var i = 0; i < events.total; i++) {
 var event = events.records[i];
 console.log( "XM REST API: setEventStatus for " + event.href + " to " + status ); // href looks like /reapi/2013-12-01/events/<id>
 
 var response = XMIO.put( JSON.stringify({ 'status': status }), event.href );
 console.log( "XM REST API: setEventStatus received " + response.statusCode + " " + response.body );
 
 XMRESTAPI.checkResponse( response, {statusCode : XMRESTAPI.RESPONSE_CONFLICT} ); // ignore conflict errors 
 count++; 
 }
 
 console.log( "XM REST API: setStatus set " + status + " to " + count + " events successfully" ); 
 return count;
 };
 
 XMRESTAPI.deleteEvents = function( eventFilter ) {
 console.log( "XM REST API: deleteEvents for " + JSON.stringify( eventFilter ));
 return XMRESTAPI.setEventStatus( eventFilter, XMRESTAPI.EVENT_STATUS_TERMINATED );
 };
 
 // Utility methods 
 XMRESTAPI.checkResponse = function( response, ignoreError ) {
 if ( response.statusCode !== undefined && response.statusCode != XMRESTAPI.RESPONSE_SUCCESS ) {
 // Ignore status?
 if ( ignoreError && ignoreError['statusCode'] !== null && ignoreError['statusCode'] == response.statusCode ) {
 console.log( "XM REST API: checkResponse status " + response.statusCode + " will be treated as success" );
 return response;
 }
 
 var error; 
 try {
 var body = JSON.parse( response.body );
 if ( ignoreError && ignoreError['type'] !== null && ignoreError['type'] == body.type ) {
 console.log( "XM REST API: checkResponse error type " + response.statusCode + " will be treated as success" );
 return response;
 }
 error = body.message;
 } catch ( e ) {
 error = "xMatters server returned status " + response.statusCode;
 } 
 throw error;
 }
 return response;
 };
})();