IDP — Load Document

IDP — Load Document

Type: idp-load-document  ·  Package: IDP Activities v1.20.4  ·  Output: object

Loads a document and returns its text and every word with its position on the page. If the PDF has a text layer it reads it directly; if not, it scans it with Azure Document Intelligence. Both routes return the same structure.

It is the entry point of the document pipeline: what comes out of here feeds AI — Extract or IDP — Ground. IDP — Classify and IDP — Extract use it internally.

How it works

In auto mode (the default):

• It is an image (.jpg, .jpeg, .png, .bmp, .tif, .tiff, .heif) → it goes straight to scanning.
• It is a PDF with text (average characters per page ≥ minCharsPerPage) → it reads the text layer. Exact, it never leaves the machine and it costs nothing.
• It is a PDF without text → it sends it to Azure Document Intelligence (the prebuilt-layout model).

The decision goes to the log, with the average characters per page it measured and the threshold, so you can see why it chose what it chose. When it finishes, the log says how many pages and words it read and from which source; if it recognised no words, it leaves a warning.

With the reading included in your plan, each attempt waits up to 10 minutes and transient failures are retried up to 3 times.

Required parameters

Parameter	Type	Default	Description
path	string	—	Path to the document: a PDF or an image (.jpg, .jpeg, .png, .bmp, .tif, .tiff, .heif). Images always go through scanning.

Optional parameters

