Documents
The Documents editor defines how NomaUBL turns a raw source XML spool — or an already-formed UBL invoice — into the persisted record on which the rest of the platform operates. NomaUBL is source-agnostic: the same configuration model works whether the spool comes from JD Edwards, SAP, NetSuite, a custom ERP, or any other system that can emit XML or UBL. (Only the Extract and BIP sync features are JD Edwards-specific.)
For every document type you tell NomaUBL three things:
- Where the data comes from — the
sourceselector picks between an XML spool that needs an XSL transform, a UBL 2.1 invoice that's already structured, and a SQL or REST connector that returns the data live without any file (Document tab). - How to transform each document into UBL and PDF (Processing tab).
- How fast to run the transformation (Advanced tab).
A fourth tab — PDF Template — is dedicated to the per-document PDF layout (which sections appear, in which order, with which columns and toggles).
Document templates used to live under Configuration → Documents. They were lifted to Management → Documents so the new four-tab editor — and especially the visual PDF Template tab — has a full-height home. The schema and the routes are unchanged: every existing template keeps working with no migration step.
At a glance
Load an XML sample (optional, recommended)
At the top of the editor click Load XML sample and pick a representative spool file from your source system. Once loaded, every XPath field shows a small ⌘ browser button — clicking it opens a side drawer that lists all tag paths found in the sample, so you can pick the right tag without typing it. The drawer supports filtering and shows the value of each path as a hint.
You can configure documents without loading a sample, but the picker makes it much faster to avoid typos.
Tab 1 — 📄 Document
This tab tells NomaUBL where to find each piece of data on every incoming document.
Source
| Field | Values | Description |
|---|---|---|
| Source | XML (default) / UBL / Connector | Picks the input pipeline. XML — an XML spool from any source system, transformed to UBL 2.1 by the XSL pipeline. UBL — files that are already UBL 2.1 invoices (your ERP emits UBL natively, or the file came from an upstream system in UBL form); no XSL transform runs. Connector — no file at all: NomaUBL calls a SQL query or a REST endpoint that returns the document, then runs the same XSL pipeline against the result. |
| Direction | Issued (default) / Received | What side of the transaction this template handles. Issued — invoices the operator emits to a customer. Received — invoices the operator gets from a supplier; the row's counterparty is the supplier party, the emit-only seller actions (Resend to PA, Send completed, Credit note…) are hidden in the detail modal, and the Invoices list shows the row under the Received filter chip. Set on the received-ubl bundled template by default. |
The Source choice flips the rest of this tab between three distinct sets of fields. The remaining sections of the page — Processing, Advanced, PDF Template — apply identically to all three sources. The Direction field is orthogonal: any combination of Source × Direction is valid, although Received is most often paired with UBL (PA-pushed supplier invoices).
The Direction value is written once on the row at insert time (column UHDRIN on F564231 — '1' for received, '2' for issued). Changing the template's Direction afterwards does not re-classify the rows that already exist — the Invoices list filter, notification rules and e-Reporting envelopes read the frozen value, not the live template setting. Pick the right Direction before processing the first invoice on a new template; flip it later only if you accept that historical rows stay on the previous side.
Key extraction from cbc:ID (when Source = UBL)
For UBL invoices the (doc, dct, kco) primary key — the same triplet that identifies the document everywhere else in NomaUBL — is parsed from the invoice's cbc:ID via a regex with named groups. There is no filename convention to follow; the file can be named anything.
| Field | Description |
|---|---|
| ID Pattern | Regex applied to cbc:ID. Allowed groups: doc, dct, kco. Any subset is allowed; missing groups fall back to the defaults below. |
| doc default | Used when the regex does not match or the doc group is missing. |
| dct default | Used when the dct group is missing. |
| kco default | Used when the kco group is missing — common when the cbc:ID does not include a company code. |
Sample cbc:ID + Suggest + Test helper
To avoid writing the regex by hand, the section includes a small inline assistant:
| Action | Effect |
|---|---|
| Sample cbc:ID | Paste a real ID from one of your invoices (e.g. 38706889RI00001 or F202600025). |
| Suggest | Generates an idPattern by splitting the sample on letter / digit transitions, fills in the matching defaults, and runs Test on the result. |
| Test | Runs the current idPattern + defaults against the sample and shows the extracted (doc, dct, kco) live — green when it matches, red on a regex error. |
Worked examples:
| Sample | Suggested idPattern | Defaults | Extracted |
|---|---|---|---|
F202600025 | ^(?<dct>[A-Z]+)(?<doc>\d+)$ | kcoDefault = 00001 | doc=202600025, dct=F, kco=00001 |
38706889RI00001 | ^(?<doc>\d+)(?<dct>[A-Z]+)(?<kco>\d+)$ | (none) | doc=38706889, dct=RI, kco=00001 |
Document number lookup (when Source = UBL)
On a Received template, the UBL's cbc:ID is the supplier's invoice number — not the operator's internal key. The default Suggest + Test regex-on-cbc:ID path then no longer makes sense: the operator needs to look the internal (doc, dct, kco) triplet up from supplier-side fields (UBL number, supplier name, supplier VAT, etc.).
A new Document number lookup group on the Document tab (visible only when Source = UBL) wires the lookup against a SQL connector or an API connector.
| Field | Description |
|---|---|
| Connector | The SQL or API connector that holds the lookup query / endpoint. |
| Target | The named query (SQL) or endpoint (API) on the selected connector. Parameters declared by the target become the placeholder set the lookup can supply. |
| Parameter values | Free text + placeholders mapped per target parameter. Supplier-side placeholders available out of the box: {ublNumber}, {supplierName}, {supplierVat}, {supplierAddress}, {issueDate}, {totalTtc}, {currency}. |
| Mapping | Which response fields hold the resolved doc, dct and kco. Defaults to the first row's columns of those names on a SQL connector; on an API connector pick the JSON keys with the same picker used elsewhere. |
When the group is filled in, the lookup runs before the regex-on-cbc:ID path and its result wins. Leave the group empty to keep the legacy behaviour — the regex assistant and the (doc, dct, kco) defaults below continue to apply unchanged.
The bundled received-ubl template ships with this group present but empty: pick the connector and the target in Settings → Document Templates, fill in the parameters, and the receive-side flow is wired end-to-end.
Connector source (when Source = Connector)
When Source is Connector, NomaUBL fetches the document data live from a SQL connector or an API connector instead of reading a file. The same XSLT pipeline then turns the result into UBL — no spool, no file watcher, no transient directory.
Two patterns are supported:
| Mode | When to use it |
|---|---|
| Single call | One query / endpoint returns the header and the nested line array in one shot. Best when the source can join the header with its lines server-side (typical for a SQL view or a REST endpoint built for invoicing). |
| Two calls | One call returns the header, a second one returns the lines. Useful when the line endpoint accepts the header keys as parameters ({customer}, {docNumber}…) — line parameters can reuse any value returned by the header call via {header.field} placeholders. |
Once a connector is wired, the rest of Tab 1 (Burst Key, Document Identification, Document Data, Date format) reads exactly like Source = XML — the XPath fields point at the XML shape produced by the connector response, not at a file on disk. Use Load connector sample in the XSL Editor to pull a real response so the XPath picker autocompletes against actual data.
Running a connector-sourced document is described on Processing → Process Document: the page replaces the file picker with the parameter form derived from the header connector. The same parameters are passed from the CLI via repeatable --param key=value arguments (see Command Line).
Bursting (Document Root) (when Source = XML)
| Field | Description |
|---|---|
| Burst Key | XML tag name used to split the spool into individual documents. This element marks the root of one document — every occurrence in the spool produces one output document. |
Document Identification (when Source = XML)
NomaUBL uses these five fields to know which document it is, who owns it, and what business type it belongs to. Each field accepts a default for cases where the tag is absent.
| Field | Maps to source-system concept |
|---|---|
| Activity | Business activity / module the document belongs to. |
| Type | Document type code as known in NomaUBL. |
| Document ID | Invoice number / document number. |
| Document Type (JDE) | Document type as defined in the source system (named after JD Edwards' RI/RM codes, but works with any source value). |
| Company (JDE) | Company / business unit owning the document in the source system (legacy field name, applies to any ERP). |
Document Data (XPath) (when Source = XML)
Functional data NomaUBL reads from the spool to populate the UBL invoice and to drive routing.
| Field | Description |
|---|---|
| Customer Number | Customer / address book number. |
| Amount | Document gross amount. |
| Document Date | Issue date of the document. |
| Due Date | Payment due date. |
| Routing Code | Code used to route the document to the correct delivery channel: archive, email, postal mail, dispatch to a Plateforme Agréée, etc. |
| Office | XML tag in the spool that contains the office / business unit code. |
| Processing Type | XML tag carrying the processing-type code (B2B, B2BINT…). Leave empty to fall back to the default defined in Document Types. |
💡 Each Document Data field has its own default value. Defaults are used when the XML tag is missing or empty, which is useful when a value is constant for a given template.
Date format (when Source = XML, 2026.05.9)
| Field | Default | Description |
|---|---|---|
dateInputFormat | yyyy-MM-dd (ISO) | Java SimpleDateFormat pattern used to parse document and due dates extracted from the source XML before they are written to F564230 / F564231. The previous version hardcoded ISO; that worked on UBL sources (the XSL emits ISO) but silently failed on XML sources where the spool format is locale-dependent (dd/MM/yyyy for many French ERPs, MM/dd/yyyy for North-American spools, etc.). |
Pick the pattern that matches the source dates literally. Common values:
| Source date sample | Pattern |
|---|---|
2026-05-12 | yyyy-MM-dd (default — ISO) |
12/05/2026 | dd/MM/yyyy |
12.05.2026 | dd.MM.yyyy |
05/12/2026 | MM/dd/yyyy |
20260512 | yyyyMMdd |
The pattern applies only when the document's Source is XML. UBL sources keep emitting ISO through the XSL, so the field is ignored there. The default keeps existing UBL flows back-compat without any edit.
Tab 2 — 🔧 Processing
This tab controls what NomaUBL does with the data extracted in Tab 1. It applies to both XML and UBL sources, although several fields (XSL, RTF) are only meaningful on the XML pipeline.
XSL Transformation
| Field | Values | Description |
|---|---|---|
| Transform | Y / N | Whether to apply an XSL transformation pipeline before generating UBL. |
| XSL Pre-processing | path | Optional XSL applied before indexation, e.g. to normalise the raw source XML (JD Edwards, SAP, NetSuite, custom ERP…). |
| XSL Indexation | path | XSL used to generate the indexation / metadata applied to the document. Produces an XML file paired with the generated PDF for indexing purposes. |
| RTF Template | path | RTF template used by BI Publisher to render the human-readable PDF. |
UBL
| Field | Values | Description |
|---|---|---|
| UBL XSLT | path | XSL transform from the source XML to UBL 2.1. The placeholder %APP_HOME% is expanded to the NomaUBL install root. |
| Attachment | — None / create / attach | How to associate the human-readable PDF with the UBL: create = generate the PDF and embed it in the UBL file; attach = use a PDF already present in the input directory; empty = no PDF embedded. |
Output
| Field | Description |
|---|---|
| No-Data Key | Name of an XML element that must exist in the spool. If absent, NomaUBL considers the document empty and skips it. Useful to filter out spool sections that aren't real invoices. |
| Set Locale | Locale used to render the PDF (e.g. en_US, fr_FR). Affects date and number formatting in the PDF only. |
Tab 3 — ⚙️ Advanced
| Field | Description |
|---|---|
| Number of CPUs | Number of parallel threads used by the processing pipeline for this document type. Increase to speed up large spools, decrease if the host is under memory pressure. Default: 4. |
Tab 4 — 🖼 PDF Template
The fourth tab picks the PDF layout applied when this document is rendered. Since 2026.05.1, layouts are first-class shareable resources stored in config-pdf.json and edited on the dedicated PDF Templates page — this tab simply references one of them by name via the template's pdfTemplate property.
| Field | Description |
|---|---|
| PDF Template | Dropdown listing every saved layout (the pdf-template resources from PDF Templates), plus the bundled built-in. Leave empty to fall back to the global default (global.defaultPdfTemplate); empty + no global default falls back to built-in. |
The resolution chain at render time is therefore: this field → global.defaultPdfTemplate → built-in. Every persisted invoice carries the document template name in F564231.UHTMPL, so the PDF generator re-renders on demand against the layout that was active for that document.
The visual editor — section list, per-section drawer, live preview, block sections — lives on Management → PDF Templates. Open it once to author or tune a layout, then come back here to point the document at it. A single layout can serve many documents.
Tips & best practices
- Always set defaults on Document Identification fields — they save you from spool variations that omit a tag occasionally.
- For UBL sources, use Suggest to bootstrap the regex — it handles the common patterns (digits-only, letters + digits, digits + letters + digits). Tweak by hand only when the format is unusual.
- Leave Processing Type empty unless this template needs to override the per-document-type default; this keeps the configuration DRY.
- For new document types, start by loading an XML sample, configure Tab 1 using the picker, then test on a few documents before tuning the XSL chain in Tab 2.
- The Burst Key is the most critical XML field — getting it wrong produces either one giant document or no documents at all.
- Edit the PDF layout on its own page. PDF Templates hosts the visual editor with the live preview; this tab just picks the right one. Sharing one layout across several documents avoids editing N copies when a legal mention or a column set changes.