Taxonomy, lifecycle, tags & events

In one line. The four configuration tabs inside a Collection that turn raw documents into classified, reviewed, decided, and reported-on records: Taxonomy, Lifecycle, Tags, and Events. You’ll be able to. Read and edit a collection’s classification labels, design the review stages a document moves through (including auto-decide rules), tag records, and fire an external webhook when a document changes stage. Where this lives. Studio ▸ Data Model ▸ Collections ▸ <collection> — then the Taxonomy (Schema), Lifecycle, Tags, and Events tabs in the right pane.

Why it matters

Collections & schema gave you a Collection and a schema — the shape of a record. This page gives the record a life. Once a document lands, four things decide what happens to it: how it’s classified (Taxonomy), the stages it moves through and who reviews it (Lifecycle), the tags people stick on it (Tags), and the external systems told about it (Events). Three of these tabs are short; Lifecycle is the big one, because that is where “AI extracted some fields” becomes “the business made an auditable decision.”

Watch out — the one confusion to avoid. A Lifecycle / Stateflow is the set of stages a document moves through (Intake → Review → Approved…). An XFlow is a pipeline of operators that does processing work. They are different objects; the codebase unhelpfully calls both “workflow.” This whole page is about Lifecycle, not XFlow. XFlows are covered in XFlows & pipelines.

Taxonomy (Schema) tab — classification vs extraction

You met this tab in Collections & schema as the place you define Learners (trainable extractors) and their Labels (fields). Here we focus on one specific use of it: classification.

There are two jobs a Learner can do, and the difference is the Type you pick when you create it:

Job	What it produces	Learner Type to choose
Extraction	Pulls a value out of the document — `invoice_total`, `due_date`.	A field/record/table type.
Classification	Assigns the document (or a page/section) to a category — “this is an Invoice”, “this page is a Cover Letter”.	Document / Page / Section / Table Classification.

A classification label is just a Label living under a Classification-type Learner: its name is a category the document can be sorted into (e.g. Contract, Invoice, Statement). Classification results are what drive routing later (a Conditional lifecycle stage can branch on them — see Lifecycle below).

Creating a classification label

Studio ▸ Data Model ▸ Collections ▸ <collection> ▸ Schema (or the + Taxonomy header button):

Click Taxonomy (footer) to open Create Taxonomy. Give it a Name and Description.
Set Type to one of Document / Page / Section / Table Classification, pick the Entity (collection), and Submit.
Select the new Learner, open the Labels sub-tab, click + Label.
Enter the category as the Label Name (e.g. Invoice) and a Description (both required).
Show Advanced Settings reveals the same six accordions as any label (Table Styling, Contextual Insights, Record Config, Toggles, Lookup Config, View Config). For a plain classification label you rarely need them — leave defaults.
Add (keep going) or Add and exit.

Bulk import

On the Label dialog switch to the Import labels tab to load many categories at once: drag-drop or Choose File a .txt / .xlsx / .tsv / .csv; parent-to-child hierarchy is expressed by indentation (text) or columns (spreadsheet); Upload & Create.

Tip. Keep classification Learners small and flat — one Learner per decision (“Document type”, “Risk band”) with a handful of labels each. It reads better in the Conditional stage editor.

The full field-by-field reference for every label advanced option lives in Collections & schema; this page doesn’t repeat it.

Lifecycle tab — the stages a document moves through

This is the heart of the page.

A Lifecycle (a Stateflow) is an ordered set of stages, with role-gated edges between them. Every document in a Processing collection carries a current stage. Moving a document from one stage to the next is the unit of progress — and every move is written to an audit trail (document_workflow_history). A “decision” on the platform isn’t a separate object; it’s simply read back from that trail of stage moves. That is the whole point of the Lifecycle: it turns AI output into an auditable business decision.

The default: the 8-stage Four-Eyes flow

Every new Processing collection is seeded with the Four-Eyes lifecycle. Its motto: AI recommends, two humans confirm, the platform remembers. (How the humans in it actually receive and work their queue is Human-in-the-loop.)

