Filling in the fields
What this page is — the document workspace, where a draft is actually written: a form generated from the type's field schema on the left, the document it produces on the right.
What it is for — so the person writing an agreement answers questions, and the legal wording assembles itself from the answers.
The problem it solves — authors edit legal wording directly, and every agreement drifts a little further from the approved text.
Route: /org/papers/documents/<document> · Permissions: View this project's documents. to
open; Edit draft documents / data values. to change anything.
1. What it is
Everything on this screen is driven by the document's type. A different type asks different questions and produces different wording; the two halves stay the same.
| Part | Holds |
|---|---|
| Header | Title (editable in place), state badge, family chip, number, validity, retention and legal-hold pills, save indicator, AI buttons, Activity, Help |
| Lifecycle bar | The transitions available from this state, Finalize, Amend, Override |
| Form (left) | The type's fields, grouped into cards |
| Preview (right) | The document as the server renders it from saved content |
| Cards below | Attachments, security tags, parties, suggestions, signature, distribution, versions, activity |
Editing a legal document by hand is how clauses get broken. Here the wording is fixed by the template and only the answers move.
| You change | You never change | |
|---|---|---|
| In the workspace | Field values, title, attachments, parties | Template wording |
| In the Type Designer | Template wording, field definitions | Any one document's values |
2. Why you would use it
- A non-lawyer can produce a correct agreement. They answer "what is the contract value?", and the value lands in clause 7 in the approved phrasing.
- Nothing is lost. Every edit autosaves about a second after you stop typing.
- Every change is attributable. The Activity card shows each edit as a before → after table using the field's real label — Contract value: 25,000 → 40,000, changed by Jane on Tuesday.
- The form adapts. Conditional fields appear only when an earlier answer makes them relevant, so a thirty-field type rarely shows thirty fields.
- Once others are reviewing, it stops moving. Outside the editable states the form turns read-only, so nobody's approval is of a document that changed underneath them.
3. When the form accepts typing
The form is editable only in three states, and only while no sealed artifact exists:
| State | Editable |
|---|---|
draft | Yes |
negotiation | Yes |
returned | Yes |
| Any other state | No — "This document is in state "x" — data is read-only here." |
| Any state, once sealed | No |
The list is fixed in the product, and the server enforces the same three — an edit sent in any other state is refused with document in state "x" is not editable.
If a type's lifecycle calls its starting state working_draft instead of draft, documents in it are
read-only from the moment they are created. Keep the names draft, negotiation and returned for the
states people need to type in.
4. Step by step
- Open the document from the list.
- Work through the field cards. Watch the save indicator: unsaved changes… → saving… → saved.
- Check the preview on the right after each group.
- Rename the document in the header if its title is not yet right — click, type, click away; Title updated confirms.
- Press the lifecycle transition — typically Submit — when the form is complete.
5. Field reference
Controls by datatype
| Datatype | Control | Validation |
|---|---|---|
text | Single-line box | Non-empty when required |
long_text | Large box with a dictation mic | Non-empty when required |
number | Digits only | Numeric |
currency | Digits, merged with the currency into the template | Numeric |
date | Date picker | A picked date — a typed partial date does not count |
select | Dropdown | One of the options defined on the field |
boolean | Checkbox | — |
party | Box | Non-empty when required |
line_items | Editable table with the type's columns; + Row adds, the bin removes | Per column |
Markers on a label
| Marker | Means |
|---|---|
Red * | Required — see below for when this is actually enforced |
auto: customer.name | Merge-mapped: pre-filled from a platform record at creation. Still overridable |
Conditional fields
A field with a visibility condition appears only when the condition holds. Conditions compare another
field with eq, neq, in, not_in, gt, gte, lt, lte, empty or not_empty — for example
Non-solicit period (months) appearing only once Includes non-solicitation? is ticked.
Required fields — when they are enforced
Required fields are checked when the document is submitted, not while you type. A missing one refuses the transition with missing required fields: effective_date, counterparty_name. Hidden conditional fields are not counted.
submit enforces themThe check runs on a transition whose action code is literally submit. On a type whose transitions use any other action code, a document can leave draft — and be finalized and signed — with every required field empty.
If your type's first transition is called anything else, the red asterisks are advisory. Check the action code on the type's Lifecycle tab.
Messages
| Message | Means |
|---|---|
| This type has no fields defined | The document is produced exactly from its template. If the preview is also blank, so is the template |
| document in state "x" is not editable | An edit reached the server outside an editable state (§3) |
| missing required fields: … | Submit refused — the listed field codes are empty |
6. Worked example
An HR partner writes a consultancy agreement for a contractor, Marcus Feld.
The Parties card has Client pre-filled — auto: organisation.name. They type the contractor's
name and address. On Engagement they pick Day rate in the Fee basis select, and a Day rate
currency field appears beneath it; they type 850 and tab away. The preview re-renders with
"EUR 850 per day" in clause 4. The indicator reads saved.
On Terms they tick Includes non-solicitation?; Non-solicit period (months) appears, and they
enter 6. They leave Effective date empty by accident and press Submit:
missing required fields: effective_date. They pick the date and submit again. The document moves to
internal_review, the read-only banner appears, and the form stops accepting typing.
Two days later legal asks who changed the day rate from 800. The Activity card shows the edit: Day rate: 800 → 850, with the partner's name and the time.
7. The admin contract
| Must be true | Where | What breaks without it |
|---|---|---|
| The role holds Edit draft documents / data values. | Role editor | Fields are read-only for that user in every state |
| The type has a field schema | Field schema | This type has no fields defined |
| The template references the field codes the schema defines | Template builder | Values are entered but never appear in the preview |
Editable states use the names draft, negotiation, returned | Lifecycle | Documents are read-only from creation (§3) |
The draft's outgoing transition action is submit | Lifecycle | Required fields are never enforced (§5) |
| Merge sources are mapped | Field schema | auto: fields arrive empty |
8. Downstream
| When a field changes | Then |
|---|---|
| Autosave completes | The preview re-renders from the server |
| The value is a merge target in the template | It appears in the document body |
| The field is a conditional driver | Dependent fields appear or disappear |
| AI results exist for the document | They show computed on older version until re-run |
| The document is later amended | The amendment starts with these values copied |
9. Don't confuse this with…
| Guided fill and auto-fill | Faster ways to fill this same form |
| The template | The fixed wording these values are merged into |
| Preview and versions | The generated result, and snapshots of it |
| Smart fields | Values extracted out of a finished document, not typed in |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| The fields will not accept typing | The state is not draft, negotiation or returned, the document is sealed, or you lack Edit draft documents / data values. |
| A brand-new document is read-only | The type's starting state is not named draft (§3) |
| A required field was left empty and nothing stopped it | The transition's action is not submit |
| A value does not appear in the preview | The template does not reference that field code, or the save has not completed |
| A field I expected is missing | It is conditional, and its condition is not met |
| The title will not change | The document has left the editable states |
An auto: field is empty | The merge source had nothing for this record |