Working with XML

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.

Getting ready

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

How to do it...

This recipe is split into two parts; first, we create an XML document, and then phrase an XML document.

Creating 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>
  1. Create a new workflow and create the following variables:

    Name

    Type

    Where

    Usage

    from

    String

    IN

    The sender of the e-mail.

    subject

    String

    IN

    The subject of the e-mail.

    date

    String

    IN

    The date of the e-mail.

    content

    String

    IN

    The content of the e-mail.

    XMLout

    String

    OUT

    The XML output in a one-line string.

  2. Drag a scriptable task into the schema and enter the following script:
          //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)
  3. Save and run this workflow. Copy and paste the output into Notepad and check the XML structure you have created.
  4. We now improve the program by using the JavaScript 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.

Parsing XML structures

Taking the XML string we created, we now focus on how to parse the XML structure:

  1. Create a new workflow and drag a scriptable task into it.
  2. Create the XML in-parameter of type string.
  3. In the scriptable task, enter the following script:
          //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); 
              } 
          } 
      }
  4. Run the workflow. Paste the XML string that was created earlier into the in-parameter, and watch the logs for the output.

Instead of walking through the XML tree, we can take some shortcuts; take a look at the How it works... section of this recipe.

How it works...

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 name
  • attributeValue = 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 name
  • XMLDoc = XMLManager.loadDocument(file, validate); XMLManager.saveDocument(XMLDoc,file): Using these methods, you can load and save XML documents onto the local Orchestrator filesystem

There's more...

In 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:

  • Define a new XML doc:
      var doc = new XML(XMLin);
  • Output the amount of children:
      doc.Mail.length()
  • Output all From tags:
      doc.Mail.From 
      doc..From
  • Output only the From tag from the first child:
      doc.Mail[1].From
  • Get the Date attribute from the From tag:
      doc.Mail[1].Content.@Date
  • Output the Mail record for the From tag that has the Username text in it:
      doc.Mail.(From=='Username')
  • Change the text of the tag:
      doc.Mail[1].Subject = "Test";
  • Change the attribute of the tag:
      doc.Mail[1].Content.@Date = "04.09.14";
  • Loop throughout the children of the element:
      for each (mail in doc)

See also

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)
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset