Tutorial: build and run an extraction project

This guide walks you, end to end, through pulling structured data out of documents with Zoan Automation: create the extraction project in the portal, extract with a playbook, have a person review what it pulled, and hand the data to the next step. No prior experience needed.

We’ll use a concrete example: a biomedical equipment life-record sheet (serial, manufacturer, dates, maintenance history). Swap the fields and you have any other document.

The map: what we’ll build

   Document (PDF)
        │
        ▼
   idp-extract ──── reads, extracts and locates every value ──── the PROJECT governs everything
        │
        ▼
   Zoan Cloud (store) ── keeps the document + extraction, renders the pages
        │
        ├── fields below threshold? → Validation station (a person corrects them)
        │
        ▼
   Output queue ── your business bot picks up the already-validated data

The core idea: the extraction project holds all the configuration (which fields, which model, credentials, retention). The playbook only says which project and where the document comes from. Whoever knows which fields matter works in the portal, without touching the playbook.

The components

Piece	What it is	Where it lives
Extraction project	The document’s contract: canonical schema + format profiles + config.	Portal (Zoan Cloud)
IDP Extract activity	Extracts the project’s fields from a document.	Playbook (Designer)
Document store	Keeps the document, the extraction and the rendered pages.	Zoan Cloud
Validation station	Where a person reviews the fields that fell below the threshold.	Portal
Output queue	The hand-off to the bot that processes the data downstream.	Zoan Cloud
Classification station	For files with several documents: confirm the split before extracting.	Portal

Before you start

You need:

An environment created in Zoan Cloud (e.g. production or testing).
An agent installed and connected to that environment (where the playbook runs). See Agent installation.
A model credential: the Anthropic API key stored as a Zoan Cloud credential (step 2).

Step 1 — Create the extraction project

In the portal, open the Extraction projects menu and click New project. The project is created with just its identity; everything else is configured afterward, in tabs.

1.1 Identity

Field	Example	What it is
Name	`hoja-de-vida`	The name the playbook calls it by. No spaces.
Document type	`life-record sheet`	Descriptive, for the inboxes.
Description	`Biomedical equipment life-record sheet`	Helps the model know what the document is.
Scope	`Global` or `This environment`	Global = shared by all environments; environment = only that one (takes priority).

1.2 The canonical schema

This is the output contract: the fields the project delivers, always under the same name, even if the document’s layout changes. In the Canonical schema tab, add one field per row:

Name	Type	Threshold	Description (the model reads this)
`serial`	string	0.85	The equipment serial number.
`manufacturer`	string	0.80	The equipment manufacturer.
`install_date`	date	0.90	The installation date.
`maintenance`	table	0.80	The maintenance history (columns: date, action, technician).

Two key ideas:

The description is what the model uses to decide what goes in each field. Write it the way you’d tell a person.
The threshold (0 to 1) is per field: a value whose confidence is below its threshold goes to human review. The business sets it: a serial matters more than a note.

Confidence is not something we ask the model. It is measured by locating the value in the document (grounding). That is what makes the threshold trustworthy.

1.3 Format profiles (optional)

If the same document type comes in several layouts (different manufacturers, different templates), you create a profile per format in the Formats tab. Each profile:

has a router key (the printed code that identifies that format), and
can override canonical fields (a different description, another threshold) without changing the contract.

If there’s only one layout, you don’t need profiles.

1.4 Reading and model

In the Reading and model tab:

Field	Typical value	What it is
Model	`claude-haiku-4-5`	The LLM that extracts.
Reading mode	`auto`	`auto` uses the PDF’s text layer and only scans if there isn’t one; `text` never scans; `azure-di` always scans (for PDFs that are photos).
Model credential	`anthropic-key`	The Zoan Cloud credential holding the API key (step 2).
OCR endpoint / credential	(empty)	Scans only: the Azure Document Intelligence resource.

1.5 Governance and retention

In the Governance and retention tab:

Field	What it is
Retention (days)	How many days uploaded documents are kept. It is a legal responsibility: keep only what you need.
QA sampling	The fraction of auto-accepted documents reviewed anyway, to watch quality.
Auto-accept	Approve documents with no below-threshold fields without review. Turn it on only after calibrating.
Output queue	The name of the queue extracted documents go to as work for the downstream bot. Empty = no queue (the data stays in the store).

1.6 Publish

When the project is ready, click Publish. This freezes the version the runtime uses: from there, editing the schema or the profiles does not break in-flight extractions — the draft is edited separately and only applies when you publish again. The state shows in the editor: Published / Unpublished changes / Not published.

Step 2 — The model credential

In the environment’s Credentials, create a credential:

Field	Value
Name	`anthropic-key`
Value	(your Anthropic API key)

The playbook never sees the key: it names it and Zoan Cloud resolves it. See Credential management.

Step 3 — The extraction playbook

In the Designer, create a playbook. The normal case is two nodes: list the files and extract each one.

