Integrated Properties! Pull data from an external system! (GIG Part 10)

So, maybe you saw Doug Peete’s Spring Release Overview demo or were perusing the News & Updates section and saw these fancy Integrated Properties, or maybe you missed all those and found this interesting new entry in the Form Edit menu? In any case, let’s take a closer look at this newest widget from the xMatters engineers.

This has been an often requested feature: the ability to pull in information from another system and include additional details from that system in the notification. In the link above, Doug talks about pulling in fields from an Incident on a message panel. This would allow you to send an event from the xMatters UI and include details from your favorite ticketing system! If you threw in some callbacks, you could even update the ticket with the message! Mind blowing!

Anyway, I’m going to take the same concept and apply to a different realm: catering. You see since Master Chef has been so successful after deploying these various uses of xMatters, he’s expanding the business into catering large events! Go Chef! In the next few paragraphs, I’m going to show how Master Chef will include weather forecast in the pre-catering reminder.


This is all rather theory actually. I live in San Diego and it is perennially 70° so you can safely plan events outside without issue 99% of the time. However, I realize there are other parts of the world that have to plan or alter events based on what the weather does that day. Fortunately, the venerable Weather Underground provides an api for getting weather data. This is a simple HTTP GET request with all the parameters in the URL.

For example, if my API_KEY was a1234b567c890, and I wanted the forecast details for zip code 92104 in JSONformat, the url looks like this:

