Scan Parameters Reference | OptimiDoc Server Documentation

Scan parameters are reusable metadata fields that prompt the operator for input at scan time. A single parameter is defined once, linked to any number of scan workflows, and its collected value is then available throughout the workflow — in output filenames, destination folder paths, email fields, conditional routing, embedded PDF metadata, and metadata sidecar files — through the square-bracket placeholder [key].

https://optimidoc.atlassian.net/wiki/download/attachments/42860564/scan-parameters.png?api=v2

Screenshot: Scan Parameters Reference view

Overview

Scan parameters are defined globally in the OptimiDoc administration under Scanning → Scan Parameters and then attached to individual scan workflows on the workflow's Parameters tab. This separation lets a single definition (for example "Department") be reused across many workflows without duplication, and lets each workflow override the default value and control whether the operator may edit it.

When an operator runs a workflow, OptimiDoc prompts for each attached parameter on the device panel (or in the web scan client). The entered values travel with the job and are substituted wherever the corresponding [key] placeholder appears.

How Scan Parameters Work

A parameter has two identifiers that are easy to confuse but serve different roles:

The Title is the human-readable label shown to the operator on the device panel ("Department", "Invoice Date").
The Key is the internal identifier used inside placeholders. If the key is department, you reference the value as [department]. Keys are alphanumeric with underscores and must be unique.

The lifecycle is:

Define the parameter once under Scan Parameters — set its Title, Key, Type, an optional Default Value, whether it is Required, and any type-specific Configuration.
Attach it to one or more workflows on the Parameters tab, where you can reorder parameters (drag handle), override the default value for that workflow, and toggle whether the operator may edit it.
Collect the value when the operator scans — the panel renders the appropriate control for the type (keyboard, numeric keypad, toggle, calendar, selection list, or folder browser).
Substitute the value wherever [key] appears — filenames, folder paths, email fields, PDF metadata, watermark/signature text, and sidecar metadata files.

Parameter Types

OptimiDoc provides thirteen parameter types. The three external file-based list types share a single reference page.

Type	Panel control	Description
String	Keyboard	Free-text input for any text value
Number	Numeric keypad	Whole-number input with optional minimum/maximum bounds
Boolean	Yes/No toggle	Binary on/off choice, resolves to `True` or `False`
Date	Calendar picker	Operator selects a calendar date; supports a `[TODAY]` default
List	Selection list	Choice from inline key/value items; supports multi-level (tree) grouping
CSV, XML and JSON List	Selection list	Choice populated from an external CSV, XML or JSON file; supports tree grouping
User List	Searchable list	Choice from OptimiDoc user accounts, resolving to a chosen user attribute
SharePoint List	Selection list	Choice populated from an on-premises SharePoint list
Folder	Folder browser	Operator browses the workflow destination's folder tree and picks (or creates) a subfolder
Site	Site browser	Operator picks a SharePoint Online site/library for a SharePoint Online destination (no dedicated page yet — see below)
Password	Masked keyboard	Masked input for sensitive values such as PDF encryption passwords

The Site parameter type behaves like a Folder parameter but browses SharePoint Online sites rather than folders. It is used together with a SharePoint Online destination, typically paired with a Folder parameter so the operator first chooses the site and then the target library folder. It has no configuration or default value; its options come entirely from the bound destination.

Parameter Properties

Every parameter definition has these properties, regardless of type:

Property	Description
Title	The display name shown to the operator on the device panel or web client.
Key	The internal identifier used in `[key]` placeholders. Alphanumeric and underscores only; must be unique. The key cannot be changed after the parameter is created.
Type	The parameter type, which determines the panel control and the available configuration.
Default Value	An optional pre-filled value. The input shown here is type-specific (calendar for Date, list for List, and so on) and can be overridden per workflow.
Required	Whether the operator must provide a value before the scan can start.
Configuration	Type-specific settings — list items, external file paths, SharePoint connection details, or numeric bounds. String, Boolean, Date, Password, Folder and Site have no additional configuration.

Whether the operator may edit a value at the panel is not a property of the definition — it is set per workflow on the Parameters tab, alongside the per-workflow default-value override. Set a parameter to non-editable there to enforce a fixed value.

Placeholder Tokens

Anywhere OptimiDoc accepts a dynamic string — the output filename, a destination folder path or connection string, email subject and body, PDF metadata, watermark and signature text — you can insert placeholders in square brackets. At scan time each token is replaced by its value; unknown tokens are left untouched, and a token whose value is empty is replaced by an empty string.

To insert a parameter value, wrap its Key in brackets: a parameter with key department is referenced as [department]. In addition to your own parameters, these built-in tokens are always available in scan workflows:

Category	Tokens
Date and time (scan time)	`[timestamp]` (yyyyMMddHHmmss), `[current_year]`, `[current_month]`, `[current_day]`, `[current_hours]`, `[current_minutes]`, `[current_seconds]`
User	`[user_name]`, `[user_login]`, `[user_email]`, `[user_homedir]`, `[user_department]`, `[user_givenname]`, `[user_surname]`
Device	`[device_name]`, `[device_ip]`, `[device_model]`, `[device_location]`, `[device_sn]`, `[device_id]`
Workflow and file	`[flow_name]`, `[file_name]` (original file name without extension), `[file_name_extension]` (original file name with extension)
Parameters	`[yourkey]` — the collected value of any parameter attached to the workflow

Using Parameter Values

Typical places a parameter value is used, referencing the key department as an example:

Location	Example
Output filename	`[department]_[current_year][current_month][current_day]` → `Finance_20260710.pdf`
Destination folder path	`\\server\share\[department]\` routes scans into per-department folders
Email subject / body	`Scan from [department]`
Conditional destinations	Route the document to a different destination based on the value
Embedded PDF metadata	Every non-password parameter is written into the output PDF's document properties, keyed by its parameter key
Metadata sidecar	When metadata output is enabled, each value is written to the XML/CSV/JSON index file next to the scan, using the parameter key as the field name

Choosing the Right Type

Need	Recommended type
Free-text metadata (titles, descriptions)	String
Whole-number codes with optional bounds (invoice, cost centre)	Number
Yes/no flags (confidential, urgent)	Boolean
Calendar dates (document date, expiry)	Date
Small fixed or grouped selection	List
Large or externally maintained selection	CSV, XML or JSON List
Selection from OptimiDoc users	User List
Selection from on-premises SharePoint data	SharePoint List
Let the operator pick a destination subfolder	Folder (or Site for SharePoint Online)
Sensitive input (encryption passwords, PINs)	Password

In Summary

Scan parameters turn a static scan workflow into an interactive one: the operator supplies context at the panel, and OptimiDoc weaves those values into filenames, folder structure, metadata, and routing decisions. Define each parameter once with a clear Title and a stable Key, attach it to the workflows that need it, and reference it as [key] wherever a dynamic value is accepted. Choose the type that matches the data — free text, bounded numbers, controlled lists, users, or destination folders — so the panel presents the operator with the right control and the captured data stays clean and consistent.

Scan Templates — Overview of scan workflow configuration
Parameters Tab — Attaching parameters to workflows and per-workflow overrides
Output Options — Filename patterns, metadata output and conditional destinations