List Files    path      = "D:\life-records\inbox"
              pattern   = "*.pdf"
              recursive = true
              → output: files

For Each      items        = = files
              itemVariable = file
              │
              └── IDP Extract   path    = = file
                                project = "hoja-de-vida"

That’s all you need to extract. IDP Extract does everything expensive inside: reads the document, routes to the profile, extracts in a single call to the model, locates every value (grounding), and persists the document + extraction to the store. Zoan Cloud renders the pages for review, and if the project has an output queue, it enqueues the clean documents.

There is no pdf-to-images or documents-upload: the platform does that.

IDP Extract parameters

Parameter	What it is
`project`	The name of the extraction project. Everything comes from it: schema, model, credentials, reading mode.
`path`	The document’s path.
`reference`	A stable key (idempotency): if that document was already extracted, it reuses the stored result and does not pay Azure/LLM again. Defaults to the file name.
`pages`	Which pages to read (`"1-3"`). Empty = all.
`document`	A document already read by IDP Classify — to avoid re-reading it (useful in bundles).

credential, azureCredential, dpi, mode and the endpoint are not set here: the project governs them. They appear only as an advanced override.

Step 4 — Run

Click Run in the Designer. In the logs you’ll see something like:

list-files: ... → 3 entries
idp-extract: routed to format 'nuevo-formato'.
idp-extract: 1 call(s), 5023 input + 410 output tokens.
idp-ground: 42 of 45 field(s) accepted; 3 need review.
idp-extract: persisted extraction as document 07d0fca7-... (reference 'life-record-2506193.pdf').
enqueued document 07d0fca7-... → queue 'hojas-de-vida-carga' (new item ...)

What happened: it was read once, the 45 fields were extracted in one call, they were located (3 fell below threshold → review), the document was saved, and since it didn’t need full review it was enqueued for the downstream bot.

If you run it again, you’ll see already extracted — reusing the stored result, skipping OCR+LLM: idempotency avoids paying twice.

Step 5 — Review

Documents with below-threshold fields appear under Documents → To review in the environment. Open one: it’s the validation station.

On the left, the document’s pages (rendered by Zoan Cloud).
Over each value, a box with its confidence. The ones needing review come first.
Correct the value if needed and click Approve.

On approval, the document turns to validated and, if the project has an output queue, enters the queue with its corrected values. A Back button returns you without validating.

Step 6 — The downstream bot (performer)

The already-ready documents (clean at extraction, reviewed at validation) sit in the output queue. A second playbook processes them:

Process Queue   queueName    = "hojas-de-vida-carga"
                itemVariable = item
                │
                ├── Set Variable   name  = data
                │                  value = = item.SpecificContent
                │
                ├── (your real load goes here: item.SpecificContent["values"]
                │    holds the fields; load them into your target system)
                │
                └── Set Transaction Status   item   = = item
                                             status = successful

The item carries the data (values) plus a documentId to trace it. The performer loads it into your system and closes the transaction. No bot waits for the review: it is asynchronous.

Documents with several types in one file

If a PDF brings several documents concatenated (life-record + maintenance report + calibration), use IDP Classify before extracting. It classifies each page (its type and whether it starts a new document) and returns segments.

IDP Classify   path     = = file
               projects = ["hoja-de-vida", "reporte-mantenimiento"]
               → output: doc

If the split is clear, the playbook extracts each segment by its range and type.
If it’s uncertain (doc["splitNeedsReview"] is true), it sends the bundle to the classification station with documents-classify-bundle and moves on. A person confirms the boundaries/types under Documents → Classify, and the idp-extraer-confirmados playbook extracts the confirmed ones with documents-take-classified.

This way, no matter how the documents arrive, there is always a way to get the split right.

Behavior: what’s worth knowing

A single model call. Extraction asks for all fields at once, without strict grammar, and validates the result. The document is read once (it used to be ~10 calls re-sending the document).
Measured, not declared, confidence. Grounding locates the literal in the page; that yields the confidence and the box. A value that isn’t located is flagged.
Idempotency. IDP Extract does not re-pay OCR/LLM if the document (by its reference) was already extracted.
Versioning. The runtime extracts against the published version; editing the project is a draft until you publish again.
Retention. Documents expire per the project/environment retention; a sweeper deletes them.
Pages. Zoan Cloud renders the document’s pages on demand from the file — the playbook does not upload them.

Activity quick reference

Activity	For	Doc
IDP Extract	Extract a project’s fields from a document.	See
IDP Classify	Tell which type each page is and split a bundle.	See
Documents Classify Bundle	Send an uncertain bundle to the classification station.	—
Documents Take Classified	Take the already-confirmed bundles to extract them.	—
Add Queue Item / Process Queue	Enqueue and process the downstream work.	Queues

Next steps

Concepts in depth: Document processing (IDP).
Calibrate with a gold set before turning on auto-accept.
Schedule the performer with a scheduled trigger.