OptimiDoc Server Help Center
OptimiDoc Server Help Center
Breadcrumbs

List Parameter

The List parameter offers the operator a controlled selection from a set of options you define inline — departments, document types, project codes, and the like. Items are defined as key/value pairs and can be organised into a multi-level tree, so the operator drills down through groups to reach the right choice. Because the operator can only pick a defined item, list values stay clean and consistent.

What It Is

A List parameter presents a fixed set of options. You maintain the options directly in the parameter definition (as opposed to the external CSV, XML and JSON or SharePoint list types, which draw their options from an external source). Each item has a Key (the value stored and used in placeholders) and a Display Value (the text the operator sees). This split lets you show a friendly label while storing a compact code.

How It Renders on the Terminal

The device panel shows a selection control labelled with the parameter's Title:

  • Flat lists show all items as a single selectable list.

  • Long lists (more than 20 items) automatically switch to a searchable list, so the operator can type to filter instead of scrolling.

  • Hierarchical (tree) lists are navigated by drilling down: the panel first shows the top-level groups (marked with a folder icon); tapping a group opens its children, and so on until a selectable item is reached.

Whether a group (parent) node can itself be selected — or only the leaf items beneath it — is controlled by the Allow selecting group items option (see below).

Configuration

List items are defined in the Configuration section using the inline item editor. Each row has a Key and a Display Value, and a row menu lets you add a child, move the row up or down among its siblings, or delete it (deleting a group removes its whole subtree).

Control

Purpose

Add Item

Adds a new top-level row

Add child (row menu)

Adds a child row beneath the current row, creating a nested group

Move up / Move down (row menu)

Reorders a row (and its subtree) among its siblings

Allow selecting group items

When off (default), only leaf items are selectable and group rows act purely as navigation. When on, group rows can be selected as values too.

Each item's Key must be non-empty and unique; the editor flags duplicates and blocks saving until they are resolved.

Standard properties

Property

Description

Title

The display name shown to the operator, e.g. "Department".

Key

The parameter's internal identifier used in [key] placeholders, e.g. department.

Default Value

An optional pre-selected item, chosen from a dropdown of the defined (selectable) items. Can be overridden per workflow.

Required

Whether the operator must select an item before scanning.

Building a Hierarchical List

Trees are useful when a flat list would be too long. For example, a two-level "Document Type" list:

  1. Add a top-level row Key = invoices, Display Value = "Invoices".

  2. From that row's menu choose Add child, and enter Key = incoming, Display Value = "Incoming".

  3. Add another child Key = outgoing, Display Value = "Outgoing".

  4. Repeat for other groups (Contracts, Reports…).

On the panel the operator taps Invoices, then chooses Incoming or Outgoing. With Allow selecting group items off, "Invoices" is only a folder; with it on, the operator could also pick "Invoices" directly.

Using the Value

The placeholder resolves to the Key of the selected item — not its display text. For a parameter with key department whose selected item has key FIN and display value "Finance":

Location

Example

Result

Filename

[department]_[timestamp]

FIN_20260710093015.pdf

Folder path

Scans\[department]\

Routes into the FIN folder

Conditional destinations

Route based on the selected key

e.g. FIN → Finance archive

Metadata

(automatic)

The selected key is included in PDF metadata and the metadata sidecar

If you would rather store the friendly label, set the item's Key to that label as well.

List vs External List Types

Type

Data source

Best for

List

Items defined inline (key/value, optional tree)

Small to medium, admin-maintained lists

CSV / JSON / XML List

External file on the server

Lists maintained by another system or exported periodically

SharePoint List

On-premises SharePoint list

Data managed centrally in SharePoint

User List

OptimiDoc user directory

Selecting a person

All list types support the same tree navigation on the panel; only the source of the items differs.

Common Use Cases

Use Case

Key

Example Items (key → display)

Department

department

FIN → Finance, HR → Human Resources, IT → IT

Document type

doc_type

inv → Invoice, con → Contract, rep → Report

Office location

office

lon → London, prg → Prague, ber → Berlin

Priority

priority

low → Low, med → Medium, high → High

In Summary

The List parameter is the workhorse for controlled input: define your options once as key/value pairs, group them into a tree when the list grows, and decide whether groups are selectable or purely navigational. The operator gets a fast, error-proof selection on the panel — searchable when long, drill-down when nested — and your workflows receive a clean, predictable key every time.