In this recipe, we explore how to use the XML plugin to create and phrase XML structures with Orchestrator. XML is a good way to exchange complex information between systems.
We don't need anything special; however, we need to understand the basics of XML. Take a look at http://www.w3schools.com/xml/ .
You should be familiar with the JavaScript concept of functions (see the introduction to this chapter).
This recipe is split into two parts; first, we create an XML document, and then phrase an XML document.
This is the rather more complex part; however, we will go through it slowly.
We will create a simple XML document that looks like this:
<?xml version="1.0" encoding="UTF-8"> <MailMessages> <Mail> <From>[email protected]</From> <Subject>Test message</Subject> <Content Date="10/12/12">This is a test message </Content> </Mail> </MailMessages>
Name |
Type |
Where |
Usage |
|
|
IN |
The sender of the e-mail. |
|
|
IN |
The subject of the e-mail. |
|
|
IN |
The date of the e-mail. |
|
|
IN |
The content of the e-mail. |
|
|
OUT |
The XML output in a one-line string. |
//create empty XML document var document = XMLManager.newDocument(); // add a root element var mailMessages = document.createElement("MailMessages"); //add the root element to the document document.appendChild(mailMessages) ; //Create new node var mail = document.createElement("Mail"); //add new node under the root element mailMessages.appendChild(mail) ; //add a Child node under the mail node var nodeFrom = document.createElement("From"); mail.appendChild(nodeFrom); //set a text value for the From node var txtFrom = document.createTextNode(from); nodeFrom.appendChild(txtFrom); //add another node with a value to the mail node var nodeSubject = document.createElement("Subject"); mail.appendChild(nodeSubject); var txtSubject = document.createTextNode(subject); nodeSubject.appendChild(txtSubject); //add content node var nodeContent = document.createElement("Content"); mail.appendChild(nodeContent); var txtContent = document.createTextNode(content); nodeContent.appendChild(txtContent); //Add an attribute to the Content node nodeContent.setAttribute("Date",date); //Output the XML Document as string XMLout=XMLManager.getDocumentContent(document)
function
command. Use the following script:function createNode(doc,rootNode,NodeName,NodeText, attribName,attribValue) { var newNode = doc.createElement(NodeName); rootNode.appendChild(newNode); // if there is no NodeText don't add anything if (NodeText!= null){ var newTxt = doc.createTextNode(NodeText); newNode.appendChild(newTxt); } // if there is an attribute defined add it if (attribName!= null){ newNode.setAttribute(attribName,attribValue); } // return the new created node return newNode; } //create empty XML document var document = XMLManager.newDocument(); mailMessages = createNode(document,document,"MailMessages"); mail = createNode(document,mailMessages,"Mail"); createNode(document,mail,"From",from); createNode(document,mail,"Subject",subject); createNode(document,mail,"Content",content,"Date",date); //Output the XML Document as string XMLout=XMLManager.getDocumentContent(document);
You can see how using the function
command reduces the number of lines and makes the code more reusable. Alternatively, you can also create an action and put the function content into it.
If you like, you can now go and integrate XML into the workflow that you built in the Receiving e-mails section of the Working with mails recipe in Chapter 9, Essential Plugins, to format the e-mail output.
Taking the XML string we created, we now focus on how to parse the XML structure:
XML
in-parameter of type string
.//convert the string into an XML document var document = XMLManager.fromString(XMLin); // get all Child elements of the document (type: XMLNodeList) var docNodelist = document.getChildNodes(); //as we know from the XML structure there is only mailmessages var mailmessage = docNodelist.item(0); //now we get all child elements from mailmessages var maillist = mailmessage.getChildNodes(); //lets see how many child elements there are var mails = maillist.length; //lets walk though each mail (type: XMLNode) for (i = 0; i < mails; i++) { mail = maillist.item(i); //get the child elements of each mail var mailchilds = mail.getChildNodes(); //walk through the mail Childs for (j = 0; j < mailchilds.length; j++) { //get one child var child = mailchilds.item(j); //get child name var childName = child.nodeName; //get child content (type: XMLElement) var childText = child.textContent; //output System.log (childName+" : "+childText); //lets get the childs attributes (type: XMLNamedNodeMap) var ChildAttribs=child.getAttributes(); //walk though all attributes for (k = 0; k < ChildAttribs.length; k++) { //get one attribute (type: XMLNode) var ChildAttrib = ChildAttribs.item(k); //get Attribute name var ChildAttribName = ChildAttrib.nodeName; //get Attribute value var ChildAttribValue = ChildAttrib.nodeValue; //output System.log("Attribute : "+ChildAttribName+" : "+ChildAttribValue); } } }
Instead of walking through the XML tree, we can take some shortcuts; take a look at the How it works... section of this recipe.
XML is a very nice way to exchange complex information. As you can see, forming an XML isn't that hard, especially when using a function or action. Parsing an XML is quite straightforward, too; the example we used is very detailed, but it will work for any simple XML. It can be made easier by using some of these XML methods:
nodeList = Node.getElementsByTagName(tag)
: This method can be used to create a node list of all nodes that have the same node nameattributeValue = Node.getAttribute(attributeName)
: This is an undocumented method that is quite useful, as you can directly access the value of the attribute by supplying the attribute's nameXMLDoc = XMLManager.loadDocument(file, validate); XMLManager.saveDocument(XMLDoc,file)
: Using these methods, you can load and save XML documents onto the local Orchestrator filesystemIn addition to the XML plugin that we looked at in this recipe, Orchestrator also supports the JavaScript built-in XML (E4X). Please note that most browsers no longer support E4X and therefore it is doubtful how long its shelf life in JavaScript will be. On the other hand, the JavaScript implementation of Orchestrator isn't a new one either, so for that purpose it doesn't matter.
Here is a short introduction to E4X XML:
var doc = new XML(XMLin);
doc.Mail.length()
From
tags:doc.Mail.From doc..From
From
tag from the first child:doc.Mail[1].From
Date
attribute from the From
tag:doc.Mail[1].Content.@Date
Mail
record for the From
tag that has the Username
text in it:doc.Mail.(From=='Username')
doc.Mail[1].Subject = "Test";
doc.Mail[1].Content.@Date = "04.09.14";
for each (mail in doc)
To learn more about E4X, take a look at the following URLs:
The example workflows are as follows:
10.01.1 CreateXML
10.01.2 CreateXML(Function)
10.01.3 phraseXML(General)