Pretty easy actually. And this request returns a rather bewildering amount of data. Here is part of the JSON structure returned (note that since this is a GET, you can just paste that url in a browser to see what would happen.)

   "response" : {
      "version" : "0.1",
      "termsofService" : "",
      "features" : {
         "forecast" : 1
   "forecast" : {
      "txt_forecast" : {
         "date" : "11:36 AM PDT",
         "forecastday" : [{
               "period" : 0,
               "icon" : "mostlycloudy",
               "icon_url" : "",
               "title" : "Thursday",
               "fcttext" : "Considerable cloudiness. Slight chance of a rain shower. High around 65F. Winds W at 10 to 15 mph.",
               "fcttext_metric" : "Mostly cloudy. Slight chance of a rain shower. High 18C. Winds W at 15 to 25 km/h.",
               "pop" : "20"
            }, {
               "period" : 1,
               "icon" : "nt_chancerain",
               "icon_url" : "",
               "title" : "Thursday Night",
               "fcttext" : "Cloudy skies early, then off and on rain showers overnight. Low 58F. Winds W at 10 to 15 mph. Chance of rain 40%.",
               "fcttext_metric" : "Cloudy skies early, then off and on rain showers overnight. Low near 15C. Winds W at 10 to 15 km/h. Chance of rain 40%.",
               "pop" : "40"
            }, {

Ok, cool. So with a given zip code we can retrieve the forecast for that location. Let’s see what we can do with it. These integrated properties use the integration agent as a work space to make the HTTP calls. When you create a new Integrated Property, there are a couple of fields that tell the system where to go look. Let’s take a peek:

Here I’ve created a new Integrated Property and started filling in the fields:

The Name field gives a handle for interacting with the property. A Description is always good to explain to our colleagues what this thing is doing. The Protocol drop down right now just contains “Integration Agent”, but this will likely be expanded to other entries as we expand our cloud integration tools. The Integration Service might look familiar from Part 7 when we looked at callbacks. The last entry here is the Action field and has this entry called “getWeather”. These last three fields collectively tell the system to go look at any “integration agents” with the “wunderground” service and then fire the “getWeather” action.

The second part of this page details what data points we send to the “getWeather” action and what to expect when we return.

The Request Properties are the inputs, and in this case is Zip Code. The Response Properties are what we return from the call to the IA. Since the notification will be sent out the day before the catering gig, we’ll just pull out the forecast for the next day and then provide relevant details such as temperature, wind and conditions. A handy icon will make it look nice.

Ok, next, let’s check out the integration agent side of things. Below is an excerpt of the wunderground.js file included in the zip file at the bottom of the page. After a couple of wrapper functions, the code hits the handleGetWeather function and does the actual stuff to get the zip code sent over and then deal with returning that to xMatters. I’ve commented the code to explain what is going on.

function handleGetWeather(apxml) {

  // All responses must include this value from the request so that the response 
  // can be matched to its originating request.
  var requestUuid = apxml.getValue("xmattersRebRequestUuid");

  // The getEventProperties helper method will read the request properties out 
  // of the request.
  var obj = getEventProperties(apxml);

  // Create a minimal response
  var response = ServiceAPI.createAPXML();

  // This field is REQUIRED in the response. If omitted, xMatters will not be 
  // able to match the response to the request that originated it.
  response.setToken('xmattersRebRequestUuid', requestUuid, APXMLToken.Type.STRING);

  // Here we query an external data source for the values of the integrated properties
  var weatherJson = getWeatherData( obj[ 'Zip Code' ] );

  // Here we add some sample properties to the response.  These will be used to 
  // populate the response properties on the form, assuming properties with these 
  // names have been defined.
  var addTokens = {};
  addTokens[ 'Icon URL'      ] = weatherJson[ 'Icon URL'     ];
  addTokens[ 'High F'        ] = weatherJson[ 'High F'       ];
  addTokens[ 'Low F'         ] = weatherJson[ 'Low F'        ];
  addTokens[ 'High C'        ] = weatherJson[ 'High C'       ];
  addTokens[ 'Low C'         ] = weatherJson[ 'Low C'        ];
  addTokens[ 'Conditions'    ] = weatherJson[ 'Conditions'   ];
  addTokens[ 'Max Wind MPH'  ] = weatherJson[ 'Max Wind MPH' ];
  addTokens[ 'Max Wind KPH'  ] = weatherJson[ 'Max Wind KPH' ];

  // Add the response properties to the response message. The field MUST be 
  // called "additionalTokens", and the expected value should be a JSON 
  // representation of the values. Use JSON.stringify() to encode the values 
  // as JSON.
  response.setToken('additionalTokens', JSON.stringify(addTokens), APXMLToken.Type.STRING);

  ServiceAPI.getLogger().warn('Sending response with tokens ' + JSON.stringify(addTokens));

  // Return the response so that it gets sent back to xMatters.
  return response;

The code above makes a call to getWeatherData which does the actual call to wunderground to get the forecast. Here is the relevant part:

function getWeatherData( zipCode ) {

  // Set up the url for the HTTP GET
  var url = '' + API_KEY + '/forecast/q/' + zipCode + '.json';

  // httpget function from our helpers.js file
  weatherRAW = httpget( url );
  weather = JSON.parse( weatherRAW );

  // extractTomorrowForecast is also in helpers.js
  forecast = extractTomorrowForecast( weather.forecast.simpleforecast.forecastday )

  // Encapsulate the data into something readable
  data = {
    'Icon URL': forecast.icon_url,
    'High F': forecast.high.fahrenheit,
    'Low F': forecast.low.fahrenheit,
    'High C': forecast.high.celsius,
    'Low C': forecast.low.celsius,
    'Conditions': forecast.conditions,
    'Max Wind MPH': forecast.maxwind.mph,
    'Max Wind KPH': forecast.maxwind.kph

  return data;

And, check it out in action. Here is the Email template with all the Weather properties:

Then, we it comes time to send the notification, we get into the message panel, enter the Event Name and Date, then populate the Zip Code and hit the Search button. This makes the call to the integration agent and retrieves the details from wunderground. Pretty slick eh?

And when we send the event to someone the resulting email has the appropriate values:

If you want to play with this at home, here is a broad overview of the steps needed to use this wunderground service:

  1. Unzip the file into the IAHOME/integrationservices folder.
  2. Update the IAHOME/conf/IAConfig.xml file to recognize the wunderground service (see Part 6 for specific details on how to do this).
  3. Create the Integration Service on the xMatters applications event domain (See Part 7 for details).
  4. Import the Bakery file into the Communications Plan page or create your own Integration Property to use the wunderground service.


Click here for the next installment of the GIG!

Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.