Forms and EDC exports

Forms

For Viedoc imports, select the Viedoc design export profile. Generic ODM identifiers are not Viedoc expression identifiers; the Viedoc profile projects stable, target-safe identifiers and their references together. Do not rename individual identifiers in an exported file.

ODM text fields carry maximum character counts through ItemDef.Length, not numeric range checks. Positive minimum text lengths and pattern rules are reported as export findings for target-system review. Numeric ranges retain their authored error messages. Historical Forms with language English export their question and choice text using en.

A Form is an organization-owned, reusable data-collection definition. Each saved change creates an immutable Form version containing ordered sections, fields, answer choices, validation rules, conditional display, provenance, and optional standards mappings. Stable codes and node IDs preserve identity when labels change.

Form language is stored and accepted by the API as an ISO 639-1 code, such as en or da; the editor displays the corresponding language name. AI/import input and historical database reads use the shared language codec to map recognized names to codes. Unrecognized language values are rejected without an English fallback. Reading an older version does not rewrite its immutable source record.

The Form tab keeps routine authoring deliberately small:

• name, description, and language;
• sections with a name, description, and repeatable setting;
• fields with a label, description, field type, and required setting;
• answer choices, numeric limits, text length and pattern checks, and conditional display only when the selected field type needs them;
• a Contains identifying data setting when an answer can identify a participant.

Open a field’s Edit action to use separate Details, Conditions, Validation, and Standards settings. Duplicate item copies the clinical configuration while assigning fresh governed identity to the new field, choices, validation rules, and conditions. Standards references remain unset on a duplicated field.

The description explains the reusable Form’s purpose for discovery and review. Completion instructions are a separate canonical property because imported Forms and some export targets can provide global guidance to data-entry users, but TrialStack does not show that property in routine authoring. Activity-specific guidance belongs to the placement. A future expert workflow can expose exceptional global instructions without conflating them with the Form description.

TrialStack generates and preserves the technical codes used by connections and exports. Form release labels, Form type, global completion instructions, source provenance, organization ownership, and standards release details remain governed metadata rather than routine free-text authoring. Trial-level population belongs to trial configuration and placement context, not to the reusable Form. Licensing review is conditional for imported, external, copyrighted, COA, or PRO content; manually authored internal Forms default to not applicable.

AI-generated Forms and activity connections remain drafts for human review. Generation does not approve their clinical content.

Generate, import, improve, and verify

The authoritative Forms Action binding uses the complete Form contract. Generate and Import can return metadata, sections, fields, answer choices, validation, conditional display, repetition, optional standards mappings, findings, and source lineage. TrialStack assigns immutable Form and node identity after validating the proposal; the model does not control governed UUIDs, version numbers, or ordering metadata.

Generated new Forms receive a system-assigned code, so generating another Form with the same name does not claim an existing Form or starter-catalog code. Reuse an existing Form through Connect; update it through its own governed editing flow. Imported codes remain unchanged and conflicting codes are reported.

Generated conditional-display rules are checked against the complete Form tree before the output is accepted. References must resolve to one earlier field. Unknown or ambiguous references are returned for one correction attempt; invalid output is not saved. A failed save retains its generated output and reports the specific persistence error. Retrying an interrupted creation can recover the initial Form version saved by that same run without overwriting another Form.

Generating Forms for selected trial assessments saves reusable draft Forms and connects their exact saved versions to the selected scheduled activities. The connections also remain drafts. If an activity was removed, moved to another visit, or assigned to another assessment while generation was running, the run fails instead of linking to that changed activity. Existing connections retain their pinned versions when generation is retried.

Schedule acquisition plans remain review handoffs: proposed matches and new Form drafts must be reviewed before they are applied.

Structured REDCap, EDC dictionary, JSON, CSV, and XML imports use the same review path. Supported sections, variable codes, choices, validation, and conditional display are retained. Unsupported calculated or scored fields, cross-Form rules, vendor JavaScript, runtime roles, and direct deployment are findings rather than silently invented TrialStack behavior.

