Form System Architecture

FormService.createFormController() is the factory that creates the appropriate controller based on ProcessDefinition.type:

The walk shown under RUNNING is the saved-answer walk: it positions the form after person selection, on a resume of an instance with no current step, and at completion, where it must pass every step before onDone() runs. A submit does not run it — it validates and saves the current step and moves one step forward, as described under Validation Flow.

When the front-end submits an answer via POST /api/forms/next:

The same walk positions the form on INIT, and on a resume of an instance that has no current step yet.

One request serves several steps on the same FormPerson objects: the step just submitted, the step moved to, and — at completion — every step in the walk. Before a step renders (moveToField(), loadCurrentStep()) and before each step validates a person’s saved data in the walk, the engine clears that person’s view — options, answer and message — so that every step starts from what it would see if it were the only step (FormPerson.clearStepView()). Selection, removal and skip state are not cleared: they are the person’s standing on the process, not a step’s rendering.

A FormField must therefore:

Why this is a rule and not a convention: in 2.4.29 the category and race-type steps began loading their options during the completion walk, and the membership step — which only loaded its options when the list was absent — found category ids, never PROCEED, and rejected every rider’s saved answer. Riders were sent back to the membership step with no message, answered it, submitted indemnity, and were sent back again; for three days no entry for the live event completed. The licence step had had the same defect fixed a week earlier, without the lesson reaching its sibling.

The flow matrix RegistrationFlowMatrixIT drives an event registration through FormService, one request per step as the portal does, for every combination of step order, CSA checks required, CSA standing and navigation (straight through, back and forward again, leave and resume). Each flow must end in one of three states: the registration completes; the person is told why it cannot; or the person who cannot be verified is removed and the rest complete. A step rendered twice in a row is a failure.

When adding a FormField type, changing what a step validates, or adding a controller:

Subclasses can override these hooks to add domain-specific behaviour:

FormField types are registered in the formFieldCandidates map during construction:

Only a non-terminal instance is resumable:

When no resumable instance exists a new ProcessInstance is created. A terminal instance is never reused — and in particular, a completed registration whose order is still unpaid is not a reason to reuse it.

That distinction matters because onDone() has already fired on a DONE instance: the EventParticipant or membership records and the order all exist. Reusing it cannot enrol anyone new, because next() refuses to advance a terminal instance and resume() rejects one outright. Handing a terminal instance to a screen that is about to start a registration therefore strands the user rather than registering them.

An unpaid order left behind by a completed registration is surfaced independently of process state:

Keeping payment recovery separate from process selection is what allows a user holding one unpaid registration to still start a second registration for another person.

Inherits all base types plus: MFM, MFA, MFC, MCS, MCM

A membership type may name a cross-sell membership type (membership_type.cross_sell_membership_type_id) — at HNR, the "Early Riser" membership offered alongside the annual one. The form offers it to each adult or senior in the transaction. On completion, every selected person is enrolled in the cross-sell type’s latest period, with a line item on the same order.

The process designer chooses how many people may take it by choosing the step code:

Both codes store their answers the same way: one ProcessData row per eligible person, data key MCS, value 1 (selected) or 0. Completion reads those rows without knowing which code produced them, so moving a definition from single to multiple selection is a change to process_step.type alone — no data migration and no front-end change, because the BCB checkbox already renders per person.

TXM — RememberedTextFormField, a subclass of FreeTextFormField. It sends UI code TXT, so the front-end renders an ordinary text box and needs no change. Validation is exactly that of TXT: value_min, value_max and value_pattern.

TXT itself is unchanged: it reads person_data_key verbatim to prefill and never writes back. Choosing TXM is what opts a question into being remembered, because not every free-text question should outlive its registration (for example "Anything the organiser should know?").

The answer is stored in WordPress user meta (wp_usermeta) on the person being registered, under:

Example: HNR (organisation 8) asks "Medical aid number" → slug medical-aid-number → key 8-medical-aid-number.

Consequences:

Prefill, in order of precedence:

The value is written in saveFormData(), on each successful submission of the step, to the person answered for — not to the principal who is filling in the form — only when the principal has READ_WRITE access to that person’s data (including implicit access to their own data). For a READ link, answers may be saved in this process instance’s ProcessData, but user meta must not be inserted, updated or deleted, regardless of sensitive. A registration abandoned after an authorised write has still updated the remembered value; that is accepted.

A blank answer to an optional TXM question deletes the meta row, so a person can clear a value that no longer applies. For text fields, null and the empty string are the same answer: neither is ever stored as a meta value, and a missing meta row prefills as empty.

process_step.sensitive (boolean, not null, default false) marks a question whose answer is sensitive, such as medical information.

In this release the flag is stored and exposed only. One rule applies now: the answer of a sensitive step is never written to a log, at any level.

Planned behaviour: when the principal’s link to a person has access_level READ — a coach or teacher linked to a minor, for example — sensitive questions are skipped for that person: not shown, not prefilled and not overwritten.

Remembered answers are stored in plain text in wp_usermeta. Encryption at rest is outside this design. Configure TXM and sensitive with that in mind.

Inherits all base types plus: ECA, ERT

The event steps depend on one another, and the dependency is carried by ProcessStep.seq:

In short: <any> › [ECA, ERT] › (CSI › CSM › [CSL]) › <any> › ITC.

Nothing enforces this yet. A definition saved in another order — CSL before CSM, or ERT after the CSA block — runs, and its steps give wrong or empty answers. Planned: a definition is validated against the rule when it is saved through ProcessDefinitionResource and ProcessStepResource (on the resulting set of steps, since steps are saved one at a time), and FormService refuses to start a registration on a definition that breaks it, with a message that names the rule. Whether CSI must be present whenever CSM is remains open: the code falls back to the person’s identity number when there is no CSI step, which serves a South African rider and nobody else.

During development of new form questions (Epic #34), front-end developers need to integrate with specific FormField types. Creating a full ProcessDefinition for each field type under development creates a dependency bottleneck. The TestFormController eliminates this by allowing any FormField type to be tested via a single API call.