Integrator > Integration Builder >   Integration inputs

Integration inputs

The request object describes the HTTP request posted to the integration service URL. You can use the transformation scripts to access the request headers, parameters, body, etc. The easiest way to examine the content of an incoming request is to send an HTTP request to your integration and then view the details in the Activity Stream.

Request object properties
Property Description
body

This is the body of the request posted to the integration service URL, and usually contains the JSON or XML payload of an HTTP POST.

  • If the body contains JSON, you can use JSON.parse(request.body) in the script to convert it to a JavaScript object.
  • If the body contains XML, you can use one of the included XML libraries to manipulate the data.
headers The HTTP headers of the incoming request. Note the Content-Type parameter that defines the payload type.
parameters

A JavaScript object featuring key-value pairs for any querystring parameters

If the Content-Type in the header is application/x-www-form-urlencoded, this section also contains the POST body parameters.

requestId The unique identifier (UUID) assigned to this request by the integration service when the request is received. This identifier is returned in the response, making it possible to match a request with the results of the script processing.
xTrace

An xMatters internal use ID that allows tracking of the request through the system.

The following is a sample request object:

{
	"body": "<incident importance=\"High\">\n    <ticket>16931</ticket>\n    <summary>Mail server is down</summary>\n    <recipients>\n        <username>bsmith</username>\n        <username>mmcbride</username>\n    </recipients>\n</incident>",
	"headers": {
		"Accept": "*/*",
		"Authorization": "Basic lmht9e46Yo9tc3xleA==",
		"Content-Length": "217",
		"Content-Type": "application/xml",
		"Host": "lugh.xmatters.com:8080",
		"User-Agent": "curl/7.40.0"
	},
	"method": "POST",
	"parameters": {},
	"remoteAddr": "127.0.0.1",
	"requestId": "afc9498a-ba47-418b-912f-d977091b7d2a",
	"timestamp": 1440001619011,
	"url": "http://lugh.xmatters.com:8080/integrations/6FE66C95-81C0-4DDC-B932-0D3609E234BA",
	"xtrace": "afc9498a-ba47-418b-912f-d977091b7d2a"
	}

If the body of your incoming request contains JSON, you can parse it to a JavaScript object using JSON.parse(request.body). If your incoming payload is XML, you may need to use one of the XML libraries listed below to read or manipulate the content.

Working with XML

The Integration Builder includes the following libraries that allow you to manipulate XML payloads. These are pure-JavaScript libraries sourced from "npm" (the package manager for Node.js), and packaged for use by the Nashorn engine using "browserify".

Library Description
XMLUtils.DOMParser

This is an implementation of the W3C DOM parser specification. The source library is XMLDOM (https://github.com/jindw/xmldom).

The DOMParser is a low-level parser used by the JXON and xpath libraries below, but can also be used directly.

XMLUtils.xpath This library allows you to read values from an XML DOM using the xpath syntax. The source library is xpath (https://github.com/yaronn/xpath.js).
XMLUtils.JXON

This library can be used to convert an XML document object into a native JavaScript object for further manipulation. The source library is jxon (https://github.com/tyrasd/jxon).

The Integration Builder provides a simplifying wrapper object for XMLUtils.JXON that takes an XML-formatted string and returns a JavaScript object using a single method, parse.

The wrapper takes this:

var obj = XMLUtils.JXON.build(new XMLUtils.DOMParser().parseFromString(xml));
 

And allows you to do this:

var obj = JXON.parse(xml);
 

By default, JXON case-folds all tag and attribute names to lowercase. For example, both <username> and <USERNAME> would be converted to a property called username in the JavaScript. To retain the exact case of tags and attributes, enable the following option in the script prior to calling JXON.parse:

XMLUtils.JXON.config({'lowerCaseTags': false});

Examples

The following examples illustrate how to use the included libraries to manipulate incoming XML payloads.

Incoming XML Manipulation
<incident importance="High">
    <ticket>1234</ticket>
    <summary>Mail server is down</summary>
    <recipients>
        <username>bsmith</username>
        <username>mmcbride</username>
    </recipients>
</incident>

Using DOMParser

var xml = request.body;
 
var doc = new XMLUtils.DOMParser().parseFromString(xml);
 
trigger.properties['Incident ID'] = doc.getElementsByTagName("ticket")[0].firstChild.data;
 
trigger.properties.Summary = doc.getElementsByTagName("summary")[0].firstChild.data;
 
var recipients = [];
var recips = doc.getElementsByTagName("username");
for (var i = 0; i < recips.length; i++) {
    recipients.push({"targetName": recips.item(i).firstChild.data});
}
trigger.recipients = recipients;
 
trigger.priority = doc.getElementsByTagName("incident")[0].getAttribute("importance");
 
form.post(trigger);

Using xpath:

var str = request.body;
// Build the XML document from the request
var doc = new XMLUtils.DOMParser().parseFromString(str, 'text/xml');
 
// Get the ticket number
var ticket = XMLUtils.xpath.select('//ticket/text()', doc)[0].data;
trigger.properties['Incident ID'] = ticket;
console.log("Ticket: " + ticket);
 
// Get the summary
var summary = XMLUtils.xpath.select('//summary/text()', doc)[0].data;
trigger.properties.Summary = summary;
console.log("Summary: " + summary);
 
// Loop over the recipients objects
var recipients = XMLUtils.xpath.select('//recipients/username', doc);
for (var i in recipients) {
    var recipientUsername = recipients[i].firstChild.data;
    console.log("Adding recipient " + recipientUsername);
    trigger.addRecipient(recipientUsername);
}
 
// Get the priority
var importance = XMLUtils.xpath.select('//incident/@importance', doc)[0].value;
console.log("Priority: " + importance);
trigger.priority = importance;
 
// Post the trigger to the form
form.post(trigger);

Using JXON:

var xml = request.body;
var obj = JXON.parse(xml);
console.log(JSON.stringify(obj));
/* The following data gets logged:
{
    "incident": {
        "@importance": "High",
        "recipients": {
            "username": [
                "bsmith",
                "mmcbride"
            ]
        },
        "summary": "Mail server is down",
        "ticket": 1234    }
}
*/
var data = obj.incident;
trigger.properties['Incident ID'] = data.ticket;
trigger.properties.Summary = data.summary;
var recipients = [];
for (var i in data.recipients.username) {
    recipients.push({"targetName": data.recipients.username[i]});
}
trigger.recipients = recipients;
trigger.priority = data['@importance'];
form.post(trigger);
<soap:Envelope
 xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
 xmlns:sch="http://www.xmatters.com/webservices/schema#5.5.47">
   <soap:Header/>
   <soap:Body>
      <sch:AddEvent>
         <sch:user>user1010</sch:user>
         <sch:password>tester</sch:password>
         <sch:clientTimestamp xsi:nil="true"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
         <sch:clientIP xsi:nil="true"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
         <sch:clientOSUser xsi:nil="true"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
         <sch:company>mustafar</sch:company>
        <sch:eventTokens>
            <sch:eventToken>
               <sch:name>Incident ID</sch:name>
               <sch:value>12345</sch:value>
            </sch:eventToken>
            <sch:eventToken>
               <sch:name>Impact</sch:name>
               <sch:value>High</sch:value>
            </sch:eventToken>
            <sch:eventToken>
               <sch:name>Summary</sch:name>
               <sch:value>testing SOAP endpoint</sch:value>
            </sch:eventToken>
         </sch:eventTokens>
      </sch:AddEvent>
   </soap:Body>
</soap:Envelope>

Using xpath with namespace:

var doc = new XMLUtils.DOMParser().parseFromString(request.body);
var select = XMLUtils.xpath.useNamespaces({"sch": "http://www.xmatters.com/webservices/schema#5.5.47"});
var tokens = select('//sch:eventTokens/sch:eventToken', doc);
 
// Iterate the event tokens to build the form properties
for (var i in tokens) {
  var nameToken = select('sch:name/text()', tokens[i])[0].data;
  var valueToken = select('sch:value/text()', tokens[i])[0].data;
  console.log("Adding property: " + nameToken + " = " + valueToken);
  trigger.properties[nameToken] = valueToken;
}
 
// Extract the target name from the incoming request and add to the trigger
var targetName = select('//sch:user/text()', doc)[0].data;
console.log("Adding Recipients: " + targetName);
var recipients = [];
recipients.push({
    'targetName': targetName
});
trigger.recipients = recipients;
console.log(JSON.stringify(trigger));
 
// Post the form to xMatters
form.post(trigger);