Improve starts from the current governed Form and preserves manual content and stable identity. Verify checks tree integrity, field and control compatibility, ranges, choices, conditional-display references, licensing state, and optional CDASH mappings. Verification never changes the Form. Schedule-triggered acquisition loads complete current Form and placement collections before planning; a failed load stops generation. If the schedule changes during acquisition, the returned plan remains stale and must be regenerated before its draft or placement actions can proceed.

Conditional display

In an item’s Conditional display tab, conditions appear as table rows. Select Add condition or open a row to edit its earlier item, comparison, and answer. Apply updates the item draft; Cancel discards modal edits. Save the item and then the form to persist changes. The All/Any selector applies to the complete set of conditions. Blank checks do not require an answer value.

Fixed values and field visibility

Field Details includes Read-only answer, Hidden field, and Fixed value settings. A fixed value must match the field’s data type and any answer list; it is always read-only. These settings describe the intended collection behavior. They do not create participant data or execute a collection system.

The immutable Form version retains these settings through editing, history, cloning and restore. Existing Forms without these settings remain visible and editable with no fixed value. The preview shows fixed values and omits hidden fields.

ODM retains the settings as a TrialStack Form Value Definition 1.0 alias and reports that receiving-system implementation is required. REDCap retains the canonical sidecar and reports an error because the native dictionary does not project this behavior. Retained metadata is not evidence of validated external execution.

Measurement units

Numeric items offer a searchable Unit selector in Details using a pinned subset of UCUM 2.2 expressions with readable names. Saved custom units, labels, and release pins remain unchanged when the editor opens. An explicit selection changes the item draft; saving the item and then the form persists it. Choosing the current catalog entry explicitly replaces an older release of the same unit code. Leaving the saved selection unchanged preserves its release. Changing units does not convert numeric limits or answer values.

The subset is bound to the retained UCUM 2.2 source and is not a complete terminology release or a check that a unit fits the measurement. The server resolves new selections to exact references. Unchanged historical references keep their saved source, including an absent release. Existing imported units remain visible even when outside the subset. Arbitrary expressions and automatic numeric conversion are not supported.

New form-aware ODM exports retain the unit code, label, code system, and release as item aliases. ODM 1.3.1 and 1.3.2 also emit native measurement-unit definitions and references with distinct identities derived from the complete code system, release, and unit code. ODM 2.0 does not support the legacy MeasurementUnit element; aliases preserve the metadata, but its native sibling UnitsItemOID model is not yet projected. REDCap retains the same metadata in the checksummed data-collection.json file; that file is not a native REDCap import file. Retained exports are unchanged.

CDASH and controlled terminology

CDASH is useful when a field should have a standard collection meaning and downstream traceability to SDTM. It is not required to design a Form or to generate ODM, Viedoc, or REDCap metadata.

Select CDASHIG version beside Language to choose the Form’s immutable standard profile. New empty Forms have no profile. The seeded profile pins CDASH Model 1.3, CDASHIG 2.3, and CDASH and SDTM terminology dated 2026-03-27. The terminology date belongs to that profile; it is not inferred from the IG version.

Each field retains only its CDASH domain and variable. Original source evidence is retained separately, and existing answer bindings keep their exact term identities. The server resolves codelists against the selected releases. Missing releases, unknown variables, datatype conflicts, ambiguous codelists, invalid answer bindings, and LOINC failures produce concrete findings.

There is no separate mapping status or confirmation step. Form calculations and edit checks likewise have no mapping-review status; their definitions, source limits and external execution remain unchanged. Save with the existing change description to record a new version. Document approvals and other entity workflows are unchanged.

The API retains verifiedItemCount for compatibility. It counts complete CDASH references that pass the implemented technical checks, including checks on their answer bindings and LOINC references. It is not a clinical approval. An unscoped finding prevents a reliable count and produces zero.

