XML Variables

(Available from version 7.0 onwards.)

XML variables allow you to load, read, process, and save data stored in XML format.

For instructions on how to create a complex variable, see here.

Prerequisites

To make full use of the XML variables and their methods, some knowledge of the following is required:

  • XML markup language

  • XPath query language

XML Variable Types

Automation Studio provides three types of XML variables, described below.

The examples shown are based on a simple XML file that lists all three members of a country club.

  • XML Document: This type is designed to store the contents of a standard XML file, including the header (e.g. <?xml version="1.0" encoding="UTF-8"?>), and the XML content itself. Methods are provided for uploading XML files to an XML Document variable.

    <?xml version="1.0" encoding="UTF-8"?>
<members clubName="The Parktown Club" city="Parktown">
		<member level="Gold" type="family">
			<surname>Smith</surname>
			<joined>2008</joined>
		</member>
		<member level="Silver" type="single">
			<surname>Cheketri</surname>
			<joined>2013</joined>
		</member>	
		<member level="Silver" type="family">
			<surname>Peters</surname>
			<joined>2001</joined>
		</member>
</members>

  • XML Element: This type is designed to store the root element of a standard XML file. A method is provided to populate an XML Element variable with the contents of an XML Document variable.

    <members clubName="The Parktown Club" city="Parktown">
		<member level="Gold" type="family">
			<surname>Smith</surname>
			<joined>2008</joined>
		</member>
		<member level="Silver" type="single">
			<surname>Cheketri</surname>
			<joined>2013</joined>
		</member>	
		<member level="Silver" type="family">
			<surname>Peters</surname>
			<joined>2001</joined>
		</member>
</members>

  • XML Node: This type is designed to store nodes (or sections) of XML content. Methods are provided for populating XML Node variables with nodes from XML Elements and from other XML Nodes.

    	<member level="Gold" type="family">
		<surname>Smith</surname>
		<joined>2008</joined>
	</member>
    		<surname>Smith</surname>

XML Variable Properties

The three XML variable types all share the same set of properties described below. Not all properties are populated or relevant for all types. See the examples below the table for more information.

Property

Type

Description

Can Be Modified
Exists Boolean

Indicates whether data was found with which to populate the variable when using the method of another variable.

Returns true if the variable was populated with data. Returns false if no data was found with which to populate the variable.

 No
Inner XML Text The XML content of all child nodes of the variable. Yes
Name Text The name of the outer node in the variable, or in other words, the outermost XML tag of the XML in the variable. No
Outer XML Text The XML content of the variable. No
Value Text   Yes

Example of XML Variable Types and Properties

This example is designed to clarify the role of the three XML variable types and the meaning of each of their properties. The example uses a limited number of the methods provided. See the example provided for each method here.

This example is based on an XML file club_members.xml which lists all members of a country club and details on each.

<?xml version="1.0" encoding="UTF-8"?>
<members clubName="The Parktown Club" city="Parktown">
		<member level="Gold" type="family">
			<surname>Smith</surname>
			<joined>2008</joined>
		</member>
		<member level="Silver" type="single">
			<surname>Cheketri</surname>
			<joined>2013</joined>
		</member>	
		<member level="Silver" type="family">
			<surname>Peters</surname>
			<joined>2001</joined>
		</member>
</members>

An XML Document variable can be populated directly from an XML file, using the Load XML File method.

When running the project, the XMLDocument variable is populated with the entire contents of the XML file.

The variable properties are set as below:

  • Exists: Blank, as was not populated using a method of another XML variable.

  • Name: Blank, as the variable includes the file header in addition to the XML content

  • Inner XML: Includes the full contents of the XML file.

  • Outer XML: Includes the full contents of the XML file.

  • Value: Blank

An XML Element variable is populated from an XML Document variable using the Get Document Element method of the XML Document variable.

When running the project, the XMLElement variable is populated with the entire contents of the XML file except for the XML file header. Compare the Outer XML values of XMLDocument and XMLElement.

