Your First Form

By the end of this page you'll have a public URL that anyone can submit, and every submission will create a job in your FSM and end up as a first-class entity record. Six steps.

1. Create the entity kind

Jobs need an entity record to carry their payload. From the admin shell, open Entities:

1. Type intake in the "Entity kind" box.
2. Click Load. The list is empty — that's fine.
3. Use the Create record form to add one seed record: { "name": "sample", "notes": "from Installation walkthrough" }.
4. Save.

You now have one record of kind intake. The Fleet-of-Files architecture stores it in your tenant's own SQLite file, not a shared table.

2. Design the FSM

Open Workflows → New workflow. The FSM Designer opens as a React Flow canvas.

1. Add two states: received (initial) and processed. Click Set initial on the received node.
2. Drag a transition from received to processed. In the side panel, set event_type = mark_processed. No guard needed for the first run.
3. Still on the transition's side panel, click Add action and pick PROMOTE_FORM_TO_ENTITY. Fill the payload template with { "entity_name": "intake" } — when the operator fires this transition, the submission attached to the job will be copied into an intake entity record.
4. Name the workflow Intake Flow and bind it to the intake entity (sidebar "Entity name" field) so entity annotations can light up the guard composer later.
5. Save.

You can publish additional versions later; the saved schema is automatically marked is_active.

3. Build the form

Open Forms → New form:

1. Name it Intake, slug intake.
2. Drag in two text fields: name and notes. Mark name as required.
3. Save. Click Publish once you're happy.

4. Wire the form to the FSM

Open the form's detail view, find the Submit actions panel, and pick your Intake Flow schema from the Spawn job in schema dropdown. Save.

Every accepted submission will now spawn a fresh Intake Flow job in its initial_state with the submission linked to the new job (processing_state = 'attached'). Submissions made before the binding was set stay pending for manual triage.

5. Mint an invite token

From the form's detail page:

1. Click Create invite.
2. Pick an expiry (default 7 days) and an optional submission cap.
3. Copy the URL — it looks like /f/<token>.

Open the link in an incognito window. Fill the form. Submit. Head back to /admin/jobs and you'll see a new Intake Flow job in received.

6. Fire the transition and land an entity record

Click the new job on /admin/jobs, then click Mark processed. Three things happen in one atomic step:

1. The job advances from received to processed.
2. The PROMOTE_FORM_TO_ENTITY action copies the submission's payload into a new intake record on entity_records.
3. The submission's processing_state flips from attached to promoted and its entity_record_id points at the new record.

Open Entities, type intake, and click Load — the submitter's values (name, notes) show up as a fresh row. Discarded submissions don't land here; every entity record you see came from a transition an operator explicitly fired, and the append-only event_log carries the full audit trail.

What's next

• Forms Builder — multi-page forms, routing, attachments, custom themes.
• FSM Designer — guards, actions, action payload templates.
• Entities — annotations, the Page Designer, and entity-scoped pages.

Next

For the full guided arc — multi-page forms, PDF templates, signatures, branching, custom CSS — see the Forms tutorials.