Forms That People Actually Fill — Building and Driving Process Forms in Oumma

Most workflow tools give you a form widget and wish you luck. Oumma forms are first-class design objects: built in a visual builder, labeled in three languages, validated at launch and completion, and — because a form *defines a step's input — the thing that drives the engine when a step is completed.*

Series: Oumma · previous: Roles, Groups and Permissions

The three places a form appears

  1. At launch — the initial step's form is the "Create a dossier" form. A process can only be launched with a valid form_id belonging to that process; the launch role (configured in the designer) is the only one who sees the button.
  2. At a human step — the form is the step's input contract. Completing the step = submitting a valid form.
  3. At a system step — the input schema plays the same role: it declares what the step consumes from the process context (and what it produces), even though no human types it.

All three are designed in the same place.

The Forms tab

Forms tab

The tab lists every step that has a form and opens the visual builder:

  • Authorized field types — text, number, date, list/choice, textarea (the platform's controlled set; no arbitrary widgets).
  • Required flags — enforced twice: in the app (the field blocks submission with a translated error) and in the engine (a completion without a required value is rejected).
  • Trilingual labels — each field label carries EN/FR/AR. The workspace language switcher makes the same form read natively in all three, RTL included.
  • Per-step ownership — the form belongs to the step; renaming the step renames the form step with it (the durable rename cascades engine + forms + roles in one pending version).

Two structural rules keep launches sane:

  • All initial steps of a process share the same form structure — a launch must be unambiguous no matter which initial step the engine picks.
  • form_id is mandatory at launch — the engine validates the id against the process's stored forms; you cannot launch with a foreign or stale form.

Building forms with the AI

The designer chat converts plain language (or pasted JSON) into these same field definitions:

Build the launch form for Order Processing: customer name, customer id, items (list), total amount (number, required), payment method (choice: card, transfer, cash).

The agent proposes an update_form_step tool call with the field list; you Apply, and the Forms tab now shows the real form — editable by hand afterwards. This is the loop that makes form design conversational and inspectable: the chat writes it, the builder audits it.

The completion flow is form-driven

When the engine reaches a human step, "complete" is not a button-with-vibes:

  1. The task view renders the step's form (labels resolved through the process's search-items catalog).
  2. Required fields gate the submit button (client), and the engine re-checks the submitted values against the schema (server).
  3. The submitted values land in the process context — the next steps (human or system) read them. This is how the total_amount you typed at launch becomes the value the $1000 manager-rule branch checks at review time.
  4. The whole thing is written to the task history (who submitted what, when), stored in Postgres.

Documents ride along

The Documents tab of a dossier is the attachment surface: files attached to the instance, with role-scoped permissions (read/write/share/delete per role — the same RoleActionChecker that guards task completion). The AI can also analyze an attached document and fold the extracted facts into the process context (article 7).

What this buys you

  • One builder, three languages — the form is the localization unit; labels are data, not code.
  • Validation as a contract — required fields and schemas are enforced at the engine, so no client (human or AI) can cheat the process.
  • Forms drive data flow — submitted values are the process context; decisions and tool inputs consume them downstream.
  • Conversational with an audit trail — the AI builds the form; the builder is the source of truth you can always open.

Next in the series: A Day with Oumma — the Normal User Journey, the same platform from the other side of the desk.

Oumma: Go workflow engine + React agentic workspace. Article 5 of the Oumma series on Dev.to. Source code: the Go engine in AHBench/oumma and the React workspace in AHBench/oumma-app — both Apache-2.0.