Transactions

Transactions represent a batch of documents uploaded for processing. They are the primary unit of work in DocAI Fabric.

Transaction Lifecycle

Created → Queued → Processing → Completed / Failed
                       ↕
                 Awaiting input

Any of the first four → Cancelled (stopped by a person)

1. Created: Transaction exists and documents can be uploaded to it
2. Queued: Processing has been requested and a worker will pick it up
3. Processing: The workflow engine is running activities on the documents
4. Awaiting input: The workflow is paused for something outside itself, most often a human review step
5. Completed: The workflow reached its end
6. Failed: An activity failed and the workflow could not continue
7. Cancelled: Someone stopped it (see Cancelling a transaction)

Creating a Transaction

Via the UI

1. Open a project
2. Click New Transaction
3. Upload files using drag-and-drop or the file picker
4. (Optional) If a single file is selected, enable Limit Pages and set the number of pages to process
5. Click Process to start the workflow

Other ways to start

The same dialog offers two alternatives to uploading from your computer. Capture with phone shows a QR code that opens the camera on your phone and sends the photos straight into a new transaction in the dataset you are working in (not offered while you create a new evaluation dataset, which exists only once its first files are uploaded). Copy from another dataset brings transactions that already exist elsewhere in the project (Playground, Work Queue, Memory, or an evaluation dataset) into the one you are working in. Copying is available on Playground, Memory, and Evaluation.

Naming

If your project calls its transactions something else, set Item name in project settings. The button then reads New Invoice, New Port Call, and so on, throughout the app.

Page Limit

When uploading a single file, you can choose to process only the first N pages. The full file is always stored; only the conversion step is limited. This is useful for previewing large documents or testing workflow settings.

Uploading an email

You can drop a saved email onto the same dialog: .eml (most mail clients, and Save as in Outlook on the web) or .msg (dragged out of Outlook for Windows). An email is not treated as a single document. It is opened into the transaction it describes:

What arrives	What it becomes
The message body	The first document, laid out as a PDF with a printed header showing From, Received, To, Cc, Subject and the attachment list
Attachments in a supported format (PDF, TIFF, PNG, JPEG, HEIC)	The remaining documents, in the order they were attached
Sender, recipients, subject, received time, importance	Transaction metadata, available as email_* columns and as field values
The original message file	Kept with the transaction, never processed

Attachments in other formats are not imported; each one is listed in the transaction's Activity Log with the reason, so you can see what the message contained. Images embedded in the body (signatures, logos) stay part of the body rather than becoming documents of their own.

Each email always creates its own transaction, even with Upload each file as a separate transaction switched off, because the sender and subject belong to one message. You can drop several emails at once, and mix them with ordinary files: every email gets a transaction, and the other files follow the switch.

This is the same result you get from an email import connector, so it is a good way to try a mailbox's typical message before setting one up.

Using email details in fields

Because the envelope lands in transaction metadata, an extraction field can be filled from it instead of from the page. Set the field's value source to Transaction metadata and pick a key such as email_from or email_received_at.

Uploading a ZIP archive

A .zip file works the same way: the archive is opened and its files become the transaction's documents.

What arrives	What it becomes
Files in a supported format (PDF, TIFF, PNG, JPEG, HEIC), in any folder inside the archive	The documents, as one flat list. Folder structure is ignored; files are ordered by their path inside the archive, with numbers sorted naturally (page2 before page10)
The archive file itself	Kept with the transaction, never processed

Two files with the same name in different folders both come through; the second is renamed (invoice.pdf, invoice_2.pdf). System files that archiving tools add (__MACOSX, .DS_Store, Thumbs.db) are dropped quietly. Everything else that is not imported is listed in the Activity Log with a reason:

• unsupported format: a file type the platform does not process (for example .docx or .csv)
• password protected: an encrypted entry
• an email or archive inside the container is not opened: an .eml or .msg inside the archive is not expanded, because an email's sender and subject belong to a transaction of their own. A .zip inside the archive is opened one level down; deeper than that it is listed instead

An archive that holds nothing importable is rejected, and nothing is stored. There are limits per archive: 200 documents and 500 MB unpacked. An archive over either limit is rejected with a message saying so; split it and upload the parts as separate transactions.

Like an email, each archive always creates its own transaction, and Limit pages is not offered for it.

An archive carries no sender or subject, so nothing is written to transaction metadata.

Via the API

