IDP Load Document

IDP Load Document

Type: idp-load-document  ·  Package: IDP Activities v1.18.0  ·  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 it does not, it scans it with Azure Document Intelligence. Both routes return the same structure.

This is the entry point of the document pipeline: what comes out of here feeds AI Extract.

How it works

In auto mode (the default) it measures the PDF’s text layer:

• Has text → reads it from the text layer. Exact, and free.
• Has no text (or is an image) → sends it to Azure Document Intelligence.

The decision goes to the log, along with the average characters per page it measured and the threshold, so you can see why it chose what it chose.

Required parameters

Parameter	Editor	Description
path	expression	Path to the document: a PDF or an image (.jpg, .png, .tif, .bmp).

Optional parameters

Parameter	Editor	Description
mode	enum	auto (default), text (text layer only, never calls the cloud) or azure-di (always scan).
pages	expression	Pages to read: "all" (default) or a range such as "1-3,5,7-9".
endpoint	expression	URL of the Azure Document Intelligence resource. Required unless mode is text.
credential	credential	Zoan Cloud credential holding the Azure API key. Required unless mode is text.
dpi	expression	Resolution the coordinates are expressed in. Default 200.
minCharsPerPage	expression	Autodetection threshold. Default 16.

Output

Returns an object shaped like this:

Field	Type	What it is
path	string	The path that was loaded.
source	string	Which route it took: text or azure-di.
dpi	int	The dpi the coordinates are in.
pageCount	int	Number of pages read.
text	string	All the document’s text, with every line numbered ([12] ...). This is what’s 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. This 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 reconstructed text on the text-layer route. In case you want it without line numbers.
pages	List	One entry per page: page, width, height, text.
words	List	One entry per word: text, page, x, y, width, height, confidence.

source is not there for the playbook to branch on — it is there to explain a bad result: a confidence from the text layer and one from OCR do not mean the same thing.

Why the text is numbered

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

Checkboxes: scan route only

A checkbox (☑/☐) is a graphic mark, not text: the text-layer route doesn’t see it. The azure-di route does detect selection marks with their state and confidence, and they’re injected into the text as ☑ (ticked) or ☐ (empty), at their position and as a locatable token. So a boolean field — “Requires calibration?” — is extracted from the checkbox’s real state, not guessed from the surrounding text.

That’s why a document with checkboxes must be read with mode = azure-di (or auto if it’s 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’s generator wrote: there is no recognition and no uncertainty. Only the azure-di route returns real per-word confidences.

The coordinates

Every word comes back in pixels at the dpi you ask for, with a top-left origin, whichever route the document took. Render the same page with PDF To Images at the same dpi and 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 equipment record and extract its fields:

IDP Load Document   path       = = docPath
                    mode       = auto
                    endpoint   = = "https://my-resource.cognitiveservices.azure.com"
                    credential = = credential("azure-di-key")
                    dpi        = 200
                    → output: doc
Log                 message = = "read via " + doc["source"]
AI Extract          credential = = credential("anthropic-key")
                    prompt     = = doc["text"]
                    schema     = {…}
                    → output: equipment

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 item.

The autodetection threshold

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

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

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

Common errors

Message	What happened
'endpoint' is required to scan a document	The document was detected as scanned but no Azure resource is configured. Configure it, or use mode = text if the document does have a text layer.
The credential does not contain an Azure Document Intelligence API key	The credential exists but is empty or holds something else.
the text layer is empty (warning)	You asked for mode = text on a scan. Use auto or azure-di.

Related activities

• AI Extract — extract fields from the loaded document.
• PDF To Images — render the pages to draw the boxes on top.
• OCR — on-prem route for clients without cloud.