Form Builders

SeqDesk provides three form builders for customizing the data-collection forms that researchers and admins interact with: one each for order intake, study metadata, and sequencing-run assignment. Admins can add fields, organize them into groups (which become wizard steps), set validation rules, and control visibility.

Order Form Builder

At Admin → Form Builder (/admin/form-builder), customize the fields researchers see when creating orders.

How the Wizard is Built

The order creation wizard at /orders/new is constructed dynamically from the form configuration:

1. Each field group becomes a wizard step
2. Fields are shown in the step matching their group
3. Fields without a group appear in an “Additional Details” step
4. The Samples step always appears (for per-sample fields)
5. A Review step is always shown last

System Fields

These fields ship with every SeqDesk instance. They can be shown, hidden, or made required, but cannot be deleted:

Per-Order Fields (group: Order Details):

Per-Order Fields (group: Sequencing Information):

Per-Sample Fields:

Custom Field Types

Add custom fields of these types:

Field Configuration

For each field, you can set:

• Label — display name shown to researchers
• Visible — whether the field appears in the form
• Required — whether the field must be filled before submission
• Per-sample — if true, shown as a column in the sample table; if false, shown once per order
• Admin-only — if true, only visible to facility admins (hidden from researchers)
• Help text — guidance shown below the field
• Placeholder — example text inside the empty field
• Default value — pre-filled when the form loads
• Validation — regex patterns (including email/phone/url presets) and min/max values. AI-powered validation with custom prompts and strictness levels is available only when the ai-validation module is enabled

Field Groups

Fields are organized into groups that become wizard steps:

You can create new groups, rename existing ones, and move fields between groups.

Drag-and-Drop Ordering

Fields can be reordered within and between groups using drag-and-drop.

Module Dependencies

Some field types require their corresponding module to be enabled at Admin → Modules (/admin/modules). If a module is disabled, fields of that type are automatically hidden from the form regardless of their visibility setting.

The sequencing-tech module backs the sequencing technology selector and the barcode field type. It is always enabled and cannot be disabled, so those fields are always available.

Study Form Builder

At Admin → Study Form Builder (/admin/study-form-builder), customize the metadata fields for study creation.

This works similarly to the order form builder but applies to the study creation and editing forms. It is primarily used for:

• MIxS template configuration
• Institution-specific metadata fields
• Mandatory fields per study type

Sequencing Run Form Builder

At Admin → Sequencing Run Form Builder (/admin/sequencing-run-form-builder), customize the per-sample fields shown when assigning samples to a sequencing run. This is the third form builder, separate from the order and study builders, and it backs the sample table on the sequencing-run assignment page inside an order.

Typical fields configured here:

• Barcode (uses the dedicated barcode field type)
• Concentration (ng/uL), volume, library prep details
• Per-sample preparation notes
• Anything else that varies per run rather than per order or study

The same building blocks as the other builders apply: groups become wizard sections, fields support visibility/required/admin-only/help-text, and the JSON export/import flow lets you ship a default form via the --config flow.

This builder is the source of truth for the Run Assignment sample table — fields removed here disappear from the run assignment UI even if they were populated previously. Existing values stay in the database; they are simply no longer surfaced.

Import / Export and Defaults

Each builder has an Import / Export tab for moving form configuration between instances and recovering a clean starting point.

Export configuration

Use Export Configuration to download the current form builder state as JSON. Form exports are useful for:

• Back up your form configuration
• Copy settings between instances
• Share configurations with other facilities

Order form exports include order fields, fixed sections, and related order settings. Study form exports include study fields and fixed sections.

Import configuration

Use Import Configuration to upload a previously exported JSON file. Import replaces the current form builder configuration, so export the current setup first if you need a rollback file.

The importer accepts current exports and older exports that still contain custom groups. Legacy groups are mapped into the fixed sections used by the current builder.

Reset to Defaults

Use Reset to Defaults to restore the built-in SeqDesk form layout. This is helpful when testing customizations, recovering from a bad import, or preparing a clean form before adding facility-specific fields.

For the order form, reset restores the default order fields and fixed sections. It does not change post-submission instructions or data handling settings. For the study form, reset restores the default study fields and fixed sections.

Install-time presets

Exported JSON files can also be applied during installation:

seqdesk -y \
  --order-form-settings /absolute/path/order-form.json \
  --study-form-settings /absolute/path/study-form.json

For unattended deployments, the same paths can be stored in infrastructure-setup.json:

{
  "forms": {
    "order": "/absolute/path/order-form.json",
    "study": "/absolute/path/study-form.json"
  }
}