Old snapshots remain immutable. Uniform legacy release references can be projected to the corresponding profile; mixed or unknown releases remain unresolved rather than being silently replaced. Copying sections between different profiles is rejected. Clone and restore retain the source standard basis. Changing the profile creates a new Form version; run verification against that version to obtain current findings.

New workspaces start without Forms. Workspace onboarding does not provision the Form seed catalog, and legacy Form continuation requests finish without creating more Forms. Existing workspace Forms remain unchanged.

The seed generator retains source identities, wording, values and rules. The separate operator seed command creates missing Forms and leaves existing tenant Forms untouched. Updating existing seeded Forms is a separate versioned operation with a conflict report and readback. Catalog availability is checked independently: a seed profile does not mean its catalog has been ingested.

Reusing sections

In the sections action menu, Reuse sections opens a picker for existing internal or public-domain forms in the same language and with the same CDASH profile. Select a source form and the sections to copy. Earlier sections required by the selected conditions are included and identified before adding. Forms requiring licensing review or carrying a licensed-content designation are excluded from this initial section-reuse flow.

Adding sections changes only the current draft. Save the form through its normal governed save flow to persist the copy. Source forms and existing trial placements remain unchanged. Each copy receives fresh node identities and collision-free codes. Conditions point to the copied items. Units, answer terminology, validation, and explicit standards references are retained without selecting new mappings.

Each reused section carries the exact source form version, source section, and item identity correspondence in its canonical metadata. The API resolves new attribution within the current organization before saving. Attribution describes the origin of the copy; it does not certify that later edits preserve clinical meaning or confer the source form’s approval. Existing exports retain their original artifacts; new canonical collection sidecars include the added metadata.

Editing a question or reference is recorded through the existing save description and version history. There is no separate mapping acknowledgement. Verification and exports retain concrete catalog and capability findings; historical saved verification results change only after a new verification.

LOINC observation mappings

In Standards, select Add mapping, then choose LOINC to search the retained LOINC 2.83 catalog by name or code. Review the component, property, timing, specimen or system, scale, and optional method before selecting Apply. This changes only the item draft. Save the item, then save the form to persist it. Cancel discards the draft. Local item codes and answer values remain unchanged.

Only active terms from the exact reviewed release are offered for new mappings. Existing references remain readable when the catalog is unavailable; they are never silently refreshed. AI regeneration preserves mappings on retained item identities and cannot invent catalog references. Duplicating an item clears its observation mapping. A matching label is not evidence of clinical equivalence.

Verify checks the retained term identity, all observation parts, source status, release checksum, archive checksum, and source attribution. Missing releases, changed metadata, and non-active terms produce findings. These checks establish source integrity, not clinical approval or target-system conformance.

ODM 1.3.1/1.3.2, ODM 2.0, and the Viedoc projection retain LOINC metadata as item aliases. REDCap retains it in the checksummed canonical sidecar, not as a native dictionary column. These are metadata handoffs, not automatic coding or transformation instructions. No participant data or SDTM mappings are inferred.

Importing the reviewed catalog locally

Apply the additive 20260905093000_loinc_catalog migration before importing. The operator command defaults to inspection and only permits writes to local Neon Docker on port 5434:

corepack pnpm --filter @trialstack/api exec tsx scripts/import-loinc-catalog.ts /absolute/path/Loinc_2.83.zip
corepack pnpm --filter @trialstack/api exec tsx scripts/import-loinc-catalog.ts /absolute/path/Loinc_2.83.zip --apply

The importer verifies the archive, main table, and license against PINNED_LOINC_RELEASE, then imports the complete normalized LoincTable/Loinc.csv transactionally. All source columns are retained. Release 2.83 contains 112,405 terms: 99,737 active, 5,436 trial, 5,008 deprecated, and 2,224 discouraged. Re-importing the same release is idempotent; conflicting checksums are rejected. Accessory answer lists, crosswalks, and other ZIP contents are not exposed as lookup catalogs by this phase.