The variable properties are set as below:

  • Exists: true, as was successfuly populated from the XMLDocument variable.

  • Name: members which is the outermost XML tag in the XML Element.

  • Inner XML: Includes the full content of the XML Element, except for the outermost XML tag.

    <member level="Gold" type="family"><surname>Smith</surname><joined>2008</joined></member><member level="Silver" type="single"><surname>Cheketri</surname><joined>2013</joined></member><member level="Silver" type="single"><surname>Cheketri</surname><joined>2013</joined></member><member level="Silver" type="family"><surname>Peters</surname><joined>2001</joined></member>

  • Outer XML: Includes the full contents of the XML Element, including the outermost XML tag.

    <members><member level="Gold" type="family"><surname>Smith</surname><joined>2008</joined></member><member level="Silver" type="single"><surname>Cheketri</surname><joined>2013</joined></member><member level="Silver" type="single"><surname>Cheketri</surname><joined>2013</joined></member><member level="Silver" type="family"><surname>Peters</surname><joined>2001</joined></member></members>

  • Value: Blank

An XML Node can be populated from an XML Document, an XML Element, or from another XML Node. In this example we will populate XMLNode_1 from XMLElement, and XMLNode_2 from XMLNode_1. In each case we will use the Get First Child method.

The workflow populates XMLNode_1 from XMLElement.

When running the project, XMLNode_1 is populated with the XML content of the first member node in XMLElement.

The variable properties are set as below:

  • Exists: true, as was successfuly populated from the XMLElement variable.

  • Name: member which is the outermost XML tag in the XML Element.

  • Inner XML: Includes the full content of XMLNode_1, except for the outermost XML tag.

    <surname>Smith</surname><joined>2008</joined></member>

  • Outer XML: Includes the full contents of the XML Element, including the outermost XML tag.

    <member level="Gold" type="family"><surname>Smith</surname><joined>2008</joined></member>

  • Value: Blank

The workflow populates XMLNode_2 from XMLNode_1.

When running the project, XMLNode_2 is populated with the XML content of the first node of XMLNode_1.

The variable properties are set as below:

  • Exists: true, as was successfuly populated from the XMLNode_1 variable.

  • Name: surname which is the outermost XML tag in the XML Element.

  • Inner XML: Includes the full content of XMLNode_2, except for the outermost XML tag.

    Smith

  • Outer XML: Includes the full contents of the XML Element, including the outermost XML tag.

    <surname>Smith</surname>

  • Value: Blank

Sample Implementation

To see a full project in which data from an XML file is parsed and used to populate a list variable, see Project: Read Data from an XML File.

Methods

The three XML variable types share most of their methods. Some methods are available for one XML variable type only. The table below lists all methods and indicates which methods are available for each variable type. It also indicates the return type of each method.

Method

Returns

XML Document

XML Element

XML Node
Elements By Tag Name List of XML Nodes No Yes No
Get Attribute by Name XML Node Yes Yes Yes
Get Attributes List of XML Nodes Yes Yes Yes

Method

Returns

XML Document

XML Element

XML Node
Get Child Nodes List of XML Nodes Yes Yes Yes
Get Document Element XML Element Yes No No
Geft First Child XML Node Yes Yes Yes
Get InnerText Text Yes Yes Yes
Get Next Sibling XML Node Yes Yes Yes
Get Parent Node XML Node Yes Yes Yes
Get Previous Sibling XML Node Yes Yes Yes
Get Value Text Yes Yes Yes
Load XML N/A Yes No No
Load XML File N/A Yes No No
Remove XML NameSpace N/A Yes No No
Save XML File N/A Yes No No
Select Nodes List of XML Nodes Yes Yes Yes
Select Single Node XML Node Yes Yes Yes

Information on Examples for Methods

An example implementation is shown for each method listed below. All examples are included in the sample project. The sample project includes one workflow per method.

Download the sample project here and unzip to the folder %AppData%/Nice_Systems/AutomationStudio/Projects.

Download the sample XML file here and copy it to the folder c:/Temp.

Methods

Returns the root element of the contents of an XML Document variable.

Parameters

Parameter

Input Type

Description

none

 

 

Returns

Returns an XML Element.

Example

This workflow:

  1. Populates the XMLDocument variable from an XML file. See the example for Load From File.

  2. Populates the XMLElement variable with the root element of XMLDocument using XMLDocument's Get Document Element method.

The XMLElement variable now includes the root element of XMLDocument. In other words it includes the full contents of XMLDocument except for the XML header.

Loads the specified XML into the XML Document variable.

Parameters

Parameter

Input Type

Description

xml

Text

The XML Document to load.

Returns