#	Stage	Type	Role that handles it	Sends to Inbox?
1	Intake	Start	everyone	no — system assigns on ingest
2	AI Processing	In-progress	everyone	no — the intake agent is running
3	AI Recommendation	In-progress	everyone	no — branches by confidence / policy
4	L1 Review	In-progress	L1-Reviewer (also visible to L2-Approver)	yes — first human eye
5	L2 Approval	In-progress	L2-Approver	yes — second human eye (the gate)
6	Needs Info	In-progress	everyone	yes — Inbox stage; awaits more info, then re-runs AI Processing
7	Approved	End	everyone	no — terminal (approved)
8	Declined	End	everyone	no — terminal (declined)

Intake (Start)
  │ auto on ingest
  ▼
AI Processing ◄──────────── re-runs when info arrives ──┐
  │ agent done                                          │
  ▼                                                     │
AI Recommendation                                Needs Info (Inbox)
  │                                                     ▲
  ├─ policy ON & confidence passes: auto-decide         │
  │  skips both reviewers ──► Approved / Declined       │ needs-info
  │                                                     │
  └─ low confidence / always ──► L1 Review (Inbox, L1-Reviewer)
                                   │ approve       ├ reject ──► Declined
                                   ▼               └ needs-info ─┘
                                 L2 Approval (Inbox, L2-Approver)
                                   ├ approve ──► Approved (End, terminal)
                                   └ reject  ──► Declined (End, terminal)

Under the hood. The Four-Eyes seed creates exactly two reviewer roles — L1-Reviewer (bound to L1 Review) and L2-Approver (bound to both review stages) — alongside the lifecycle. (Admin exists as a general project role, but it is not part of the Four-Eyes seed.) The seeded stages ship with ViewedByRoleIds null (open to all); gating is expressed the inverse way — each role carries the stage ids it handles — and you assign any further per-stage gating yourself via Can be viewed by (ViewedByRoleIds). Roles are covered in Security & governance.

Layout of the Lifecycle tab

Left “Lifecycle” panel — lists the collection’s stateflows by Name + Description; a star marks the Primary. Row menu: Edit / Delete (Delete is hidden for the Primary). Footer + Lifecycle to add one.
Right pane — the stage graph (WorkflowGraphComponent; drag to reorder, click a stage to open the State editor), a legend strip (Start / Conditional / End markers), and — for Processing collections — the Auto-Decide policy card.

What every control does

Lifecycle (stateflow) level — the + Lifecycle / Edit dialog:

Control	What it does	Notes
Name / Description	Identify the lifecycle.	Required.
Entity	Which collection it belongs to.	Prefilled to the current collection.
Set as Primary	Makes this the default lifecycle for the collection.	Exactly one Primary.
Allow Back Propagation	Lets documents move backwards to an earlier stage.	E.g. L2 sends back to L1.
Include StateFlow Change Message	Prompts for a note when a document changes stage.	Captured in the audit trail.
Disable Show Stage History	Hides the per-document stage history.	Default off (history shown).

Stage level — the Create / Edit State dialog:

Control	What it does	Notes
State Name / Description / Final Name	Name the stage.	Final Name is the label shown when terminal.
Workflow State	`Start` / `In-progress` / `End`.	Exactly one Start, one End.
Send to Inbox (human review)	Routes documents reaching this stage to the human work queue (Inbox).	This is `IncludeManualIntervention` — what makes a stage a review stage. Routing detail: Human-in-the-loop.
Can be moved to	Target stages — the outgoing edges.	Multi-select.
Can be viewed by	Roles allowed to see/act on documents here.	`ViewedByRoleIds`; empty = all roles.
Legend	A coloured tag on the graph; inline Create New Legend (Name + colour).	Cosmetic + grouping.
Document View Type / history-visibility	Display options.	—
Automation Type	The action this stage runs on entry (11 types).	Summarised next.

What a stage can do: the 11 automation types

A stage isn’t only a waiting room — on entry it can trigger one Automation. The picker offers 11 types. Briefly:

