...

The ACE Configuration Management (ACM) Utility is a tool for managing XML configurations for the Elecsys RediGate or Director or RediGate products that are created in the Elecsys ACE Editor software.

This utility provides the following features:

• Retrieve a filtered list of ACE XML configuration names and descriptions.

• Modify the list of included configurations Select a subset of configurations to be used for subsequent Query or Modify actions.

• Run an information query on all included configurations using XPath query definition.

• Run a modification query on all included configurations using XPath.

• Modification queries might change a value, substitute XML content, remove/add an XML child object, etc.

• Select and import tags from an Allen Bradley L5X file to poll PLC data using ACE configuration.

Because the tool is designed to perform a set of actions on a group of configurations, it is ideal for batch queries or batch modification of configurations to update ACE properties, add new features, etc. The Elecsys ACE Editor is still needed to view and upload configurations, and will still be used for individually setting properties or adding objects to a single configuration.

The master copy of this ACM utility spreadsheet can be opened, configured for individual combinations and varieties of queries, and saved under different names for future reference. It is not required that the ACM spreadsheet retain its originally distributed filename. This will allow a user to keep multiple logs of information obtained from devices or results of a modification action.

...

The ACE Configuration Management (ACM) Utility is a Microsoft Excel workbook, which includes Visual Basic macros. This platform was chosen for its wide support on Windows operating system, which is also required for the Elecsys ACE Editor; and because Excel Visual Basic for Applications (VBA) supports XPath and XML methods.

...

Test the ability to run macros by clicking the ">> Go to SetupMain Menu" button on the About sheet.

Other Utilities

In addition to the ACE Configuration Management ACM Utility and the ACE Configuration Editor software, the following utilities are also recommended for help in designing the XPath queries used in the utility:

• A good text editor, such as Notepad++, to view XML files. (This will help by showing the XML structure of the configuration.)

• A good text diff program, such as WinMerge, to view differences between the original and modified XML files. (This is useful when designing the XPath queries, to ensure that XML changes are made as intended.)

...

Main Menu

...

On the About page, click the ">>Go to SetupMain Menu" button. Or click on the tab for the Setup sheet. Make the following settings:This will open a menu to select the location of ACE XML configurations, the output of modified files, and provides a menu of actions to perform.

Configuration Path: Enter the path where Click the Configuration Path button and browse to the folder containing ACE XML configurations are found.

For instance, C:\Users\username\Documents\Elecsys\ACE\CFG

FileName Filter: (optional) Enter a filename criteria to select a subset of the XML files.

Examples: *.XML xml (this is the default filter)

abc*.xml

or the Configuration Path could be “C:\Users\username\Documents\Elecsys\ACE”
and the FileName Filter could be “CFGinclude a subfolder such as “myfiles\*.xml”

Output XML Path: (optional) Enter the path Click the Output XML Path button and browse to the folder where the (modified) output XML files will be stored. This is only used with Modify actions.
If the Output XML Path is blank, output files will be stored in the same as the Configuration Path.

...

OriginalConfigurationName_MOD.XML

NOTE: If you use the same Output XML Path as the source Configuration Path and no do not use an Output File Suffix then the output file will overwrite the original configuration! This is not recommended.

...

After setting up the paths, filter, and file suffix, click the "> List Configurations <" button. This will generate a list of configuration names based on the above criteria. The configuration names appear on the Configurations sheet.

...

Configurations Sheet

The Configurations sheet lists the names and descriptions of XML configuration files that will be queried or modified by this utility. Only ACE XML configurations (with a TemplateProperties/Description XML field) will be included automatically in the list. You can click on the tab for the Configurations sheet at any time, or click the ">> Go to Configurations" button.

After clicking the "> List Configurations <" button on the Setup sheet Main Menu page, you will automatically be taken to the Configurations sheet.

...

The configurations are automatically marked with "1".
The Query, Modify, or Modify L5X actions will only act only on the configurations with a 1 “1” in this column.
You can exclude configurations by just changing the "1" to something else, or deleting unneeded rows, or by clearing the cellscell contents. Any row with a blank Configuration Name will be treated as the end of the list for all actions.

