CSV, XML and JSON List Parameters

CSV, XML, and JSON list parameters populate a selection from an external data file on the OptimiDoc server. They suit lists that are large, change often, or are maintained by another system — and, like the inline List type, they support multi-level (tree) grouping so the operator can drill down to a choice.

Overview

When the options are too many for an inline List, or are produced by another system, an external list parameter reads them from a file. OptimiDoc supports three formats:

All three present the same selection interface to the operator — only the source format differs — and all three support hierarchical (tree) lists.

How It Renders on the Terminal

The device panel shows a selection control labelled with the parameter's Title. As with the inline List type, lists of more than 20 items become searchable, and hierarchical lists are navigated by drilling down through their groups. Each item has a stored key and a displayed value; the operator sees the value, and the key is what the workflow receives.

Hierarchy (Tree) Support

Each format expresses parent/child relationships by giving an item the key of its parent:

• CSV — an optional third column holds the parent key.

• JSON — an optional parentKey property on each object.

• XML — an optional Parent element or attribute, configured alongside Key and Value.

Items with no parent are top-level; items whose parent key matches another item's key become its children. The Allow selecting group items option decides whether a parent (group) item can be chosen directly, or acts only as a navigation folder.

CSV List Parameter

Configuration

File format

Each line is key,displayvalue with an optional third column for the parent key. No header row:

FIN,Finance Department
HR,Human Resources
MKT,Marketing

With a single column, the same text is used as both key and display value. With three columns, the third builds a tree:

inv,Invoices,
in,Incoming,inv
out,Outgoing,inv

Here "Incoming" and "Outgoing" are children of "Invoices". Values are split on commas, so commas within a value are not supported — use JSON or XML if your data contains commas.

JSON List Parameter

Configuration

File format

An array of objects, each with a key, a value, and an optional parentKey:

[
  { "key": "inv", "value": "Invoices" },
  { "key": "in", "value": "Incoming", "parentKey": "inv" },
  { "key": "out", "value": "Outgoing", "parentKey": "inv" }
]

The property names key, value, and parentKey are recognised (the capitalised forms Key, Value, ParentKey also work). A legacy flat object of "key": "value" pairs is still accepted for simple lists.

XML List Parameter

Configuration

Child-element form (Use Attributes off)

<departments>
  <department>
    <id>FIN</id>
    <name>Finance Department</name>
  </department>
</departments>

Element Name = department, Key = id, Value = name.

Attribute form (Use Attributes on)

<departments>
  <department id="FIN" name="Finance Department" parent="" />
  <department id="FIN-AP" name="Accounts Payable" parent="FIN" />
</departments>

Element Name = department, Key = id, Value = name, Parent = parent, Use Attributes = on.

Prefetch and Automatic Refresh

Either way, OptimiDoc watches the file: when the file's modification time changes, the cached list is reloaded automatically on next use — editing the file does not require a service restart.

File Location Requirements

• The file must be reachable from the OptimiDoc server, not the device.

• Use a local path (C:\Data\lists\) or a UNC path (\\fileserver\share\lists\).

• The OptimiDoc service account needs read access to the file (and network access for UNC paths).

• Save files as UTF-8 so accented and special characters display correctly.

Using the Value

The placeholder resolves to the key of the selected item. For a parameter with key department where the operator picked the item keyed FIN:

Choosing the Format

Troubleshooting

In Summary

External list parameters keep large or system-managed option sets out of OptimiDoc and in a file that the right team can maintain. Pick the format that fits your data — CSV for simple exports, JSON for structured data, XML for attribute-rich or legacy sources — add a parent column/property/element for tree navigation, and let automatic refresh keep the panel current without a restart.

Related Articles

• Scan Parameters Reference — Overview of all parameter types and the [key] placeholder syntax

• List Parameter — Inline key/value list with the same tree support

• SharePoint List Parameter — SharePoint-sourced list

• Parameters Tab — Attaching parameters to workflows