Form Builders

Almost every question SeqDesk asks a researcher is configurable. Three separate builders own three separate forms:

They share the same field model — type, label, visibility, required, help text, validation — but they are stored separately and edited separately. Nothing you do in one affects the others.

Sequencing Order Form Builder

Five tabs across the top of /admin/form-builder:

How the wizard is assembled

The order wizard at /orders/new is generated from the configuration:

1. Each section becomes a wizard step, in section order.
2. Fields appear in the step matching their section.
3. The Samples step always appears and renders the per-sample fields as table columns.
4. A Review step is always last.

Sections are fixed

Per-sample fields, facility-only fields and MIxS fields are exempt from this mapping — they are placed by their tab, not by a section.

System fields

These ship with every instance. They can be shown, hidden, relabelled or made required, but not deleted.

Sequencing Order Details

Sequencing Information

Per-sample

Facility-only, shipped and admin-only from the start:

Field types

Two placement rules are enforced by the model rather than by the UI:

• mixs, funding, billing and sequencing-tech are order-level only.
• organism and barcode are per-sample only.

Per-field settings

Fields can be reordered by drag and drop within and between sections.

Module dependencies

A field type whose module is off is hidden everywhere, regardless of the field’s own Visible setting. This is the fastest way to remove a whole class of questions.

The study builder shows a banner — “N fields hidden because related modules are disabled” — with a link to Modules, which is the quickest way to diagnose a field that vanished.

The Settings tab

Advanced Settings holds two blocks that are not about fields at all:

• Post-Submission Instructions — free text shown to a researcher after they submit a sequencing order. Use it for shipping addresses, labelling conventions and drop-off hours.
• Data Handling — two switches, shared with Settings → Accounts:

Neither is restored by Reset to Defaults.

Study Form Builder

/admin/study-form-builder, headed Study Configuration. Four tabs: Study Fields, Per-Sample, Facility Fields, Import / Export. It also autosaves.

Four counters across the top give an at-a-glance summary: fields visible to researchers, facility-only fields, user per-sample fields, and fields hidden by disabled modules.

Study fields are filled once per study — principal investigator, study design, research objectives — while per-sample study fields are collected for every sample the study contains. The MIxS selector normally lives here, which is how a study’s environment checklist is chosen.

With the dynamic-studies module enabled, the sidebar entry changes to Define Studies (/admin/study-definitions) and a study can carry its own questionnaire instead of sharing one global form. Opening the builder for a specific study shows “Editing this study’s own questionnaire — changes apply only to this study.”

Sequencing Run Fields

/admin/sequencing-run-form-builder, headed Sequencing Run Fields. This is the internal questionnaire stored on each run-sample assignment — the row that links one sample to one barcode on one physical sequencing run. Its fields appear in the run plan table and in that table’s Excel import and export, and nowhere else.

Unlike the other two builders it has no tabs and no autosave: edit fields inline, then press Save. Add Field appends a new one; the trash icon removes it. Each row shows the field’s storage name under its label, and badges for Internal (admin-only) and Hidden.

The shipped defaults are an Oxford Nanopore wet-lab set: Barcode, Depletion (host depletion / no depletion / other), Extraction Date, Extraction Method, Analyte (DNA/RNA), Concentration (ng/uL), Post-PCR Concentration (ng/uL), Total Volume (uL), and Run-Specific Notes.

There is also an API-only action that installs the fuller ONT metagenomics/metatranscriptomics preset across both the order form and the run questionnaire, adding only the fields that are missing:

curl -X POST https://your-seqdesk.example.org/api/admin/sequencing-run-form-config/preset \
  -H "Cookie: <facility-admin session>"

It answers with how many order fields and run-assignment fields were added.

Import, export and reset

Each builder’s Import / Export tab is how you move a form between instances and how you recover from a bad edit.

Applying a form at install time

Exported files can be applied by the installer:

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

For fully unattended deployments the same definitions can be embedded in settings.json under forms.order and forms.study, using the same groups and fields structure that Export Configuration produces:

{
  "forms": {
    "order": {
      "groups": [
        { "id": "group_sequencing", "name": "Sequencing Information", "order": 1 }
      ],
      "fields": [
        {
          "id": "field_run_type",
          "type": "select",
          "label": "Run Type",
          "name": "run_type",
          "groupId": "group_sequencing",
          "order": 10
        }
      ]
    },
    "study": {
      "groups": [
        { "id": "group_study_info", "name": "Study Information", "order": 0 }
      ],
      "fields": [
        {
          "id": "field_study_title",
          "type": "text",
          "label": "Study Title",
          "name": "study_title",
          "groupId": "group_study_info",
          "order": 1
        }
      ]
    }
  }
}

Worked example: a barcoded ONT intake form

Troubleshooting

See also

• Sequencing Orders & Samples — the wizard these settings build
• Studies — the study questionnaire and MIxS checklists
• Sequencing Technologies — what backs the sequencing-tech and barcode field types
• Modules — which module owns which field type, and why enabling one does not place the field