Tutorial: Define data forms

Form schemas describe dynamic forms (layout, fields, validation hints, translations) consumed by the runtime renderer, workflow steps, and public-site experiences. This tutorial matches the Forms admin at /home/yourteam/admin/forms.

1. Screen layout

Actions: New, Clone, Delete (with confirm).

2. Versioning model (same idea as data entities)

The database enforces uniqueness on (account_id, name, version) for form schemas.

• Each row is one named + versioned definition.
• Bump the Version string (1.0 → 2.0) and save as a new row (via New or Clone) when you need an immutable snapshot for new workflow definitions while keeping old instances on 1.0.
• Edit in place (same id) updates that snapshot only—use when fixes are safe for all consumers.

Workflow steps store a form_schema_id. Operative runs therefore pin to the exact saved row they were configured with.

3. Create a form (New)

1. Click New.
2. Set Name (stable key-like label, e.g. Expense Request).
3. Set Version (e.g. 1.0).
4. Optionally set Description.
5. Public — For typical team-owned forms, leave unchecked. The insert path for members always ties the row to your account; Public on a team row affects how other policies treat visibility—use only when your administrator documents a cross-tenant sharing pattern.
6. Auto-create linked data entity if missing — When checked, on Save the server can infer a companion data entity ({name}-entity with matching version), link it via linked_data_entity_id, and record provenance (generated_from_form_schema_id on the entity side). Use this when you want the entity catalog to stay aligned with the form without hand-authoring JSON twice.
7. Provide Schema JSON (see structure below).
8. Click Save.

4. Schema JSON structure (what the renderer expects)

Your JSON should follow the playground / schema form contract used elsewhere in the app, including:

• schemaType / schemaVersion — Metadata for the document.
• form — id, title, layout, steps (each with sections and fields using component types such as Input, Textarea, Select, …), and actions (e.g. submit).
• dataSchema — Field-level types and required flags aligned with form fields.
• translations — Nested map of locale → label overrides (the preview language dropdown exercises these keys).

Invalid JSON blocks Save and shows Invalid schema JSON in preview.

5. Preview & Capture (no server persistence)

The Preview & Capture card renders SchemaFormRenderer in preview-only mode:

• Choose Preview language to validate translations and RTL layout (Arabic).
• onSubmitServer is undefined here—submissions in this panel are not written to your database; they are for UX validation only.

When the same schema runs inside Workflow operative or public lead intake, submission paths persist through the respective server actions.

6. AI assistance

Enter a short natural-language prompt and click Request AI assistance. The server returns JSON to paste into Schema JSON (in many dev setups this is a deterministic mock unless AI_USE_MOCK is disabled and an external generator is configured). Always review AI output before Save.

7. Clone and delete

• Clone copies metadata and JSON, suggests name-copy, and saves a new row.
• Delete removes the row—ensure no workflow step still references that form_schema_id.

The sidebar shows id: {uuid} and, when present, entity: {uuid} for linked_data_entity_id—use these when coordinating with Workflow admin.

8. Security, roles, and permissions (where they apply)

The Forms admin does not expose per-field ACLs. Security is layered:

8.1 Who can edit form definitions

• Account members with access to /home/yourteam/admin/forms can create / update / delete schemas for that account (RLS on form_schemas).
• Super admins maintain global templates where applicable.

8.2 Who can fill in a form inside a workflow

When a form is attached to a workflow step, Workflow admin → Steps defines workflow_step_permissions per step:

• role_type: system (built-in roles like owner, member, workflow_admin) or account (your team’s custom roles).
• can_view — May see the step and its form.
• can_capture — May submit / complete the step’s capture.

So the same form schema can be visible to everyone on step A but restricted on step B by changing permissions, not by duplicating the schema.

8.3 Public site lead forms

Anonymous visitors post to a public API; the platform validates host, form key, honeypot, and throttle rules. Configuring which fields exist and syncing internal schemas requires public_site.manage (or owner). Reviewing leads uses public_site.leads.view (or equivalent). See Customize your public pages.

8.4 Effective takeaway

• Forms admin = definition security (who can edit the schema).
• Workflow step permissions = runtime security for authenticated workflow users.
• Public site policies = runtime security for anonymous intake and staff lead tools.

Checklist

• [ ] Name + Version unique per account; bump version for breaking changes.
• [ ] Schema JSON valid; Preview checked in at least one locale.
• [ ] Auto-create entity decision matches whether you want a linked data_entities row.
• [ ] Workflow steps that use this form have correct can_view / can_capture rows for each role.