The archive SHA-256 is 077a0718e87d8309ffe3a673f75b836a8e783dc36a646413ef97c71c12eab27e. The complete normalized table plus license checksum hashes to 9be98af319c0e725d325fd474e5ece85fc30d133e9b22e0204809edb05d3db68. Raw source rows and archives must not be committed as fixtures. Retain source notices in mappings and exports. Remote catalog ingestion and deployment require a separate operator workflow; local import does not make a production catalog available.

Trial Plan placement

From Forms, select Generate, choose a trial, then choose one or more activities. Each activity shows its connected visits and related forms. Activities with complete coverage cannot be selected. Generation prepares one review for the selection and includes only visits without form placements.

Build > Forms lists the trial’s active and archived form placements. Each row shows the form version, activity, visit, order, requirement, history, and audit actions. Generate uses the current trial. Connect asks for an activity, a matching visit, and a form. The Forms field is unavailable when no forms exist. Removing a row removes the placement without archiving the form.

Open a scheduled activity on the trial Activities page and use its Forms section to connect and configure one or more Forms. A placement pins one exact Form version and records order, requiredness, included items, repetition, and notes. Reusing a Form never copies it into the trial. A newer Form version remains opt-in: review the difference and upgrade one or several placements with a rationale.

After the governed schedule is saved, Generate All can also prepare a Form-acquisition review queue. TrialStack groups repeated occurrences of the same reusable activity, compares them with available current Form versions, and returns one of six review outcomes: reuse an existing Form, generate a new draft, no Form required, insufficient evidence, ambiguous match, or licensing review required. A missing reusable Form is generated once and referenced by every proposed activity placement.

The queue never creates or connects records automatically. Existing matches open the standard placement drawer. New drafts open the governed Form review/create surface and can be connected only after the reviewer saves the Form. Reviewers can skip, reject, or defer each proposal. Changes to the referenced schedule or scheduled activity make the proposal stale and require regeneration.

The Form Activities tab at /forms/:formId/activities uses the same governed relationship workspace as other TrialStack connections. It lists active or archived placements with search, sorting, history, restore, and audit actions. Each card identifies the scheduled activity and shows its trial, visit, pinned Form version, order, and requiredness.

Connecting from the Form Activities tab is intentionally more technical than connecting a simple reusable entity. Select the trial first, then the visit, then the scheduled activity. Each selection constrains the next field to valid governed records. The connection modal also captures order, requiredness, optional repetition, and activity-specific notes. Editing a placement keeps its trial, visit, activity, and pinned Form version fixed; moving a Form to another activity requires a new governed placement.

Export choices

• Generic ODM emits Form, item-group, item, codelist, unit, supported range-check, and complete reference metadata.
• Viedoc workflow scaffold remains workflow-only and does not include Forms.
• Viedoc design adds governed scheduled activities and placed Forms to ODM 1.3.1 + SDM-XML 1.0. Authored visit placements are preserved: AE and concomitant-medication names or codes never move Forms into Common Events automatically.
• REDCap emits a deterministic ZIP with the data dictionary, event-instrument map, repeating-instrument settings, manifest, findings, lineage, checksums, and limitations. A standalone Form can also be exported as CSV.

The target-neutral acquisition package can retain governed cross-Form edit-check semantics, calculations, role intent, and source mappings even when a named adapter cannot project them. Data responsibilities are authored on the governed contact assignment for the trial—not as a second acquisition record—and are projected into target-neutral role intent for export. External field codes and transformations are configured on the governed Trial–Computerized System connection. The connected system category determines whether that mapping represents EDC, eCOA/ePRO, IRT/RTSM, LIMS, eSource/EHR, imaging, or digital-health acquisition; users do not choose the same source type again for every field. Older Trial Design source mappings remain readable and are merged for compatibility, while connection-owned mappings take precedence when they share an identity. Viedoc and REDCap exports report every unsupported or lossy rule, calculation, permission intent, mapping, vendor function, alert, operational RTSM behavior, subject-data behavior, or deployment operation as a limitation instead of inventing an equivalent.