The quickest route is the one-step endpoint, which creates the transaction and starts processing in a single call:

curl -X POST "https://app.docaifabric.com/tenants/{tenant_id}/projects/{project_id}/transactions/process" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"source_files": [{"filename": "invoice.pdf", "base64_data": "JVBERi0xLjQK..."}]}'

For several files, or to set options before processing starts, create the transaction first and upload to it, then start it. Process Documents via API is the full reference for both routes, including the fields each one takes.

An email file or a ZIP archive is uploaded the same way and is expanded server-side, exactly as it is in the dialog. Because one file in becomes several out, send it on its own to an empty transaction; the response lists the resulting documents, echoes expanded_from, and lists anything the container held that was not imported under skipped_entries, each with a reason code (unsupported_format, password_protected, nested_container, not_a_zip).

curl -X POST "https://app.docaifabric.com/transactions/{transaction_id}/source-files" \
  -H "X-API-Key: your-api-key" \
  -F "files=@invoice_email.eml"

Transaction Contents

Each transaction contains:

Component	Description
Documents	Individual documents detected after splitting
Pages	Individual pages with OCR text and images
Workflow State	Current processing status per activity
Source Files	Original uploaded files

Viewing Results

In the transaction detail view, you can:

• Browse documents: See all documents detected in the upload
• View extractions: See extracted field values with confidence scores
• Inspect pages: View page images with bounding boxes around extracted data
• Check classification: See how each document was classified
• Review & correct: Manually fix any extraction errors

Transaction States

These are the values the API reports in a transaction's status field:

State	Description
created	Created, awaiting files or a start request
queued	Waiting for a worker to pick it up
processing	Actively running the workflow
awaiting_input	Paused for external input, typically human review
completed	All processing finished
failed	An activity failed; the response carries error_message
cancelled	Stopped by a person; the response carries cancelled_at, cancelled_by, cancelled_by_name, cancel_reason and cancelled_to_checkpoint

Individual workflow steps have their own statuses, which are shown in the transaction's Activity Log and are not the same list.

Re-running transactions

Re-running processes a transaction again. Which project settings it uses depends on the dataset and on where it starts: see Which configuration a re-run uses. The Re-run menu is on the Playground, My Work Queue, Evaluation and Memory pages, in each row's actions and in the toolbar when several transactions are selected. It appears only if you are allowed to re-run transactions in that project.

• From Beginning runs the whole workflow again. It is always available at once.
• After a step (for example After Classify) keeps the results of that step and everything before it, and runs only the steps after it. When you are tuning extraction, this skips OCR and classification.

For one transaction the menu lists its own checkpoints, with the time each was written. A transaction that completed does not offer its last step, since nothing runs after it; one that was cancelled or failed does, so you can pick up where it stopped. For several, it lists the steps they can be re-run from, and loads them while "From Beginning" is already available. A step that only some of the selected transactions reached shows how many, for example 12 of 15: choosing it re-runs those 12 and skips the other 3, and the message afterwards says how many were skipped.

When a workflow sends a transaction back through a step, for example an IF branch that loops back or a review sent back to an earlier step, re-running from after that step starts from its first run.

Which settings a re-run uses depends on the page. On My Work Queue, From Beginning uses the latest published version, and a re-run from after a step keeps the version the transaction ran under, so the results it keeps still fit. On Playground, Memory and Evaluation a re-run always uses the draft (Versions and Publishing).

On the Evaluation page a re-run replaces only the latest results. The ground truth they are compared with stays as it is. On the Memory page a re-run rebuilds the sample's examples in the draft memory (Re-running samples).

In the Transaction Viewer you can also ask the Assistant to re-run the transaction, from the beginning or from after a step. It asks you to confirm first.

Through the API:

POST /transactions/rerun-steps              {"transaction_ids": [...]}
POST /transactions/{transaction_id}/rerun   {"from_activity_id": "classify"}

The first call returns the steps the transactions can be re-run from, each with a count of how many can. The second re-runs one transaction from after that step, or from the beginning without from_activity_id, and answers 409 rerun_step_not_reached when the transaction has no checkpoint after it. Both need the transaction.rerun permission. Its transaction_id is the transaction that runs: on a Memory sample that is a draft copy when one was made.

Which configuration a re-run uses

Re-run	My Work Queue (production)	Playground, Evaluation and Memory
Transaction, from the beginning	The latest published version. The transaction moves to that version.	The current draft
Transaction, after a step	The version the transaction was processed with	The current draft
One document: Re-classify or Re-extract	The version the transaction was processed with	The current draft

