Property Loader Plugins

TestStand 2016 Help

Edition Date: August 2016

Part Number: 370052R-01

»View Product Info
Download Help (Windows Only)

File Formats

The Property Loader step type and the Import/Export Properties tool includes file plugins to support .csv, .txt, and .xlsx (Microsoft Excel) file types. This topic describes the required delimiter characters, file structure, special property formats, and property aliases for these file formats.

Notes Notes

Delimiter Characters

Column Delimiters

The primary difference between the file types is the delimiter character used to separate columns of data. The following table describes the column delimiter used for each file format:

File Format Column Delimiter
.csv Comma
.txt Tab character
.xlsx None. .xlsx files should be opened and edited with Microsoft Excel or another application capable of supporting .xlsx files.

Row Termination Characters

In all file formats, new-line characters are used to terminate each row of data.

Field Delimiters

Data values, or fields, within the file may optionally be enclosed in double quotes. However, when certain characters are present in a field, the field must be enclosed in double quotes. The following table describes the cases in which fields must be enclosed in double quotes:

File Format Cases Where Field Must Be Enclosed in Double Quotes
.csv
  • Fields containing commas
  • Fields containing leading or trailing spaces
  • Fields containing line breaks
  • Fields containing double quotes. When a field contains double quotes, each double quote must be preceded by another double quote to serve as an escape character.
.txt
  • Fields containing tab characters
  • Fields containing leading or trailing spaces
  • Fields containing line breaks
  • Fields containing double quotes. When a field contains double quotes, each double quote must be preceded by another double quote to serve as an escape character.
.xlsx None. It is not necessary to enclose fields in double quotes in .xlsx files.

File Structure

See the following image for an example of a Property Loader source file in the correct structure for use with the Property Loader plugins.

Note Note  The file shown is in the Microsoft Excel format, but the same file structure applies to all file formats.

file structure example image

The purpose of each element in the file is described in the following table:

File Element Position in Example File Purpose
<PropertyGroup> start and end markers Cells A1, A6 Indicate the beginning and end of the TestStand property data to be imported from the file. The <PropertyGroup> start marker contains the name and ID of the data, and should be unique within the file. Optionally, a description can be included in the <PropertyGroup> start tag.

Any data that is not enclosed within the <PropertyGroup> start and end tags is ignored.
<Sequence> column header Cell A2 Indicates that this column represents the name of the sequence that each property will be imported into. If the sequence name for a property is blank, the property will be imported into all sequences.

Note: This column is optional. If the <Sequence> column does not exist in the file, all Locals, Parameters, Sequence Attributes, and step properties will be imported into all sequences within the sequence file.
<Category> column header Cell B2 Indicates that this column represents the location of each property. The location can be one of the following literal values:
  • {StationGlobals}—Indicates that the property is a station global variable.
  • {FileGlobals}—Indicates that the property is a file global variable.
  • {Locals}—Indicates that the property is a local variable within a sequence.
  • {Parameters}—Indicates that the property is a sequence parameter.
  • {Attributes}—Indicates that the property is a sequence attribute. If the name defined in the <PropertyGroup> start tag is GlobalProperties, the property is instead a sequence file attribute.
If the category is not one of the above values, the category must specify a value the can uniquely identify the step property. Typically, that is either the name or ID of a step, and the columns to the right specify the property of the step. See the Identifying Steps section below for more information about supported step name and ID formats.
<PropertyLookup> column header Cell C2 Indicates that this column represents the lookup string of each property. If the value is enclosed in angle brackets (< and >), the value represents an alias name.

If the file was exported with type information, this column will also contain the type information after the lookup string, enclosed within curly brackets ({ and }).
<Value> column header Cell D2 Indicates that this column represents the value of each property to be imported.
Property data for simple data types (string, number, boolean) Row 3 Each string, numeric, or boolean property is represented by one row in the file.
Property data for containers Rows 4, 5 Each container is represented by two rows in the file. The first row contains the names of each field in the container, and the second row contains the values of each field. Note that additional columns are used to represent container fields and values.

Identifying Steps

When the file contains data associated with step properties, either the step name, step ID, or both should be specified in the <Category> column. The following image demonstrates each method of identifying a step within a file.

step name example image

Special Property Formats

The following sections describe the file format for properties in arrays and nested containers.

Arrays

See the following image for an example of a file containing an array of numbers:

array example image

In this example, cell C3 contains the lookup string of the array, followed by information about the dimensions of the array enclosed in curly brackets {}. Rows 4-8 represent the value of each element in the array, with the value of the <PropertyLookup> column indicating which element in the array is represented by the row of data.

Nested Containers

See the following image for an example of a file with a container property that contains another container as a field:

nested container example image

In this example, the local variable SampleContainer, represented on rows 3 and 4, includes a field named SubData, which is also a container. Note that the field names and values for the SubData container are represented on rows 5 and 6 of the file, below the rows for basic data type fields within the parent container.

Property Aliases

The Property Loader allows you to optionally specify alias names for properties within a file. Aliases allow you to refer to properties within the file with meaningful names, rather than a property lookup string. When a file contains aliases, a .pla (Property Loader Alias) file must be associated with the file. The .pla file contains the mapping between aliases and property lookup strings.

Using Aliases within a Limits File

When aliases are used within a file, the <PropertyLookup> column will be replaced with an <AliasName> column. See the following image for an example of a file with aliases instead of property lookup strings:

alias example image

Column C in this example contains the alias name for each property defined in the file.

Property Alias Files

In order for the Property Loader to load properties with alias names into a sequence file, a .pla file must be specified when the file is imported. The .pla file is encoded in XML, as seen in the following example:

<?xml version="1.0" encoding="utf-8"?>

<AliasItems xmlns:ts="www.ni.com/TestStand ">

<AliasItem AliasName="Test Result Value" PropertyLookup="Sequence[MainSequence].Locals.TestResult" />

<AliasItem AliasName="Test Data Source" PropertyLookup="Sequence[MainSequence].Step[My Test Step].DataSource" />

</AliasItems>

In this example, each <AliasItem> tag defines an alias and its associated property lookup string.

The .pla file will be created automatically during the export process if aliases are defined, and can be modified outside of TestStand if the alias names or property lookup strings need to be updated.

WAS THIS ARTICLE HELPFUL?

Not Helpful