The same immutable acquisition package is the source for an SDTM participant-domain mapping specification. TrialStack pins the exact Form and placement versions, typed conditions, terminology releases, governed concept references, and computerized-system relationship versions used to compile it. Reviewers accept, reject, or override individual domain, variable, source, unit, terminology, and record-selection rows with retained rationale. Refreshing sources creates a new specification version; unchanged reviewed identities are preserved and changed or removed sources return as proposed rows or findings.

Designer capability coverage

“Covered” means that a capability is either represented portably, projected deterministically, or named in the export findings as unsupported or lossy. It does not mean TrialStack reproduces every vendor runtime setting in the Form editor.

Designer capability	TrialStack handling	Viedoc design	REDCap package
Reusable Forms/instruments, stable identity, immutable versions, sections/item groups, ordering, and cloning	Canonical and governed	Projected	Projected
Text, paragraph, integer, decimal, date, date-time, time, radio, dropdown, checkbox, yes/no, and display-only fields	Canonical field types	Projected through ODM where representable	Projected through the Data Dictionary
Labels, descriptions/help, requiredness, identifiers, choices, units, numeric limits, text length/pattern rules, and same-Form conditional display	Canonical	Supported ODM constraints are projected; typed same-Form visibility is compiled for supported field values and group scopes; unsupported conditions produce blocking findings	Supported REDCap columns are projected; omitted validation rules produce findings
Repeating sections/item groups	Canonical	Projected where supported by ODM/Viedoc	Not equivalent to REDCap instrument repetition; reported when omitted
Form placement in visits/activities, order, requiredness, selected fields, and repeatable Form instances	Canonical pinned placement	Projected to activities and event Form references	Projected to event-instrument and repeating-instrument files; duplicate activity placement is collapsed with a finding
Viedoc form summaries, hidden/copy behavior, auto-update, translated preview, annotated CRF, role visibility/edit rights, output-ID overrides, and automatic event-date behavior	Vendor runtime metadata	Not included; named findings	Not applicable
Viedoc VAS/NRS, Range, file/DICOM upload, drawing pad, form link, JavaScript functions/defaults, custom checks, alerts, SDV, signing, and review workflows	Vendor-specific or outside the current canonical field model	Not included; named findings	Not applicable
REDCap matrix/ranking, slider, signature, file upload, embedded media, action tags, smart variables, piping, field embedding, and Form Display Logic	Vendor-specific or outside the current canonical field model	Not applicable	Not included; named findings
REDCap surveys, invitations, queues, consent/acknowledgements, user rights, data access groups, locking, queries, alerts, scheduling, external modules, API deployment, and mobile runtime	Operational runtime configuration	Not applicable	Not included; named findings
Calculations/scoring, cross-Form/cross-event logic, randomization/allocation, kits/RTSM, subject data, and direct deployment	Governed intent may be retained in the acquisition package; operational execution remains outside the Form designer	Not included; named findings	Not included; named findings

This boundary follows the current Viedoc Form Designer documentation, Viedoc workflow documentation, Viedoc outputs and validation documentation, the REDCap software capability overview, the REDCap instrument-library coding guidance, and the University of Helsinki REDCap guide. Re-audit the matrix when a pinned vendor profile or canonical Form capability changes.

Generated schedule values

Generated visit numbers are retained for range-only visits. Visit duration is an encounter duration in minutes; scheduled visit windows are relative days before and after the target; range-only bounds are absolute days relative to the trial anchor. Timeline values and relative windows require explicit duration units. Ambiguous historical timing strings remain available for review rather than being silently converted to days. Unsupported encounter-duration units block generated persistence with a concrete explanation.

Review packages and export failures

REDCap trial exports are review packages. Forms without exportable fields are omitted together with their event mappings and repeating-instrument rows. The findings report, manifest, and projection omission evidence identify each omitted Form version and affected placement version; the full source lineage remains retained. Unknown references, conflicting instrument or event identities, and packages with no exportable instruments still fail.

The export details show review status and findings. Completed means the package was produced, not that REDCap or Viedoc import or operational validation succeeded. Concrete validation failures remain visible and are not retried automatically. Transient execution failures may retry; unexpected technical failures show a generic message with a traceable export request.