Configuration Name

The configuration names listed are based on obtained from the Configuration Path and FileName Filter on the Setup pageMain Menu dialog. If there are many configurations listed that you don't want to query, you can change the filter and re-run the list.
You can also manually enter configuration names in this column – you don't have it is not required to use the "> List Configurations <" button.

Description

The Description column is obtained from the <TemplateProperties> property in the ACE XML configuration file. It This column has no purpose in the ACE Management UtilityACM utility, other than for information.

...

The Query sheet is used to request information from each XML configuration included on the Configurations sheet. After setting up the list of configurations on the Configurations sheet, define one or more XML queries on the Query Configurations sheet includes buttons that will take you to the Query, Modify, or L5X Tags sheet in order to set up queries or other actions.

...

Query Sheet

The Query sheet is used to request information from each XML configuration included on the Configurations sheet.

• Query rows must begin on the visible row immediately below the "Column Header" (row 15).

• After defining the Select Query (one or more rows), click the "> Run Query Configurations <" button. This will run the listed Query definitions for request information using each Select Query from each configuration on the Configurations sheet that has a "1" in the Include column.

• The results of all queries for all configurations will be stored on the Query Results sheet.

...

The Column Header defines one or more columns of data to be stored on the Query Results sheet. The Column Header is just descriptive, but does need to be non-blank.

Any Query definitions following a row with containing a blank Column Header will not be run. This can be used (be treated as the end of the list, and Run Query definitions following a Column Header will not be run. This can be used (by inserting a blank row) to run only a few of limit the list Query definitions for testing, then delete the blank row to run additional subsequent queries.

If the Column Header ends with square brackets enclosing a positive integer number (e.g., “[2]”), it will create multiple columns in the Query Results sheet based on the number in brackets. The number defines the maximum number of columns in Query Results that will contain XML data matching the Select Query (XPath) criteria.

If the Select Query returns fewer XML nodes than the defined columns, the rest of the columns will contain “n/a”. If the Select Query matches more XML nodes than the columns allow, the rest of the data will be omitted from Query Results.

Example:

If Column Header is "Ethernet IP[2]", it will create two columns on the Query Results page. The columns will be labeled "Ethernet IP(1)" and "Ethernet IP(2)". If the Select Query yields the IP address of Ethernet port objects, only the first two will be listed in these columns.

Be aware that if using a fixed number of columns and the Query that you are using returns more XML nodes than are allowed to be displayed by the Column Header, it may give the false impression that there aren't as many nodes as there actually are.

If the Column Header ends with [0], it will create only a single column in Query Results, but if . If the Select Query returns multiple nodeselements, the contents of each node is separate by braces element will be included in the single column, separated by braces { }. If the Select Query returns only a single node, it will be shown without braces.

Example:

If Column Header is "Ethernet IP[0]", it will create one column on the Query Results sheet. The column will be labeled "Ethernet IP" and may include contents such as: "{10.95.213.86}{192.168.100.1}".

...

This column has no purpose and is only descriptive to help remember document what the Query definition is used for.

Select Query

The Select Query column uses XPath notation to select syntax to define selection criteria for one or more XML nodes in each configuration file. The elementselected node(s) selected (one or more, depending on the Column Header) will have their text stored in the Query Results page. See the section Understanding XPath Queries for help in understanding XPath query format used in the ACE Management Utility.

If there is a row with a non-blank Column Header but a blank Select Query, it will create a spare column in results, with no dataan empty column under its column header on the Query Results page.

Condition Query

The Condition Query column is currently unused. It may eventually support the ability to include an additional condition for whether or not to include XML nodes obtained in the XPath query.

...

Understanding XPath Queries

XML is a structured document format that uses a nested hierarchy of parent/child elements. The Elecsys ACE Editor (version 3.0 and higher) uses XML for both the template and configuration definitions.
XPath is a very powerful query language that allows a complex set of criteria to search an XML document. See www.w3schools.org for more generic information and tutorials on XML and XPath.

...

An EtherPort object in the ACE Editor defines the Ethernet network interface. It is represented in the configuration file by the following XML Below is a picture of the ACE properties for Ethernet object with Type=EtherPort and Instance=0 (DownFile=netethr0).

...

This object is represented in the XML configuration file using the following XML text (abbreviated here ) such asto include only a few properties):