A production transaction answers the same way whether it is processed, re-run after a step or re-run one document at a time, because all three use the version it was processed with. To apply a newly published version to it, re-run it from the beginning. To try a draft change on production work, copy the transaction to the Playground and re-run it there.

Re-running one document

In the Transaction Viewer, the re-run button above a document's fields re-runs that one document: Re-classify (classification, extraction and validation), Re-extract (extraction with the document's current class, then validation) or Re-validate (business rules only). It needs the same permission as re-running a transaction.

Re-classify and Re-extract run the workflow's own Classify and Extract steps on that one document, with those steps' settings and model, exactly as processing does. Only that document changes. The rest of the transaction stays available for review while it runs, and validation then runs for the whole transaction, so rules that compare documents stay correct.

If the workflow has more than one Extract step, for example on two branches after an If step, the re-run uses the step that processed this document before, or the first one in the workflow if none did. A document re-run does not evaluate If or Switch steps again. If Re-classify changes the class and your workflow branches on the class, re-run the transaction after the step that comes before Classify (for example After OCR) instead, so the document takes the new branch.

If the re-run fails, the document keeps the class and values it had before the re-run, and the transaction's status does not change. A message in the Transaction Viewer names the step that failed and the reason. The transaction's activity log records the request (with who made it) and the outcome, including when the re-run was asked for by the Assistant. A re-run fails, for example:

• when a step fails with an error, such as a business rule whose code fails
• when a budget that stops processing has been reached
• when classification or extraction is turned off in the project

A failed re-run is not retried automatically. Correct the cause, then re-run the document again.

Cancelling a transaction

When a transaction is stuck, or finishing it no longer makes sense, you can stop it. Choose Cancel processing... from the row's actions, or select several transactions and choose it from the toolbar. The command appears on the Playground, My Work Queue and Evaluation pages, for transactions that are created, queued, processing or awaiting review, and only if you are allowed to re-run transactions in that project.

The dialog asks for an optional reason. After you confirm:

• Processing stops. The step that was running is rolled back to the checkpoint written after the last step that finished, so everything before it keeps its results and nothing half-done remains.
• A transaction waiting for review is not rolled back. The reviewer's edits stay.
• The transaction ends in cancelled and nothing restarts it: no retry, no recovery after a restart. You can still re-run it, or re-run a single document, whenever you choose.

Who cancelled it, when and why is shown under the title bar in the Transaction Viewer, as an entry in the Activity Log, and in the Security and Audit Log as admin.transaction.cancelled. To find cancelled transactions, filter the list by status Cancelled.

On the operations dashboards a cancelled transaction counts like a failed one: it is not counted as processed.

Through the API:

POST /transactions/{transaction_id}/cancel     {"reason": "..."}
POST /transactions/bulk-cancel                 {"transaction_ids": [...], "reason": "..."}

Both need the transaction.rerun permission. The bulk call takes up to 100 ids and answers {cancelled, failed, errors}. Cancelling a transaction that is already cancelled returns the first cancel unchanged.

Every call that takes a list of transaction_ids acts only on the transactions you could open one by one. Any other id is reported in errors as not found, or left out, as if it did not exist.

Bulk Operations

You can process multiple transactions at once:

1. Select transactions in the project view
2. Use the bulk action menu to:
   • Process selected transactions
   • Reprocess failed transactions
   • Delete selected transactions

Copying selected transactions to another dataset

The same toolbar can copy the selected transactions into another dataset, so you can take real work and reuse it in design time. Every page offers the destinations it is not itself: Add to Playground (a sandbox copy you can re-run freely), Add to Memory (teach the system from these transactions), and Add to Evaluation (use them as reference data for accuracy testing).

Copying from My Work Queue into Playground or Evaluation requires permission to copy production work into design time, and Add to Memory appears only for users the system is allowed to learn from. A transaction added from My Work Queue goes straight into production memory when production would learn it anyway, otherwise into the draft memory, which reaches production when the project is published; from other pages it always goes into the draft. See Adding transactions by hand.

The toolbar keeps each page's own actions first (Assign and Priority on My Work Queue, Re-run on Evaluation, Re-run and Revert on Memory) and groups the copy actions after a divider. On a narrow window the copy actions move into a ... menu so the page's own actions keep their space.