SDTM Trial Design exports retain the server-captured design snapshot through generation and the manifest. A historical failed request without a snapshot requires a new export request. Historical artifacts are not rewritten.

Compatibility boundary

TrialStack validates XML against pinned XSD graphs and validates REDCap package structure and references deterministically. This is static compatibility evidence, not a claim of live vendor compatibility. A separately authorized vendor import and semantic round trip is required before making that claim.

Source-defined rules

Imported Forms can retain calculations, conditional requirements, consistency checks and fixed or field-driven repeat counts as governed metadata. These rules belong to the immutable Form version and can be reviewed through the existing Form editor. TrialStack does not run these rules against participant records. Source expressions are retained as historical evidence, never executable vendor code. Historical limitations remain visible alongside the specification.

Calculations distinguish intermediate results from the final field value. Cross-form catalog references pin the destination Form version when the catalog is provisioned for an organization. Copying rule-bearing sections also copies prerequisite fields and rebinds internal references.

ODM exports retain these specifications in named aliases and report that external execution is required. REDCap exports report unsupported native projections explicitly; canonical metadata retains the complete specification. Exporting a specification does not validate its operation in a receiving system.

Importing pinned CDISC workbooks

Organization administrators can import licensed, registry-pinned CDISC workbooks through Catalyst using POST /api/terminology/releases/import-workbook-json. Supply the original filename, its SHA-256 as sourceArtifactChecksum, and the complete file as canonical contentBase64. This transport accepts up to 512 KiB of decoded data so the complete request remains available in the approval preview. The existing multipart import remains available separately and is not exposed through Catalyst.

Catalyst requires a prepared preview and explicit approval before execution. The importer checks the submitted checksum, resolves the exact artifact against the immutable standards registry, and retains a checksum of the complete normalized release. Repeated imports use the existing immutable release identity. Importing a catalog does not approve clinical mappings or update historical verification results; review mappings and run verification again afterward.

CDASH Model rows without a domain code retain their complete source class label as the catalog grouping value. These labels are preserved without truncation; they are not asserted to be domain codes.

Catalog choices in Form mappings

CDASH Domain and Variable choices use the exact CDASHIG release selected on the Form. The Domain choice narrows the Variable list. Changing Domain clears the pending Variable choice; it does not assign a replacement. More than one catalog definition for the same Domain and Variable is treated as ambiguous and is unavailable for new selection.

If the release is absent, the editor displays that missing release and retains existing references. It does not substitute a newer release. Loading failures can be retried.

LOINC searches use the pinned LOINC release. Missing-release and lookup failures retain the search text so the error remains visible and the search can be retried. A valid code alone does not establish that specimen, timing, method, or the intended observation matches the Form item.

These controls do not import catalogs. In particular, the presence of a local LOINC archive or importer does not mean that a production catalog contains that release.

Import-readiness findings

An empty authored Form produces ODM_FORM_CONTENT_EMPTY; a license awaiting review produces ODM_FORM_LICENSE_REVIEW_REQUIRED. Historical range rules without numeric bounds or carrying a pattern produce ODM_FORM_VALIDATION_INVALID. Historical values remain readable for repair; new authored and generated range rules require numeric bounds and cannot also carry a pattern.

The Viedoc design adapter compiles typed same-Form conditions into Context="js" with explicit v4:HideShow="show". It resolves final target IDs, preserves missing-value semantics, and projects explicit boolean 0/1 or true/false choices as integer controls. It rejects unresolved references, cross-Form references, reads from another repeating group, and unsupported value representations with VIEDOC_ITEM_VISIBILITY_NOT_PROJECTED. Portable ODM retains its original conditions. The Viedoc visibility attribute is a bounded vendor extension, not a change to authored canonical semantics. An exported file is not evidence that conditional visibility works; an authorized target import and behavioral verification remain required. Viedoc documents native condition encoding in its Design ODM file structure.