Documents — Upload

Type: documents-upload  ·  Package: Documents Activities v1.4.5  ·  Output: object

Uploads a document —with its rendered pages and its extraction— to Zoan Cloud, so a person can open it in the validation station.

Almost never needed

IDP — Extract already stores the document and its extraction, and Zoan Cloud shows its pages on its own. This activity is for pipelines built by hand (with IDP — Ground) or cases where you render and upload the pages yourself.

Documents — Upload   path       = content["path"]
                     reference  = item.Reference
                     pages      = pages
                     dpi        = 200
                     extraction = res

How it works

1. Uploads the file at path with its reference and the metadata you give (type, project, layout, segment, retention).
2. Uploads each image in pages, in order, with its page number, its size (read from the PNG itself) and the dpi. The total page count travels with each page, so if they don’t all fit in the plan’s page quota, Zoan Cloud rejects from the first one and no document is left half uploaded.
3. If you passed extraction, stores it with the document and leaves it ready for review.

Uploading twice with the same reference replaces the document instead of duplicating it. Without pages, the document uploads but the log warns that the station will have nothing to show the fields on; without extraction, it warns that there is nothing to review. It needs the Zoan Cloud runtime context (a run from Zoan Cloud or from the Designer with a session).

Required parameters

Parameter	Type	Default	Description
path	string	—	Path to the document to upload: PDF, PNG, JPEG, TIFF or BMP. The same file you read with IDP.
reference	string	—	The document’s key. Use the same one as the queue item and you can get from the item to its document. Uploading again with the same reference replaces it.

Optional parameters

Parameter	Type	Default	Description
pages	List	—	The rendered pages, in order: what PDF To Images returned. They must be PNG. Without them the station has nothing to draw the boxes on.
dpi	int	200	The dpi the pages were rendered at. Range: 36 to 1200. It must match the dpi the document was read at: otherwise nothing fails, but the boxes land in the wrong place.
extraction	Dictionary	—	What IDP — Ground or IDP — Extract returned. Send the whole thing, not just values: the boxes let the station highlight each field and the confidences explain why it needs a look.
documentType	string	—	The document type the classifier decided. Lets the station filter by type.
project	string	—	The name of the extraction project it was extracted against. Links the document to its project so it can be listed and reviewed per project.
format	string	—	The layout profile IDP — Extract routed to (its format output).
sourceGroupId	string	—	Only when you split a bundle: the id shared by every document that came out of the same file (use the item’s reference). Lets the split file be shown as one group. Since 1.1.0.
pageStart	int	—	The first page (1-based) this document occupies in the original file. Comes from the segment. Since 1.1.0.
pageEnd	int	—	The last page (1-based, inclusive) this document occupies in the original file. Since 1.1.0.
retentionDays	int	—	How many days to keep the document (positive integer). Empty uses the environment’s default. Worth setting deliberately: you might keep a validated record for 90 days and a regulatory one for years, in the same batch.

The plan’s page quota

Every page stored counts toward your plan’s monthly page quota. The activity tells Zoan Cloud how many pages the document has, so if they don’t all fit in what is left of the quota it is rejected from the first one —with the figures— and no document is left half uploaded. Uploading a page that was already there again does not use quota. What you use shows up in AI Usage.

Output

Returns an object with:

Field	Type	What it is
id	string	The document’s id in Zoan Cloud.
reference	string	The reference it was uploaded with.
pageCount	int	How many pages were uploaded (0 if you passed no pages).

Example

A hand-built pipeline that renders the pages and uploads the grounding result:

IDP — Ground         document = doc   extraction = extraction   taxonomy = taxonomy
                     → output: res
PDF To Images        path = docPath   dpi = 200   outputDir = tempFolder   → output: pages
Documents — Upload   path         = docPath
                     reference    = item.Reference
                     pages        = pages
                     dpi          = 200
                     extraction   = res
                     documentType = res["documentType"]
                     → output: uploaded
Queue Set Transaction Status   item = item   status = "successful"
                               output = { "documentId": uploaded["id"] }

Common errors

Message	Cause and fix
'path' is required. / 'reference' is required.	A required parameter is missing.
File not found.	The path does not exist on the robot’s machine.
Cannot upload a '…' file: supported types are PDF, PNG, JPEG, TIFF and BMP.	Unsupported file format.
Page image N not found.	A path in pages is empty or does not exist.
A page image is not a PNG. Render the pages with PDF To Images, which produces PNG.	Pages must be PNG. Render them with PDF To Images.
'dpi' must be between 36 and 1200. Received: … / 'pageStart' must be a page number of 1 or more. Received: … / 'retentionDays' must be a positive integer. Received: …	Parameter out of range or not an integer.
This document needs N more pages and M are left in your plan's page quota this month, so its pages were not uploaded. Upload fewer pages or upgrade the plan.	The pages don’t fit in the quota left.
The document pages included in your plan for this month have been reached, so the pages were not uploaded. Upgrade the plan or wait for next month.	The month’s page quota is used up.
Document activities need a Zoan Cloud runtime context, which the Runner provides when it launches the playbook. Missing: …. …	The run has no Zoan Cloud (for example, from the command line). Run it from Zoan Cloud or from the Designer with a session.
Zoan Cloud rejected the upload (…): … / Zoan Cloud rejected the request (…): …	Zoan Cloud did not accept the file, a page or the extraction. The detail carries the code; retry.

Related activities

• IDP — Extract — extracts and stores; the normal path.
• IDP — Ground — what goes in extraction in a hand-built pipeline.
• PDF To Images — render the pages.