Reference Table

Definition

A Reference Table allows to manage a list of static values formatted as CSV. A CSV file can be uploaded through the administration console, its content will then be accessible from script rules.

The CSV file can sport 10 columns at most. There is no restriction on its line number.

The first line of the file must be a CSV header. CSV characters used for quoting and as delimiter, and CSV charset (default: UTF-8, ISO-8859-1 is also available) have to be defined when importing the file.

Use

A Reference Table will be namely used inside Choices rules of Attributes definition, or through the Select Widget to allow the user to choose the values ​​configured in the Reference Table.
Reference Tables are accessible in all script rules.
A table’s data is accessed either by index or by name using the header id.

All table values are of type "string".

In script rules, a Reference Table is accessed using the REF binding variable. A Reference Table is accessed via its id.

For example, with a Reference Table identified by “countries”:

// Get all values of the "countries" reference table which sports a single column
List<String> allCountries = REF.countries.list()
// Do something with allCountries...

The complete documentation of the REF API can be found in Reference Table.

Configuration

Properties

Property name	Type	Mandatory	Description	Values (default value in bold)
identifier	String	YES	Defines the unique id of each Reference Table. It is case sensitive and no special characters (except - or _) are allowed.	-
name	String	YES	Defines the name of each Reference Table. Specifying the name first allows you to define automatically the identifier. Maximum 128 characters. The name may be different from the identifier.	-
description	String	NO	Allows to describe the purpose of the attribute.	-
CSV Charset	-	NO	Allows to choose the character set of the CSV file.	UTF-8 ISO-8859-1
CSV Quoting	-	NO	Allows to choose the quoting character to escape characters matching the delimiter character.	" '
CSV Delimiter	-	NO	Allows to choose the delimiter character separating values in the CSV file.	, ;
CSV file upload widget	-	YES	Allows to upload the CSV file. The CSV file format must be coherent with the above options. The CSV file can be omitted when creating the Reference Table, it can be added later when modifying it.	-

Import CSV File parameters

Property name	Type	Mandatory	Description	Values (default value in bold)
charset	-	NO	Allows to choose the character set of the CSV file.	UTF-8 ISO-8859-1
quoting	-	NO	Allows to choose the quoting character to escape characters matching the delimiter character.	" '
delimiter	-	NO	Allows to choose the delimiter character separating values in the CSV file.	, ;
file	-	YES	Allows to upload the CSV file. The CSV file format must be coherent with the above options. The CSV file can be omitted when creating the Reference Table, it can be added later when modifying it.	-

Data structure

The content of a Reference Table can be represented by a simple CSV file, as illustrated by the following example:

The data structure is flat.

CSV file format

Description

Sample

The CSV file must respect the usual CSV conventions. It must contain: A list of headers, identified with an “header id” A list of values, generally called the “data” of the table Headers do not preserve values ​​with accents. Once the form is submitted, if no error occurs, the Reference Table is immediately created. CSV data is read using the configured charset. There is no limitation on the number of lines but if the CSV file is too large, a timeout may occur. The Reference Table may have been created anyway, this can be verified by displaying the list of Reference Tables. There are 10 columns maximum per table.

Reference_table_towns.csv

Update an existing Reference Table

When editing an existing Reference Table, only its first 10 lines are displayed (as read only). It is not possible to edit a single row, nor to search/display a specific value.

If an administrator wishes to inspect/modify the content of the Reference Table, they must:

• download the whole data as a CSV file (the separator/charset can be chosen)

• perform a local search/edit using Excel or any CSV editor, which is more suited to perform complex edition tasks such as adding a new column

• upload the whole CSV file again

It is not possible to modify individual values of the Reference Table. The whole CSV file must be submitted again after its correction.

When replacing a CSV file, new headers can be submitted, as all the original data will be erased/replaced.

Read Next