Retrieve External Data as Variables

One of the handlers available in MEP services, known as the Get External Data handler, can retrieve data from an external source such as your platform or a third party site. The retrieved data is stored as variables that you can then reference in the service. For example, your service could retrieve the latest weather and news and then send the information on in an SMS message.

The handler uses a simple HTTP request to retrieve data, which must use one of the following formats:

• XML - parsed and turned into a series of variables
• JSON - parsed and turned into a series of variables
• plain text - creates the variable scope.text with the text as the value.
  E.g. if you use the handler to retrieve plain text data and set the scope to "session", there is only one variable created: session.text and the value is the returned plain text.

There is no predefined template for the format of XML or JSON responses. MEP will parse XML and JSON into a series of variables and return a success outcome.

The handler ignores any external DTD references in XML responses.

Requirements for retrieving data

To ensure the authenticity of requests, you should only accept requests from the following OpenMarket IP addresses:

• 83.166.64.0 - 83.166.67.255 (83.166.64.0/22)
• 83.166.68.0 - 83.166.69.255 (83.166.68.0/23)
• 83.166.72.0 - 83.166.75.255 (83.166.72.0/22)
• 83.166.80.0 - 83.166.83.255 (83.166.80.0/22)
• 208.93.48.0 - 208.93.51.255 (208.93.48.0/22)

You can optionally specify an HTTPS (SSL) URL.

The external data source should return a 200 OK response, with the body containing data as plain text, or well-formed XML or JSON.

If the external data source is not available or returns an HTTP response code other than 200, the handler will retry until either the request is successful, or the handler times out. If you need the handler to return the failed outcome more quickly, you can manually configure the timeout settings using the "additional information" options when editing the handler.

If the returned XML is not valid then the failed outcome is triggered immediately.

Error conditions at the server should be conveyed using the XML output, not HTTP status codes.

Referencing XML or JSON as variables

The Get External Data handler creates a variable for each XML or JSON element. When retrieved:

• The scope for all of the variables is set in the handler.
• Each element name is a variable key.
• The content of each element is interpreted as the variable's value.

In the following examples, the keys are:

• date with a value 20120518
• flight with a value 209
• mealoptions.meal1 with a value steak
• mealoptions.meal2 with a value fish

XML example

<?xml version="1.0" ?>
<date>20120518</date>
<flight>209</flight>
<mealoptions>
   <meal1>steak</meal1>
   <meal2>fish</meal2>
</mealoptions>

JSON example

{
"date":"20120518",
"flight":209,
"mealoptions":
   {
   "meal1":"steak",
   "meal2":"fish",
   }
} 

To reference the variables, you need to enclose the variable key in square brackets and quote marks (single or double), for example:

${scope["date"]}

${scope["mealoptions.meal1"]}

XML attribute information

You can also extract attribute information from XML. This is referenced using the format tagname@attribute.

Example

In this XML example:

<?xml version="1.0" ?>
<animal type="dog">
   <name>Mr Woofy</name>
   <breed size="small">dachshund</breed>
   <age>5</age>
</animal>

you could reference the type attribute ("dog") and the size attribute ("small") using the following expressions:

${scope["animal@type"]}

${scope["animal.breed@size"]}

If the XML contains multiple elements with the same name, for example:

<?xml version="1.0"?>
<film>
   <title>Apollo 13</title>
   <actor>Tom Hanks</actor>
   <actor>Bill Paxton</actor>
   <actor>Kevin Bacon</actor>
</film>

they are accessible using "xml[n]", where n starts at zero, for example:

If you have experience with other programming languages, you may notice that the notation used here is similar to that used for arrays. However, it is not possible to iterate through the values using EL. You need to explicitly refer to values by their numbers.