GIG: Special Agent 6 at your service!

Progress. In technology things move and if you don't progress, you fall behind. Which is why our engineers up north have been fervently working on our new "xMatters Agent"! This new and improved agent will facilitate behind the firewall integrations into the future and beyond so let's check it out. 

This will likely be a series of articles working through the previous integrations for Oven Notifications, Callbacks, Inbound REST, and whatever else Chef needs, so we can bring his xMatters instance into the future. 

To get the agent out and in the hands of our awesome integrators, this first version of the agent is outbound only, but fear not, shortly down the road a command line and REST inbound interfaces will be added. So, based on that, we'll start with making HTTP calls from the agent to the SmartOven™ API to change the temperature. Quite the sophisticated oven. 

With this new release, you will notice there is a new entry in the Developer menu:

This is the central place for managing all your integration agents, across the enterprise. From here you can see what agents are where, who's up, who's down and all the version information. But for now, we need to see about getting the agent installed. Our SmartOven™ is Debian based, so we'll select Debian from the dropdown then hit the Install/Update. Check that out! It's a handy script we can use to download, install and even configure the agent! Woo! No more IAConfig.xml mess. 

sudo -- sh -c "echo 'deb stable main' > /etc/apt/sources.list.d/xmatters.list
wget -O -| apt-key add -
apt-get update
apt-get install -y xmatters-xa
service xmatters-xa start"

The last command in that script will start the agent service, so momentarily we'll see the agent displayed in the list.

Sweet! Now, let's put it to work. Cruise over to the Comm Plans and open up our 2nd favorite plan, Oven Notifications. (Second only to the Muffins Ready of course. Everyone likes baked goods.) Open the Integration Builder and we'll see our existing Outbound Integration scripts:

This list really just tells the outbound processor to redirect everything to a legacy Integration Agent. With our new cloud scripting technology, we will generate the script in the cloud and it will then be sent to the agent to run. This provides a consistent environment for building scripts, so if you are familiar with writing scripts for the cloud based IB, you don't have to learn an entirely different architecture just to write very similar scripts for an agent. 

However, due to this new architecture, migrating from a legacy integration agent script to a new Agent script is not as easy as copy/pasta. Let's take a look at the old IA based integration script and then pick it apart at a high level. Here is the apia_callbacks function which handles what are now referred to as "Outbound Integrations". 

function apia_callback(msg){

var str = "Received message from xMatters:\n";
str += "\nRAW: \n" + JSON.stringify( msg, null, 2 ); // Pretty print for easy reading;

if( msg.xmatters_callback_type == 'response' ) {
var temp = msg.response;

if( temp == "Off" )
temp = "0";

var payload = {
"ovenname": msg.additionalTokens.Oven_Name,
"temp": temp

var username = '';
var password = '';
var url = 'http://ovenhost/path';
httpresp = JSON.stringify( payload ), url, username, password); 'SmartOvenTM result: (' + httpresp.status + '): ' + httpresp.body );


So, at a high level, this is what this function is doing:

  1. Dump the "msg" variable to the log. The "msg" variable is the payload sent from xMatters.
  2. Check the callback type to make sure it is a "response" as opposed to an event status update or delivery status update. 
  3. Build the payload, using the temperature from the user's response, or 0 if they responded with "Off". 
  4. Make an HTTP call to the oven including a username and password. We just can't be too careful with the state of IoT security these days. 
  5. Dump the response from the oven to the log. 

 Ok, so how do we perform the same actions with the new agent. Let's look at each one individually. 

  1. Ok, our friend `console.log` is pretty handy for dumping anything to a log. The best part about this is we don't have to login to the server hosting the agent to see the logs! We can see them in the browser in real time! Wooo! It's like magic!
  2. This is easy. We actually select the "trigger" in the drop down before creating our outbound integration. 
  3. Pretty straightforward, we can actually just copy/paste this part. 
  4. Piece of cake, we've been over this.
  5. See #1


Since there isn't really a migration path, we'll just create a new outbound integration script. Select the appropriate values as noted below. Especially note the "Trigger" item is set to "Notification responses". 

Save the script and open the editor. I've rewritten the script, so if you want to just copy/paste this, have at it. 

var str = "Received message from xMatters:\n";
str += "\nRAW: \n" + JSON.stringify( callback, null, 2 ); // Pretty print for easy reading

console.log( str );

var temp = callback.response;

if( temp == "Off" )
temp = "0";

var payload = {
"ovenname": callback.eventProperties.Oven_Name,
"temp": temp

var req = http.request({
'endpoint': 'SmartOvenTM',
'path': 'path',
'method': 'POST'

var raw = req.write( payload );
console.log( 'SmartOvenTM result: (' + raw.statusCode + '): ' + raw.body );

There are a lot of similarities, but there are also some important differences. First, the msg variable is referenced as "callback" in the IB and the format of this JSON object is slightly different. The most notable item here is the eventProperties instead of additionalTokens. The additionalTokens is a hold over from how the Legacy Integration Agent communicated with xMatters. Finally, we're using the http.request module which leverages the pre-defined Endpoints and handles the Authentication and fully qualified domain name aspects. 

After the script is saved, make sure to create the "SmartOvenTM" endpoint and point it to the Smart Oven "server". Then send an event and make a response. The activity stream has all the info we need! We can see that the agent processed this request because it is doing an HTTP call to "localhost"!

Executing outbound integration for xMatters event ID: 3440006
Received message from xMatters:

"recipient": "tdepuy",
"device": "Work Email",
"response": "150",
"annotation": null,
"eventIdentifier": 3440006,
"date": "17-03-31 18:51:47.846",
"eventProperties": {
"Oven_Name": "Muffins"
> POST http://localhost:9988/processCallback HTTP/1.1
> Accept: text/plain, application/json, application/*+json, */*
> User-Agent: Xerus (EndpointClient)
> Content-Type: application/json; charset=UTF-8
> X-Trace: a7f4b5a7-315d-4d31-b1ac-d3d92df47b58,8164eda1-96ea-482e-a508-24651d9856dc
> Content-Length: 35

< HTTP/1.1 200 OK
< X-Powered-By: Express
< Content-Type: text/html; charset=utf-8
< Content-Length: 2
< Date: Fri, 31 Mar 2017 18:51:52 GMT
< Connection: keep-alive

SmartOvenTM result: (200): OK


Pretty slick! This means you can run behind the fire wall integrations and tweak the scripts without needing access to the box! Just login to your xMatters instance and tweak the scripts, fire the integration and you're in business.

Stay tuned as we release more and more features to these agents! 

Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk