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);

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": [
                "aottema",
                "ernie"
            ]
        },
        "summary": "Mail server is down",
        "ticket": 28088
    }
}
*/
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);