Parameter	Type	Default	Description
mode	string	"auto"	How to read it: auto (text layer, and scan only if there isn’t one), text (text layer only, never calls the cloud) or azure-di (always scan).
pages	string	"all"	Pages to read: "all" or a range such as "1-3,5,7-9".
endpoint	string	—	URL of your own Azure Document Intelligence resource (https://<name>.cognitiveservices.azure.com). Empty, together with credential, uses the reading included in your plan.
credential	credential	—	Key of your Azure resource (goes with endpoint). Both empty, the reading included in your Zoan Cloud plan.
dpi	int	200	Resolution the coordinates are expressed in. Range: 36 to 1200. Use the same one in PDF To Images and the boxes land on top of the pages.
minCharsPerPage	int	16	In auto mode, a PDF averaging fewer characters per page is treated as scanned. Cannot be negative.

No endpoint or credential: the reading included in your plan

endpoint and credential are optional (since 1.20.0):

• Empty: if your Zoan Cloud plan includes IDP, scans are read with Zoan’s Azure Document Intelligence through Zoan Cloud. You don’t create an Azure resource or store keys; the pages show up in AI Usage and count toward your plan’s page quota.
• With your Azure resource: the document goes straight from the robot to your resource. Zoan Cloud only records how many pages were read, and they don’t count against the plan’s quota.
• Only one of the two: the activity fails with a clear message, so it never charges the plan for something you meant to pay for separately.

A PDF with a text layer is still read on the machine, without leaving it and without using anything.

Limits of the included reading

Limit	Value
File size	Up to 50 MB
Pages per reading	Up to 2000; a longer document is read in parts with pages
Pages per month	Your plan’s page quota

Documents near the page limit

Before reading with the included reading, Zoan Cloud counts the pages of the document (or of the pages range). If they don’t fit in what is left of the month’s quota —or in what the remaining AI usage covers— the activity fails right away with the figures and nothing is read: you don’t pay for a reading that is no use to you.

• Without pages, the message talks about the document: “The document has 12 pages and 5 are left in your plan’s quota this month”.
• With pages, it talks about the requested range: “The reading asks for 8 pages and 5 are left in your plan’s quota this month”.

You never get a partial reading presented as complete. If the page count cannot be known in advance and the reading fills what was left of the quota (or hits the 2000-page maximum), the result is not delivered and the activity fails with a clear error (the pages read still count toward usage). To read a long document with little quota left, split it with pages or use your own Azure resource.

Output

Returns an object with this shape:

Field	Type	What it is
path	string	The path that was loaded.
source	string	Which route it came in by: text or azure-di.
dpi	int	The dpi the coordinates are in.
pageCount	int	Number of pages read.
text	string	The whole document text, with each line numbered ([12] ...). It is what gets passed to the model, and what lets it cite which line each value came from.
lines	List	One entry per line: index, page, x, y, width, height, text. It is what IDP — Ground uses to read the box of the line the model cited.
markdown	string	The original text without numbering — the service’s markdown on the scan route, or the rebuilt text on the text-layer route.
pages	List	One entry per page: page, width, height, text.
words	List	One entry per word: text, page, x, y, width, height, confidence.

A document with no recognisable text returns the same structure with empty words and lines (and a warning in the log); it does not fail.

source is not there for the playbook to branch on, but to be able to explain a bad result: text-layer confidence and OCR confidence do not mean the same thing.

Why the text is numbered

Each line starts with its number ([12] Issue date: | 15/01/2024). It is not decoration: for each field the model returns the line it took the value from, and IDP — Ground reads the box straight from that line. That is what makes a repeated value —three identical dates— each land in its own place. The scan route’s table markdown is still available in markdown.

Checkboxes: scan route only

A checkbox (☑/☐) is a graphic mark, not text: the text-layer route does not see it. The azure-di route does detect selection marks with their state and confidence, and they are injected into the text as ☑ (checked) or ☐ (empty), in place and as a locatable token. So a boolean field —“Urgent delivery?”— is extracted from the real state of the box, not guessed from the surrounding text.

That is why a document with checkboxes has to be read with mode = azure-di (or auto if it is a scan). A digital PDF with checkboxes needs azure-di forced: through the text layer the checkboxes are lost.

Text-layer confidence is always 1

In a digital PDF the character is the one the PDF generator wrote: there is no recognition and no uncertainty. Only the azure-di route returns real per-word confidences.

The coordinates

Every word comes out in pixels at the dpi you ask for, with a top-left origin, wherever the document came from. If you render the same page with PDF To Images at the same dpi, the boxes land exactly on top:

IDP — Load Document   path = docPath   dpi = 200   → output: doc
PDF To Images         path = docPath   dpi = 200   outputDir = folder   → output: images

Example

Load an invoice with the reading included in the plan and extract its fields:

IDP — Load Document   path = invoicePath
                      dpi  = 200
                      → output: doc
Log                   message = "Read via " + doc["source"] + ": " + doc["pageCount"] + " pages"
AI — Extract          prompt = doc["text"]
                      schema = {…}
                      → output: invoice

Read only the first three pages of a long scan with your own Azure resource:

IDP — Load Document   path       = scanPath
                      mode       = azure-di
                      pages      = "1-3"
                      endpoint   = "https://my-resource.cognitiveservices.azure.com"
                      credential = credential("azure-di-key")
                      → output: doc

Walk the words (to highlight, measure or locate a value):

Foreach   items = doc["words"]   itemVariable = word
  Log   message = word["text"] + " at x=" + toString(word["x"])

Chained indexing does not work

doc["words"][0]["text"] fails: the engine does not chain indexers on an untyped value. Walk the list with Foreach, which does type the element.

The autodetection threshold

The default is 16 characters per page, and it means “the text layer is practically empty” — because the sign of a scan is that it has no text, not that it has little. The margin covers scanners that stamp a watermark or a footer as real text.

A generous threshold (100 or more) sends to the cloud any short digital document —a cover page, a one-line record, a certificate— that would be read for free and perfectly through the text layer.

Raise it only if your scans arrive with a text layer of their own that you don’t trust (for example, a poor earlier OCR pass).

Common errors

Message	Cause and fix
File not found.	The path does not exist on the robot’s machine.
'mode' must be one of: auto, text, azure-di. Received: …	Invalid mode value.
'dpi' must be between 36 and 1200. Received: … / 'minCharsPerPage' cannot be negative. Received: …	Parameter out of range (or not an integer).
Invalid page range '…'. Use "all", a page number, or a range such as "1-3,5,7-9". / Invalid page range '…': the start page is higher than the end page.	pages is badly written.
Page(s) out of range: …. The document has N pages.	On the text-layer route, pages asks for pages the PDF does not have.
To scan a document, set the endpoint and credential of your Azure Document Intelligence resource, or run with Zoan Cloud to use the document reading included in your plan (in the Designer, sign in to Zoan Cloud).	The document is a scan, there is no Azure resource and the run has no Zoan Cloud (e.g. a test without a session). Sign in, configure your resource, or use mode = text if the document has a text layer.
'endpoint' is required to scan with your own Azure Document Intelligence resource. … / 'credential' is required to scan with your own Azure Document Intelligence resource. …	You set only one of the two: fill in the other, or leave both empty to use the included reading.
'endpoint' must be the full URL of the Azure Document Intelligence resource, such as https://<name>.cognitiveservices.azure.com. Received: …	The endpoint is not an absolute URL.
The credential does not contain an Azure Document Intelligence API key. Store the key as the credential's value in Zoan Cloud.	The credential exists but is empty or holds something else.
Your Zoan Cloud plan does not include document reading. …	No own resource and your plan does not include IDP. Configure your Azure resource or turn on the included reading.
The document has N pages and M are left in your plan's quota this month. Nothing was read, so you do not get an incomplete result. Read fewer pages ('pages'), use your own Azure Document Intelligence resource or upgrade the plan.	The document does not fit in the page quota left this month.
The reading asks for N pages and M are left in your plan's quota this month. Nothing was read, …	The pages range does not fit in the quota left. Ask for fewer pages.
The document has N pages and the AI usage left in your plan this month covers M. Nothing was read, … / The reading asks for N pages and the AI usage left in your plan this month covers M. Nothing was read, …	What is left of the included AI usage does not cover reading all those pages.
The reading reached N pages, the ones left in your plan's quota this month, and the document may have more. The result would be incomplete, so it was not delivered. … / The reading reached N pages, what the AI usage left in your plan this month covers, and the document may have more. …	The page count could not be known in advance and the reading filled the quota or the remaining usage: the result is not delivered because it would be incomplete.
The document has N pages and one reading takes up to 2000. Read it in parts with 'pages'. / The reading asks for N pages and one reading takes up to 2000. Read it in parts with 'pages'. / The reading reached N pages, the maximum of one reading, and the document may have more. … / The document is too long for one reading (up to 2000 pages). Read it in parts with 'pages'.	More than 2000 pages in one reading. Read it in chunks with pages (for example, in a loop over "1-2000", "2001-4000"…).
The document pages included in your plan for this month have been reached. Use your own Azure Document Intelligence resource or upgrade the plan.	The month’s page quota is used up. With your Azure resource the robot keeps going.
The request is too large for the AI included in your plan (… 50 MB per document). …	The file is over 50 MB. Split it or use your Azure resource.
The AI provider did not answer in time through Zoan Cloud. … / Could not reach Zoan Cloud: …	Transient failure after 3 retries. Wrap the activity in a Retry.
The text layer is empty. If this document is a scan, use mode 'auto' or 'azure-di'. (warning)	You asked for mode = text on a scan. It does not fail, but there are no words.

Related activities

• AI — Extract — extract fields from the loaded document.
• IDP — Extract — load, extract, locate and store in one activity.
• PDF To Images — render the pages to draw the boxes on top.
• OCR — local route, no cloud.