Agent Flow — run an agent/agent-team on the doc. AI Pipeline — run an AI pipeline. Rescore — refresh confidence scores. Ingestion — pull data from sources. Export — push the doc out via an export template. Events — fire the collection’s webhooks. RPA Bots — hand to an RPA bot. Conditional — branch to different next-stages by label value. Auto Allocate Users — auto-assign reviewers. Auto Derivation — compute/auto-fill labels. Regroup Summary — refresh roll-up summaries.

The Conditional type is the workhorse for routing: “if document_type = Invoice, go to Invoice Review.” Each type is configured with its own fields and toggles.

The Auto-Decide policy card (Processing collections)

Below the graph sits the Auto-Decide policy card — a single knob that lets the platform auto-approve (or auto-decline) clean documents without sending them through L1 + L2. It is OFF by default; even when on, it only fires when the agent’s confidence and flags pass.

Field	Default	Meaning
Enabled	`false`	Master switch. Off means every document visits L1 and L2.
Min Confidence	`0.92`	Agent confidence floor required to auto-promote.
Require Zero Flags	`true`	If any flag is open on the doc, no auto-promote.
Max Amount	`null`	A dollar-amount ceiling; `null` = no cap. (Reads from Amount Field.)
Applies To	`both`	Which verdicts may auto-fire: `approve` / `decline` / `both`.

The card shows a plain-English preview, e.g. “Auto-approve when AI confidence ≥ 0.92 AND zero flags AND amount ≤ $500k.” The safest first step most operators take is Enabled = true, Applies To = approve — auto-approve clean cases, always keep human eyes on declines.

Under the hood. Auto-decide is evaluated in the orchestrator, never spoofing a user: an auto-decided document’s audit row shows actor AI/auto plus the confidence; a normal AI handoff shows AI/recommended. The audit trail stays truthful.

Validation rules

Before you can switch stateflows or save, the lifecycle must be a valid graph:

Exactly one Start and one End stage.
At least one Start → End path.
No unterminating cycles.
A stage can’t be deleted while documents currently sit in it.

If it’s invalid you get the toast “Please validate the workflow before proceeding.”

Watch out — Reset to default is destructive. The Reset to default action rebuilds the Four-Eyes flow and is gated behind a confirm-by-EntityId prompt. Don’t use it to “clean up” a lifecycle that already has live documents.

How stages move a document (and produce the decision)

Putting it together for one document:

It lands in Intake (Start) automatically on ingest.
The intake agent runs (AI Processing), extracts fields against the schema with a confidence per field, then sits at AI Recommendation.
If Auto-Decide is ON and the doc passes, it jumps straight to Approved/Declined. Otherwise it routes to L1 Review and is sent to the Inbox (Human-in-the-loop covers what the reviewer sees there).
A reviewer with the L1-Reviewer role acts; approve sends it to L2 Approval, reject ends it, or it goes to Needs Info — also an Inbox stage, which re-runs AI Processing once more info arrives.
L2 Approval (the second eye) finalises it to Approved or Declined.
Every one of these moves appended a row to the audit trail. The “decision” is that trail — who moved it, when, with what note, at what confidence.

Tags tab — free-form labels people stick on records

Studio ▸ Data Model ▸ Collections ▸ <collection> ▸ Tags.

Tags are a small, project-wide set of free-form labels your reviewers apply to documents (internally the code calls them “Error Types”). Use them to mark things like Duplicate, Missing PO, Wrong Vendor — anything you want to filter or report on later that isn’t an extracted field.

A simple table: each tag’s Name plus Edit and Delete (Delete confirms “Delete ?”).
+ Tag opens the Add/Edit dialog: one Tag name field (required; rejects duplicates with “Tag name already exist”) and Save.
Empty state: “No tags found in the project” with a Tag button.

That’s the whole tab — tags are deliberately simple. Reviewers apply them on the document detail surface (Document detail).

Events tab — fire a webhook when something changes

Studio ▸ Data Model ▸ Collections ▸ <collection> ▸ Events.

An Event is a subscription that fires an external action (an HTTP webhook, an email, a Slack message, …) when something happens to a document — a lifecycle stage change, a label change, an ingestion failure, and so on. This is how you tell your systems that the platform did something: “POST to our ERP the moment an invoice reaches Approved.”

