GIG: Reporting errors in processing events

Welcome back to the xMatters Getting Integrated Guide!

In our last installment (which covered integrating from xMatters to Slack), we mentioned that it might be nice to let the user know that their message was not in the right format. The Integration Builder operates “asynchronously”, so the response when you send stuff to it is just a confirmation the request was received in the form of a GUID representing the request ID. If we want to tell the user or integration something went wrong, we have to make an outbound call back to Slack to indicate as much.

This asynchronous nature makes the system much more stable and allows for better scale, but makes error reporting a little tricky. So let’s look at how we can send back a message about the state of an event or any errors that might have occurred in processing the incoming request.

When we built out the Slack integration, we had these two pieces of code that 1) parse the incoming message and 2) report an error:

1. Parse the message

re = new RegExp( /"(.*)" (.*)/ );
match = re.exec( data.text );

2. Log an error

if( match === null ) {
    console.log( 'ERROR: Could not parse "' + data.text + '". Expected: "[all | <recipient>]" [message]' );
    return;
}

Unfortunately, this will just dump information to the log and return, without actually sending an event and won’t tell anyone about it, unless you happen to look at the logs. (I sometimes read logs for leisure. They are comforting.) Anyway, since we have the username of the person who initiated the event and Slack is pretty good at sending and receiving messages, let’s just send them a direct message to let them know the correct format. Just to refresh, the outbound webhooks in Slack send over the following information:

token=XXXXXXXXXXXXXXXXXX
team_id=T0001
team_domain=example
channel_id=C2147483705
channel_name=test
timestamp=1355517523.000005
user_id=U2147483697
user_name=Steve
text=googlebot: What is the air-speed velocity of an unladen swallow?
trigger_word=googlebot:

We turned this incoming message into a JSON object called data, so we can just reference the user’s name as data.user_name. Did I ever mention how much I love JSON and javascript? Pretty sweet eh? So, where were we.... ah yes: now, we’ll use Slack’s incoming webhook api to send a direct message back to this user.

So, I set up an incoming webhook in my slack account and took all the defaults:

I then copied over the webhook URL and created a new endpoint in the Integration Builder:

I whipped up a helper function to make it easy to use. I have the “channel” add in a at symbol (@) which will target a user in Slack. (We could also broadcast to a channel by using a hashtag (#) instead. The payload also has a URL for an icon to make it look like it came from xMatters. In theory, you could use the fancy new image uploader and reference the URL from the image in the icon_url element in the function below.

/*
 * replyToSlack - Post a message to the user.
 *
 *   path - The Slack path. For example /H14H1B4F5/Q76HS76A/VaFfAdh865aAA
 *   user - The username to direct message. A '@' will be prepended
 *   message - The text of the message to send to the user
 */
function replyToSlack( user, message ){


  var req = http.request({
    "endpoint": "Slack",
    "method": "POST",
    "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
    }
  });

  var payload = { 
    "channel": '@' + user, 
    "username": "xMatters Integration Builder",
    "icon_url": "https://support.xmatters.comundefined" ", 
    "text": message 
  };

  var temp = req.write( 'payload=' + JSON.stringify( payload ) );


}

The last piece is to call the function in our catch for error:

// If there is no match, we can't correctly
// parse the recipients and the message...
// So we'll post it back to Slack.
if( match === null ) {
    var msg = 'Error sending event: Could not parse "' + data.text + '". Expected: "[all | <recipient>]" [message]';

    replyToSlack( data.user_name, msg );
    console.log( msg );
    return;
}

That’s it! Now, if I send a bunk message, xMatters will respond back to me and tell me what I used and what it is expecting. Pretty slick huh?