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 a text file

Preview

Text file import is in Preview: ready to use, and it may still change based on feedback.

A plain text file (.txt, up to 1 MB) is a document like a PDF. Import lays its text out on A4 pages in a fixed-width font and processes those pages as it does a PDF's: you see the pages in the viewer, and classification and extraction read the file's exact text, with no OCR.

• Line breaks and pages are kept as they are in the file. A form feed character starts a new page, so a report printed in pages keeps them.
• Wide text: when a line is wider than a portrait page holds (about 94 characters), the whole file is laid out in landscape (about 139 characters), so the columns of a 132-column report stay aligned. A line wider still wraps onto the next line.
• Encoding: UTF-8 and UTF-16 are read as they are; a file in a Windows code page (Western, Central European, Cyrillic, Greek and the others) is recognized from its content. A short file that two code pages read equally well is read as Western European; save it as UTF-8 to be sure.
• Characters with no font: Chinese, Japanese, Korean, Thai and the Indic scripts show as empty boxes on the page image. Their text is still read, so extraction works.

The file must be named .txt and hold text: a file named .txt that holds anything else (a binary file, control characters) is refused as an unsupported file type, and an empty file, or one with only spaces and line breaks, is refused as empty. Other text formats, such as .csv, .json or .xml, are not imported as text documents.

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 documents and are not imported; each one is listed in the transaction's Activity Log, 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. An Outlook .msg attachment that is only a link to a file in the cloud, named like a supported file (invoice.pdf), cannot be imported: the email is rejected with the attachment's name, and nothing is stored.

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, and text files as described in Uploading a text file), 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.

Every other file in the archive is treated as a document, so an archive is imported whole or not at all. When it holds a file that cannot be imported, the archive is rejected, nothing is stored, and the message names each such file and why:

• unsupported format: a file type the platform does not process (for example .docx or .csv)
• password protected: an encrypted entry
• empty file: a file of zero bytes, or a text file with only spaces and line breaks
• a text file over 1 MB: split it, or send it as a PDF
• nested container: an .eml or .msg inside the archive, which is not expanded because an email's sender and subject belong to a transaction of their own, or a .zip more than one level down (a .zip inside the archive is opened one level down)
• not a zip: a .zip inside the archive that cannot be opened

Remove those files, or convert them to PDF, and upload the archive again. An import connector that picks up such an archive moves it to its failure folder with the same message. 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 the email attachments that are not in a supported format under excluded_entries, each with the reason excluded_by_mask. A container holding a file that cannot be imported is refused with 400 and the error code file_rejected, its message naming each file and why. skipped_entries is deprecated: it lists the same attachments as excluded_entries, with the reason unsupported_format.

A plain file that is not a PDF or an image (judged by its content, not its name), or a .txt that does not hold text, is refused with 400 and the error code unsupported_file_type naming the file; a .txt over 1 MB with text_file_too_large, and an empty one with empty_file. In each case none of the files in that request is stored. A file that opens but cannot be read in full, such as a damaged or password-protected PDF, fails the transaction at Import. See Import: files that cannot be imported.

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

Translated documents

When a workflow has a Translate step, or a page has been translated in the viewer, the image panel's toolbar shows an Original | Translated switch. Your choice is remembered for each project.

