This article explains the key concepts you should understand to work effectively with Ventoo Document Reader.
Building-block principle: no data entry screen of its own
Ventoo Document Reader is deliberately designed as a building block for other extensions, not as a standalone end-user feature. There's no list, no card, and no button that lets you manually read a QR-bill as a user. Instead, the app exposes a public codeunit procedure (TryExtractFromAttachment) that a dependent extension calls as soon as it processes a PDF attachment.
Note: If you install Ventoo Document Reader without such a dependent extension, you won't see any further visible functionality beyond the setup page after configuration. That's expected — the app's actual effect only plays out through the calling extension.
Data flow: from PDF to structured payment data
A call always follows the same sequence:
-
Input – A dependent extension passes a Business Central Document Attachment record (a PDF) to
TryExtractFromAttachment. -
Processing – Ventoo Document Reader securely passes the PDF to the Azure Function operated by Ventoo, which looks for an embedded Swiss QR code and decodes its content according to the Swiss Payments Code standard.
-
Return – The result is translated, on the Business Central side, into a temporary record of type QR-Bill Data (reference, creditor, debtor, amount, messages).
Important: The temporary record is declared by the calling extension itself and passed in as a parameter (Record "QR Bill Data VTO" temporary). Ventoo Document Reader itself stores nothing permanently apart from the setup.
Two-stage reference validation
The recognized payment reference is checked twice before it's considered valid:
|
Stage |
Where |
What is checked |
|---|---|---|
|
1 |
Azure Function |
Mod10r check digit of the reference (the standard validation method for Swiss QR references). |
|
2 |
Business Central |
Structural check: the reference must consist of exactly 27 numeric digits. |
Only if both stages succeed does the call count as a complete match.
Important – only QRR references currently count as a match: The 27-digit check in stage 2 is specific to the QRR reference type. References of type SCOR (alphanumeric, ISO 11649) and QR-bills without a reference (NON) never pass this check — even when the Azure Function correctly decoded the creditor, debtor, and amount data. In these cases, TryExtractFromAttachment currently returns false, even though a QR code was technically recognized. See Reference validation and error handling for more details.
"No match" is not an error
A PDF without a Swiss QR-bill is the expected, normal case, not an exceptional one. TryExtractFromAttachment simply returns false in the following cases, without raising an error:
-
Ventoo Document Reader is not enabled.
-
The function URL or function key is not configured.
-
The PDF attachment contains no recognizable QR code.
-
The Azure Function reports
"found": false. -
The recognized reference fails the 27-digit check (see above).
Only an actual transport or HTTP failure (function unreachable, timeout, status code outside the 2xx range) raises a genuine error.
Secure storage of the function key
The function key is stored encrypted and is never shown in plain text, exported, or included in a backup. On the setup page, the Function Key field shows dots once a value is stored; to change the key, simply overwrite it.
Timeouts and network errors
If the Azure Function doesn't respond within the configured Timeout (ms) period, or is unreachable, the call fails with an error that the calling extension can catch. There is no automatic retry — that's the responsibility of the calling extension.