Left “Events” panel — lists events by Name + trigger; row menu View Event / Edit / Delete; footer + Event.
Right details panel — shows the event’s trigger types, action type, and action details (Webhook URL / email To+Subject / Slack URL).

Creating an Event

Open + Event (the Create/Edit Event Details dialog):

Control	What it does	Notes
Name	Identify the event.	Required.
Events (triggers)	The trigger types — multi-select (Stage change, label change, Ingestion failure, Callback, …).	“Document” reads as your record noun.
Entity	The collection.	Prefilled.
Workflow + Stage	When a stage-change trigger is chosen, scope it to a specific lifecycle and stage(s).	This is the lifecycle-to-events link.
Jobs (Ingestion-Failure only)	Which ingestion jobs to watch; empty = all.	—
Callback types (Callback trigger only)	Which callbacks fire it.	—
Actions (`+ Add Action`)	One or more actions, each with a Notification Type: Webhook (URL), Email (To + Subject), Slack (URL), etc.	An event can fire several actions.
Show Advanced Settings	Check SLA Breach + SLA Time (sec), Check File Upload, Alert Frequency (min), label filters, user filter.	Use SLA fields to alert when a doc sits too long.

Walkthrough — webhook on “Approved”

Events tab, then + Event. Name: Notify ERP on Approved.
Events trigger — choose the stage-change trigger.
Workflow — Four-Eyes; Stage — Approved.
+ Add Action — Notification Type Webhook — paste your endpoint https://erp.example.com/bm-hook.
(Optional) Show Advanced Settings — set Check SLA Breach + SLA Time if you also want a late-document alert.
Save. From now on, every document that reaches Approved POSTs to your endpoint.

Tip. Two ways to fire a webhook on a stage change: an Event here (declarative, recommended) or an Events-type automation on the stage itself (Lifecycle tab). Prefer the Event subscription unless you specifically need it bound to stage entry inside the graph.

Try it yourself

Pick one of these on a Processing collection (e.g. the Invoices collection from Collections & schema):

A — an “auto-approve under $500” rule. Open the Lifecycle tab, then the Auto-Decide policy card. Set Enabled = true, Applies To = approve, Max Amount = 500 (and set the Amount Field to your total label, e.g. invoice_total). Save. Confirm the preview reads roughly “Auto-approve when AI confidence ≥ 0.92 AND zero flags AND amount ≤ $500.” Now clean invoices under $500 skip both reviewers; everything else still goes through L1 + L2.

B — a webhook on approval. Follow the Events walkthrough above to POST to a test endpoint (use a free request-bin URL) when a document reaches Approved. Drive one document to Approved and check the bin received the call.

Either way, open the document’s stage history afterwards and notice the audit trail — that’s your decision record.

Recap

The Taxonomy/Schema tab also defines classification labels (Document/Page/Section Classification Learners) — categories used later for routing.
A Lifecycle / Stateflow is the ordered stages a document moves through; new Processing collections are seeded with the 8-stage Four-Eyes flow (Intake → AI Processing → AI Recommendation → L1 Review → L2 Approval → Needs Info → Approved/Declined).
A stage has a type (Start/In-progress/End), edges (Can be moved to), role-gating (Can be viewed by / ViewedByRoleIds), a Send-to-Inbox flag (IncludeManualIntervention), and one of 11 Automation Types it runs on entry.
The Auto-Decide policy card auto-approves/declines clean docs (OFF by default; confidence + flags + amount cap gate it).
Every stage move is written to an audit trail — the platform’s “decision” is that trail.
Tags are a simple free-form label set; Events fire webhooks/email/Slack on stage or label changes.
Lifecycle ≠ XFlow. This page was Lifecycle.

Where to go next

Dashboards & Inbox — where the humans you route to in L1/L2 actually do the reviewing.
Human-in-the-loop — how Inbox routing and review assignment work end to end.
Security & governance — the seeded Four-Eyes roles (L1-Reviewer, L2-Approver) that stage-gating depends on, and project roles like Admin.
XFlows & pipelines — the other “workflow”: processing pipelines, not document stages.