• Translated draws each translated phrase over its original words. Text that does not fit is made smaller, down to a readable size, and then cut; hover over a phrase to see its whole translation and the original.
• Copy Text in Translated view copies the translations of the phrases you select.
• Translate this page (in the toolbar's ⋮ menu, or in place of the translation on a page that has none) translates the page in view on demand. It uses the model, and its usage counts toward the transaction's cost; it needs edit rights.
• The switch also changes fields marked Translate: see Extraction Fields. Drawing a field's region in Translated view takes whole phrases, so the field takes their stored translation.

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.

Processing warnings

A processing warning means a step had to work around something to get a document through: for example, Extract extracted a document from its text alone after the model provider's content filter refused its page images, or a table stops before its end because the model did not return all its rows. The transaction carries on as usual, and Review does not show it: Review shows only validation issues, low-confidence values and Agent Review findings. The warning is in the transaction's Activity Log, which anyone who can open the transaction can read, so a reviewer who wonders why a document came out poorly can find the reason there and tell whoever sets up the project. The Assistant and the built-in Review Agent read it too; the agent notes such a warning in its findings.

Administrators, designers and supervisors (the "See processing issues" permission) see:

• an amber mark next to the transaction's status in the transaction list and the Work Queue, and in the transaction viewer's header. Clicking it opens the Activity Log on the warnings;
• a Has processing warnings filter in the list's filter menu;
• the project's warnings in the Processing issues section of the Monitoring page.

The mark describes the current result: re-running the transaction, or re-extracting the document, clears it unless the step needs the workaround again. The Activity Log keeps every run's warnings.

A transaction waiting at a review step that its assigned reviewer cannot review also carries a processing warning, "Assigned reviewer ... cannot review at ...": see Assigning a transaction. It clears when the transaction is assigned to someone else, released, reviewed or cancelled.

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, the last one included: a transaction that was cancelled or failed picks up where it stopped. To send a completed transaction's notification again without exporting again, choose After Export: only the steps after Export run. A re-run from any step before Export removes the last run's export files, and the download links a notification already sent stop working until Export runs again. If the re-run stops before Export, at a review for example, the transaction shows no exports until then. Any re-run from a step puts the transaction back as it was when that step finished, so a correction made after that is undone; re-running from the very last step does only that. 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.

When the model is busy (its provider is limiting how many requests it takes), the re-run does not fail at once. The cover over the document says Waiting for model capacity... and until when it keeps trying (5 minutes by default); if the model is still busy then, the re-run fails as above. It also fails if the server is restarted while it waits; run it again.

To stop a re-run, choose Cancel re-run on the cover over the document, whether it is waiting or running. The document keeps the class and values it had before the re-run, and the activity log records who cancelled it. Once the re-run has reached validation, its last step, it completes and the cancel has no effect.

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.

A failed transaction can be cancelled too, from its Resume dialog (see Resuming a failed transaction) or through the API. Nothing is rolled back, and the reason is required: it records why the documents were not delivered. The transaction.resume permission is enough for this one case.

Resuming a failed transaction

Preview

Resuming a failed transaction is in Preview: ready to use, and it may still change based on feedback.

A transaction whose step failed stops as Failed and waits for someone to decide what happens to it. Besides re-running it, you can resume it: run the failed step again, or carry on from any step after it. Nothing is restored. What the earlier steps produced, and every change made since the failure (a deleted document, values typed in the viewer, a document re-extracted), stays as it is.

• Resume at the failed step to try it again, for example after an outage or after fixing the model setup. Documents the step already finished are not processed again.
• Resume at a later step to carry on without the failed step. The steps in between are skipped and the Activity Log names who skipped them. If you resume at a review step after a skipped validation step, the transaction is validated first, so the reviewer sees its validation issues.

The transaction runs on the same project version as before, and its Activity Log shows a processing warning saying it was resumed after a failure. Resuming needs the transaction.resume permission, which administrators, designers and supervisors have.

In the app

A failed transaction shows a red Processing error mark in the viewer's header; point at it to see the cause and the error, click it to open the Activity Log at the failure. In the transaction list and the Work Queue, the cause follows the Failed status, for example Content refused or Step failed, and opens the Activity Log the same way. The cause is shown to administrators, designers and supervisors (the "See processing issues" permission). Next to it, Resume... opens the Resume dialog. The same dialog is the first item of the row's Re-run menu in the transaction list, Resume from step..., and a Resume... link on the failure's row of the Activity Log. They appear only for a failed transaction and only if you have the transaction.resume permission.

The dialog shows the step that failed and its error, then the steps you can resume at: the failed step (try again) and each step after it. For a later step it lists the steps that will be skipped, and says so in amber when that skips validation or review, since the data then goes on without those checks. At a review step you choose who reviews it: leave it in the review queue, review it yourself, or assign it to someone (in production only, and with the permission to assign). A comment is optional and goes to the Activity Log.

Cancel the transaction... in the same dialog drops it instead, with a reason.

The Activity Log records each resume (Resumed at Export, or Resumed: Extract run again) with the steps skipped and your comment.

Through the API

GET  /transactions/{transaction_id}/resume-options
POST /transactions/{transaction_id}/resume   {"activity_id": "...", "assign_to": "...", "comment": "..."}

resume-options lists the failed step and every step you can resume at, each with the steps it would skip. Without activity_id, resume runs the failed step again. assign_to assigns the review when the step is a review step; without it the transaction keeps the reviewer it was assigned, if any. If the failure came before the transaction had any documents (its files could not be imported), it can be resumed only at the failed step. The response's assigned_to says who the review was assigned to; assignment_error is review_assignment_failed when you asked for an assignment that could not be made; the transaction resumed all the same and waits in the review queue.

A failed transaction's GET /transactions/{transaction_id} says why it failed in failure_code, next to error_message: for example content_filter (the model provider's content filter refused a document), retries_exhausted (a step kept failing), worker_died (processing crashed) or review_rejected (a reviewer rejected it). Both are cleared when the transaction is resumed or re-run. A transaction that failed before this field existed has none.

When a rule or script you wrote stopped it, failure_source says which: kind (validation_rule, classification_rule, data_transform or workflow_condition), rule_id and rule_name for a rule, activity_id and activity_name for the step, case for a Switch case, and error_type (for example ReferenceError, or ForbiddenPattern for code that is not allowed to run). Its code is then validation_rule_error, classification_rule_error, transform_script_error or condition_script_error (failed_by_script when a Transform called fail()). Such a failure is not retried, since the same code fails the same way: fix the rule or script, then resume the transaction. It is cleared with failure_code, and null for any other failure.

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.

Assigning a transaction

On My Work Queue, Assign gives a production transaction to one person, if you have permission to assign. While it is assigned, only that person and those who see everyone's assignments (supervisors, for example) see it in the queue. Assign is offered until the transaction is finished: while it waits for review, while it is still processing, and when it has failed. It is not offered on completed or cancelled transactions.

• Waiting at a review step: you can assign only people who can review at that step.
• Not waiting at a review step: the step it will stop at next is not known, so anyone who can review in the project can be assigned. Assign to me on upload works the same way. If the transaction then stops at a review step that person cannot review, it stays assigned to them, so nobody else in the project gains sight of it, and it carries a processing warning. Someone with permission to assign then gives it to someone who can review there, or the assignee releases it to the queue.
• Failed: it can be given only to someone who can resume it, to look into the failure and decide what to do. They may resume it, or cancel it.

The Assistant assigns by the same rules. Every assignment, reassignment and release is in the transaction's Activity Log, with who made it, including an assignment made when the transaction was created and the release when a reviewer accepts or rejects it.

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.