Nothing.

Example

This workflow loads the XML shown directly into an XML Document variable called XMLDocMini.

The XMLDocMini variable now stores the XML that was loaded.

Loads the contents of the specified XML file into the XML Document variable.

Parameters

Parameter

Input Type

Description

File path

Text

The location of the XML file.

File name

Text

The name of the XML file.

Returns

Nothing.

Example

This workflow loads the contents of the file c:\Temp\club_members.xml into the variable XMLDocument.

The variable XMLDocument now includes the full contents of that file.

Removes all namespace (XMLNS) attributes from the contents of the XML Document variable to enable regular work.

Parameters

Parameter

Input Type

Description

none

 

 

Returns

Nothing.

Example

This workflow first loads XML shown below with a namespace (xmlns) attribute into the XML Document variable XMLDocXmlns. It then removes the namespace attribute.

<?xml version="1.0" encoding="UTF-8"?>
<countryclub xmlns="http://www.countryclubs.com/xml/countryclub" name="The Parktown Club" city="Parktown">
	<members>
		<member level="Gold" type="family">
			<surname>Smith</surname>
			<joined>2008</joined>
		</member>
	</members>
</countryclub>

The XML Document XMLDocXmlns does not contain the namespace attribute.

Write the contents of the XML Document variable to a specified file. If the specified file aready exists, its existing contents are overwritten.

Parameters

Parameter

Input Type

Description

File path

Text

Location where the file to be saved.

File name

Text

Name of the file to save.

Returns

Nothing.

Example

This workflow:

  1. Populates the XMLDocument variable from an XML file. See the example for Load From File.

  2. Saves the contents of XMLDocument to the file c:/temp/copy.xml using XMLDocument's Save XML File method.

The file is saved.

Selects the nodes specified by an XPath query.

Parameters

Parameter

Input Type

Description

XPath

Text

The XPath query.

Returns

Returns a List of XML Nodes.

Example

This workflow:

  1. Populates the XMLElement variable with the root element of the XML file. See the example for GetDocumentElement.

  2. Retreives all the nodes named member using the XPath query //member and stores them as elements in the List of XML Nodes variable ListOfNodes.

ListOfNodes now includes three elements, one for each of the three members of the country club.

Selects the single node specified by an XPath query.

Parameters

Parameter

Input Type

Description

XPath

Text

The XPath query.

Returns

Returns an XML Node.

Example

This workflow:

  1. Populates the XMLElement variable with the root element of the XML file. See the example for GetDocumentElement.

  2. Retreives the second member node using the XPath query /members/member[2] and stores it in the XML Node variable XMLNode_1.

The XML Node varaible XMLNode_1 now stores the details of the second member of the country club.

If we had instead attempted to retrieve the fourth member of the club using the XPath query /members/member[4], XMLNode_1 would be empty and its Exists property would be false, as there is no fourth member listed in the XML file, as below:

Retrieves all nodes with the specified name.

Properties

Parameter

Input Type

Description

Tag Name

Text

The name of the nodes to retrieve.

Returns

Returns a List of XML Nodes.

Example

This workflow:

  1. Populates the XMLElement variable with the root element of the XML file. See the example for GetDocumentElement.

  2. Retreives all nodes named surname and stores them in the List of XML Nodes variable ListOfNodes.

ListOfNames now includes three elements, one for each surname listed in the XML file.

Retrieves the node of the specified attribute. In other words, it retrieves the value of the specified attribute.

Parameters

Parameter

Input Type

Description

name

Text

Name of the attribute.

Returns

Returns an XML Node.

Example

This workflow:

  1. Retrieves the first member listed in XMLElement and stores it in XMLNode_1. See the example for Get First Child.

  2. Retrieves the attribute named level and stores that in XMLNode_2 using the method Get Attribute Name of XMLNode_1.

XMLNode_2 now stores the name and value of the level attribute of XMLNode_1.

Retrieves the list of a node's attributes.

Parameters

Parameter

Input Type

Description

none

 

 

Returns

Returns a List of XML Nodes.

Example

This workflow:

  1. Retrieves the first member listed in XMLElement and stores it in XMLNode_1. See the example for Get First Child.

  2. Retrieves all the attributes of XMLNode_1 and stores them in the List of XML Nodes variable ListOfNodes using XMLNode_1's Get Attribute method .

ListOfNodes now includes two elements - one for each of the two attributes of XMLNode_1.

Retrieves all the child nodes of the current node.

Parameters

Parameter

Input Type

Description

none

 

 

Returns

Returns a List of XML Nodes.

Example

This workflow:

  1. Populates the XMLElement variable with the root element of the XML file. See the example for GetDocumentElement.

  2. Retrieves all child nodes from XMLElement and stores them in the List of XML Nodes variable ListOfNodes using the method Get Child Nodes.

The List of XML Nodes ListOfNodes now includes three elements - one for each member node in XMLElement.

Retrieves the first child node of the current node or element.

Parameters

Parameter

Input Type

Description

none

 

 

Returns

Returns an XML Node.

Example

The workflow below:

  1. Populates the XMLElement variable with the root element of the XML file. See the example for GetDocumentElement.

  2. Retreives the first node and stores it in the XML Nodes variable XMLNode_1.

The XML Node XMLNode_1 now stores only the first member node of XMLElement.

Returns the concatenated values (only) of the node and all its child nodes. The tags are not included.

Parameters

Parameter

Input Type

Description

none

 

 

Returns

Returns text.

Example

This workflow:

  1. Retrieves the first member listed in XMLElement and stores it in XMLNode_1. See the example for Get First Child.

  2. Extracts the inner text of all nodes in XMLNode_1, concatenates them, and stores the text in the text variable TextVar using XMLNode_1's Get InnerText method.

TextVar now includes the inner texts of the two nodes of XMLNode_1, concatenated into a single string.

Retrieves the node that follows the current node in the node or element from which the current node was originally retrieved.

To understand this better, take a look at the image below.

In the image above:

  • Node 1 is the parent of Node 1.1, Node 1.2, and Node 1.3.

  • Using the method Get First Child of Node 1 returns Node 1.1.

  • Using the method Get Next Sibling of Node 1.1 returns Node 1.2, as Node 1.1 is a child of Node 1 and Node 1.2 is its next sibling.

Parameters

Parameter

Input Type

Description

none

 

 

Returns

Returns the next sibling node of the current node.

Example

This workflow:

  1. Retrieves the first member listed in XMLElement and stores it in XMLNode_1. See the example for Get First Child.

  2. Retrieves the node that follows XMLNode_1 in XMLElement and stores that in XMLNode_2 using XMLNode_1's Get Next Sibling method.

Since XMLNode_1 stored the first node from XMLElement, when using XMLNode_1's Get Next Sibling method, the second node from XMLElement is returned. XMLNode_2 therefore stores the node for the second member.

Gets the parent node of the current node if the current node has a parent node.

To understand this better, take a look at the image below.

In the image above:

  • Node 1 is the parent of Node 1.1, Node 1.2, and Node 1.3.

  • Using the method Get First Child of Node 1 returns Node 1.1.

  • Using the method Get Parent of Node 1.1 returns Node 1.

Parameters

Parameter

Input Type

Description

none

 

 

Returns

Returns the parent node of the current node.

Example

This workflow:

  1. Retrieves the first member listed in XMLElement and stores it in XMLNode_1. See the example for Get First Child.

  2. Retrieves the parent of XMLNode_1 using XMLNode_1's Get Parent Node method and stores that in XMLNode_2.

XMLNode_2 now stores the parent of XMLNode_1. Since XMLNode_1 is a child of XMLElement, XMLNode_2 and XMLElement are identical.

Retrieves the node that precedes the current node in the node or element from which the current node was originally retrieved.

For clarification, see Get Next Sibling.

Parameters

Parameter

Input Type

Description

none

 

 

Returns

Returns an XML Node.

Example

This workflow:

  1. Retrieves the second member listed in XMLElement and stores it in XMLNode_1. See the example for Select Single Node.

  2. Retrieves the previous sibling of XMLNode_1 and stores it in XMLNode_2 using XMLNode_1's Get Previous Sibling method.

XMLNode_2 now stores the XML of the first member listed in XMLElement. This is as expected as XMLNode_1 stores the second member listed in XMLElement.

Returns the value of the node. The returned value depends on the type of the node.

Parameters

Parameter

Input Type

Description

none

 

 

Returns

Returns the node value as text.

Example

This example returns the node value of CVXMLNode001 into the simple text variable CVText001.