XML Import Module

The XML Import Module is used to import numeric data from an XML file into ION. This module is only available in the VIP.

Module icon

This module is intended for use by personnel with a working knowledge of XML and xPath.

Overview

Inputs

Enable

When this input is OFF, the XML Import module is disabled and pulses received at the Read Now input are ignored. This module is enabled by default.

Read Now

When this input is pulsed, the file is loaded and the results of the xPath queries contained in the xPath Query setup registers are copied into their corresponding Data output registers. A link to the Read Now input is mandatory or else the module will not go online.

Setup registers

URL

This register specifies the location of the XML file. The value range for this register is 0 to 80 alphanumeric characters (dash and dot allowed).

Here is an example URL for a fictional weather website containing local weather data in XML format:

http://www.myweather.com/xml/current_obs/myhometown.xml

NOTE: The URL is displayed as a string of text in your web browser’s address or location bar.

Namespace

This register specifies the XML namespaces associated with the elements you query from the XML source. The value range for this register is 0 to 80 alphanumeric characters (dash and dot allowed). This information is only needed to resolve XML data or routing issues, and is usually not required. The XML namespace information is found in the xml source, and is listed on the lines beginning with “xmlns”.

NOTE: To view the XML source, navigate to the xml webpage using a web browser such as Internet Explorer. Right-click on the webpage and select View Source.

Here is a namespace example using a fictional weather website:

xmlns:mhome='http://www.myweather.org/myhometown'
xmlns:mwork='http://www.myweather.org/myworktown'

When entering the XML namespace, make sure you use the correct syntax, including the single quotes around the namespace URI and separating multiple namespaces with a single space.

NOTE: A namespace uniquely identifies a set of names so that there is no ambiguity when objects with different origins but the same names are mixed together. A namespace is commonly given the name of a Uniform Resource Identifier (URI) - such as a website address - both because the namespace may be associated with the site or page of that URI (for example, a company name) and because a URI is likely to be a unique name.

Event Priority

This register allows you to assign a priority level to the following events produced by the XML Import module:

The xPath query returned a NULL node (could not locate any data)
The xPath query returned a non-numeric node

The priority level you specify applies to all of the above events. The default value is 128.

XPath Query 1 to n

The xPath query is used to retrieve the data from the XML file. Each query must return a single, numeric value. The content of this register must match the XML element of the data you want to retrieve.

Here is an example query to get the temperature in degrees Celsius from a fictional weather website:

/current_observation/temp_c

This query will return 3.0 from the fictional weather website XML file excerpt shown below:

<current_observation version="1.0"
xmlns:myhome="http://www.myweather.org/myhometown">
...<weather>overcast</weather>
<temp_f>37.0</temp_f>
<temp_c>3.0</temp_c>
<relative_humidity>56</relative_humidity>
...
</current_observation>

NOTE: XPath Query can only return numeric data or equations. In the example above, querying / current_obervation/weather will return an error.

Output registers

Data 1 to n

These registers contain the results of their associated XPath Query.

Load Complete

This register pulses when the XML file is successfully read.

Event

All events are recorded in the Event register.

Possible events and their associated priority numbers are:

Event priority group	Priority	Description
Setup Change	10	Input links, setup registers or labels have changed.
Custom	*	Query returned NULL node; query returned non-numeric node.
Failure	*	File did not load or could not be parsed.
* The priority of these events is determined by the value in the Event Priority setup register.

The Event output register stores the following information for each ION event: time stamp, priority, cause, effect, and any values or conditions associated with the cause and effect.

Responses to special conditions

The following table summarizes how the XML Import module behaves under different conditions.

Condition	Response of output registers
File cannot be read	All Data outputs are n/a
Query returned NULL or non-numeric node	Corresponding data output is n/a
After the module is re-linked or setup registers are changed	All Data outputs are n/a
When the Virtual Processor is first started or a module is newly created	All Data outputs are n/a

Detailed module operation

When the module's Read Now input is pulsed, the xml file referenced in the URL setup register is read, and any namespace information supplied in the Namespace setup register is applied. When the file has been read, the Load Complete output register pulses. The XPath Query specified in each XPath Query setup register is executed, and the result appears in the corresponding Data output register.

For the module to function, the xml file must be located at the specified location or URL. If you want to verify the location of your xml file, open Windows Explorer and check the directory structure or check the URL.

An example framework in the Virtual Processor that makes use of an XML Import module is shown in the next diagram. To track energy consumption against temperature, you can set up an XML Import module to get temperature information from a weather website, with a Periodic Timer module to trigger the XML Import Module’s Read Now register. This temperature information is stored in a Data Recorder Module in the Virtual Processor. When combined with meter energy data, you can correlate energy usage and local temperature.

NOTE: The Arithmetic Module does not perform any calculations on the data. You need the Arithmetic Module in order to make a duplicate recording of the meter data within the Virtual Processor. Otherwise, you can incorporate the meter data from the meter’s data recorders.