<Node Type="EtherPort" Name="EtherPort0" Enabled="Yes">

...

</Node>

XML syntax consists of elements :

• Elements, defined by a tag structure (such as <Node>, <Properties>, and <Field>)

...

• Attributes (such as Type, Name, and Enabled)

...

• with values (such as “EtherPort” and “Yes”)

• Text content within XML elements (such as "netethr0", "10.63.191.26", and "EtherPort0").

All XML elements must have an opening and closing tag (such as <Node> and </Node>) and be properly nested. Note that XML is case-sensitive, so you must ensure that all queries use the proper case.

XPath Example 1 – selection of XML nodes for Ethernet IP Address

On the Query or Modify sheet, you can define a Select Query such as:

//PropertiesNode[DownFile@Type='netethr0' || DownFileEtherPort' and Properties/Instance='netethr10' ] ~~~ .. /Fields/Field[@Name='Network Card IP']/Value/text()

• This XPath query first locates all XML elements called <Properties> (every with a tag <Node>. Every visible object in the ACE configuration has one)Configuration Editor starts with <Node>. The initial double forward slashes (//) at the beginning of the XPath statement finds any element called <Properties><Node>, no matter how deep deeply it is nested in the XML document. Using a single forward slash (/) would begin at only include elements beginning with the topmost (root) element of the XML file.

• The above XPath query is further limited to <Properties> using square brackets [ ] with an XPath qualifier (predicate). This example includes only <Node> elements which have an attribute (indicated with the leading “@”) of ‘Type=EtherPort', and a child element called <DownFile>, with a text content of either "netethr0" or "netethr1" (i.e., ACE uses these values to define objects for the eth0 and eth1 interfaces in Linux). XPath uses square brackets [ ] after an element name to provide one or more qualifiers (predicates) to select specific XML nodes.

A special notation used in the ACE Management Utility (not part of XPath) is the "~~~" notation, which may be used to chain together two XPath queries where necessary. In the above example, two separate XPath statements are joined together sequentially with "~~~". The ACE Management Utility only currently supports up to two joined statements.

• In this example, the first XPath statement selects the <Properties> element from two different ACE "EtherPort" objects (netethr0 and netethr1). The second XPath statement begins with "..", which moves up a level to the <Node> parent of both <Properties> elements.

• Then the XPath query descends through the children of those elements: <Fields><Field><Value>
  Note that the <Field> elements of an ACE object include all the first-level properties shown in the ACE Editor. In this example, this includes the IP address, Subnet Mask, and Default Gateway of an Ethernet object definition.

• The <Field> element above is further qualified to only include those elements with an attribute (using a leading "@" symbol) whose "Name" is equal to "Network Card IP". Thus, at this point in the XPath query, we have selected two nodes: the IP address XML element of both "netethr0" and "netethr1" (if they both exist in the ACE configuration).

• The second XPath query further descends into each <Field> element (whose Name="Network Card IP"), to the <Value> element, and finally to the text content of <Value>, using the syntax "text()". When retrieving the text content inside a <tag>...</tag> structure, the "/text()" suffix is required at the end of the XPath query in most cases; omitting it will return the XML that includes “<tag>text</tag>”, rather than just the “text” value.

...

• ‘<Properties><Instance>’ tag containing a value of 0. This defines the ACE Ethernet object with an instance number of 0.

• Note that either single-quotes or double-quotes may be used XPath queries, but they must be used consistently in matched sets.

• For any <Node> (one or more) matching the above criteria, the XPath query further limits the selection to <Node> elements that have direct child elements <Fields><Field> (with attribute 'Name=”Network Card IP’). This selects for the XML element containing the IP address of the Ethernet object.

• Note that the <Field> elements of an ACE object include all the first-level properties shown in the ACE Editor. In this example, this includes the IP address, Subnet Mask, and Default Gateway of an Ethernet object definition.

• After finding this matching <Field> (one or more), the XPath query ending with /Value/text() returns the text included between the <Value> and </Value> tags.

• Note that when selecting plain text between opening and closing tags, the query must end with “/text()”. It is not typically necessary to use “/text()” inside of square bracket qualifiers, as shown with Properties/Instance='0'.

XPath Example 2 – using chained XPath queries

A special notation used in the ACE Configuration Management Utility (not part of XPath syntax) is the "~~~" notation, which may be used to chain together two XPath queries, if necessary. The above example used a single XPath query to request the IP address of EtherPort object(s) with Instance=0. The same query could be done in the ACM using two separate XPath statements, joined together sequentially with "~~~". The ACM Utility only currently supports up to two joined statements.

//Properties[DownFile='netethr0' || DownFile='netethr1'] ~~~ ../Fields/Field[@Name='Network Card IP']/Value/text()

• In this example, the first XPath statement selects the <Properties> element from up to two different ACE "EtherPort" objects, containing a child <DownFile> tag with text of either ‘netethr0’ or ‘netethr1’. This is equivalent to selecting an <Instance> tag with text of either ‘0' or '1’.

• After the first XPath query has selected one or more <Properties> elements, the second XPath statement begins the set of selected elements and performs an additional qualifying selection. In this case, the second statement begins with "..", which moves up a single level to select the parent <Node> of each of the <Properties> elements. (Multiple sets of ../../../ can be used to move up more than one level.)

• Then the second XPath query descends through the children of those <Node> elements: <Fields><Field> (where the attribute is qualified to included only Name=”Network Card IP”), and the text within its <Value> element.

• After applying both XPath queries, the query will have selected two nodes: the IP address of both "netethr0" and "netethr1" (if they both exist in the ACE configuration).

• Note, again, that the “~~~” notation is part of ACM only and is not standard XPath.

XPath Example 3

As a second example, we can define a Select Query similar to the example above using only a single XPath statement, not requiring the chaining of two statements (i.e., avoiding the "~~~" notation that is unique to the ACE Management Utility).

...

Using a single row in the Query (or Modify) sheet with one of the above two examples, we will have the following Query definition:

Assuming the configuration(s) listed on the Configurations sheet have one or more Ethernet objects configured, the resulting data on the Query Results sheet might look something like this:

Note that in this example, we purposely defined the Column Header to include three columns, but the first configuration only has two Ethernet nodes, and the second configuration only has one. The remaining columns will be included in Query Results,but will be populated with "n/a" if there are no XML nodes matching the XPath criteria defined in Select Query.

...

Note that we haven't limited the <Instance> numbers to specific Ethernet objects, as in the previous examples. The Query Results might be:

Retrieving an attribute

If you wish to get the value of an attribute, as opposed to the text content inside a “<tag>...</tag>” structure, use the "@" symbol with the attribute name. For instance, to get the visible name of the ACE object representing the eth0 Ethernet configuration, you might use a Select Query like:

...

Enter data for Column Header, Mod Type, Source Data/File, and/or Source Query, and click the "> Test XPATH <" button. The basic rules for these columns are followed, as described in the section Modify Sheet. The main differences are:

1. When clicking the "> Test XPATH <" button, the query and action are performed ONLY on the same row as the currently-selected cell.

2. The Number of Child Nodes column (H) gives the count of nodes requested by the Select Query, regardless of whether the query ends with "/count()".

3. The Select Query XML column (I) contains all queried nodes, separated by braces { }, as if the Column Header ended with [0].

4. The Modify Results column (J) contains the results of any Modify action, separated by braces { }, as they would appear in multiple columns of the Modify Results sheet.