0

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;
};
})();

 

0 comments

Please sign in to leave a comment.