Skip to main content

Custom Lists

A Custom List is an operator-defined reference list — a code → labelFr / labelEn table managed outside the regulated catalogs in Reference Lists. Its job is to power a grid: assign a custom list to a column in the List Views editor and the column gets a dropdown filter, a multi-select picker in Advanced Filters, and a code — label cell renderer — all automatically, without any code change.

Each list can be edited row by row, refreshed from the NomaUBL tables (the codes actually found in the processed documents), or synced from a connector (API or SQL) when the source of truth lives in an external system. Same query / endpoint can power several lists by feeding different parameters per list.

The custom lists have their own area in the Settings navigation, Custom data, right after Reference data (which keeps the shipped lists). Like most Settings editors, the editor is in English only.

At a glance​

Custom Lists+ New list💾 SaveLISTbusiness-units ▾id used by list-views to reference this listRowsCODE · LABEL FR · LABEL EN · ⌫PARParisParis×LYOLyonLyon×MRSMarseilleMarseille×+ Add rowSync source (optional)CONNECTORerp-master · SQL ▾QUERYlistBusinessUnits ▾CODEMCULABEL FRDESCRIPTION_FRLABEL ENDESCRIPTION_ENPARAMScompany=00070; activeOnly=Y↻ Sync now✓ Synced 47 row(s) from erp-master · listBusinessUnitsList idreferenced by list-viewscode → FR / ENpicker rows + cell labelsManual rowsedit row by rowSync from connectorAPI or SQLreplaces the rows in placeSame query, many listsper-list params

List selector​

The page lists every custom list defined on the platform. Pick one to edit; + New list above the row table creates a new entry seeded with an empty row.

FieldDescription
ListDropdown of every custom list (name). The name is the identifier that the List Views editor references — picking a list here is editing it, picking the same name in a column spec under List Views binds the column to it.
+ New listCreates a new list. A Name prompt asks for the identifier; that name is what column specs will reference.
SaveWrites the active list. Switching to another list before saving discards unsaved edits.

Rows​

The row table is the canonical content of the list. One row per entry, three columns.

ColumnDescription
CodeThe stored value — what the column cell holds in the grid (e.g. PAR, MCU0070, 01).
Label FRFrench label rendered next to the code in the picker and in the cell (code — label). Required.
Label ENEnglish label rendered when the active locale starts with English. Optional — when empty, the FR label is reused.
⌫Removes the row.

+ Add row at the bottom appends a new empty row. Rows are sorted alphabetically by code in dropdowns and pickers; the editor preserves the order in which rows were added so the operator can reorder them by hand.

Sync source​

A custom list can be backed by an external system instead of being edited by hand. The Sync source (optional) group sits below the row table. Pick an API connector or a SQL connector, pick an endpoint / query, then map the response fields to the list's three columns.

FieldDescription
ConnectorNomaUBL database (@nomaubl, see below), then every api-connector and sql-connector template defined on the platform. Picking one limits the next field to that connector's targets.
Endpoint / QueryDropdown of the connector's endpoints (API) or queries (SQL). Disabled until a connector is picked.
Code fieldColumn name (SQL) or JSON key (API) the sync reads as each row's code. Required.
Label FR fieldColumn / key for the French label. Required.
Label EN fieldColumn / key for the English label. Optional.
List path (API only)Dotted path to the array inside the JSON body. Supports data.items and items[0] segments. Empty when the body is already a JSON array.
ParametersPer-list key / value pairs sent to the connector as fixed values (no placeholder substitution). The same query can power several lists by saving different values per list; defaults from the endpoint definition apply when a field is left blank.
Sync nowCalls the connector, walks the response, builds the row set, and replaces the rows in place. A translated banner reports Synced N row(s) from connector · endpoint on success, or the underlying error on failure.

From the NomaUBL database​

With the NomaUBL database connector, the list is filled with the values found in the NomaUBL tables. The endpoint picks the column:

EndpointValues
Activity code (F564230)Activity codes of the processed documents.
Sub-type (F564230)Document sub-types.
Document type (F564230)Document types (dct).
Company (F564230)Companies (kco).
Business unit (F564230)Business units.
Send to PA flag (F564230)Send-to-PA flags.
Validation level (F564236)Severity levels of the validation findings.

No field mapping is needed. Sync now only adds the codes the list lacks and keeps every existing code and its labels; the banner reads N new code(s) added, M kept. The labels of the new codes are then filled in by hand.

The sync config lives on the same list template under sync.connector, sync.endpoint, sync.codeField, sync.labelFrField, sync.labelEnField, sync.listPath and sync.params. List consumers (cell renderer, Advanced Filters dropdown, per-column filter row) never see those keys as entries — they are filtered out of parseRefOptions.

A Sync now does not auto-save; it only rebuilds the row table. Click Save to persist the synced rows.

Ready-made lists​

NomaUBL ships custom lists that the default List Views use for their value-list columns:

ListContent
list-activiteActivity codes, refreshed from the NomaUBL database.
list-sub-typeDocument sub-types, refreshed from the NomaUBL database.
list-companiesCompanies, synced from the getCompanies query of the shipped jde-sql connector.
list-send-paDestination of the invoice: 1 For the platform, 2 Not for the platform, 3 Held for review before sending.
list-levelSeverity levels: Fatal, Error, Warning, Information.
list-validation-sourcesSources of the validation findings: XSD schema, EN 16931, CIUS-FR, extended CTC FR, Chorus Pro, NomaUBL rules, and the technical steps (UBL, XML, PDF, XSL transformation, validation, PA, database, processing).
list-fluxE-reporting direction: 1 Inbound (purchases), 2 Outbound (sales).
list-reviewReview flag: Y Reviewed, N Waiting.

A built-in validation-rules list is also available to the list views: the rules of the Schematron catalog, so that a rule column shows its description next to its code.

Using a custom list in a grid​

A custom list is wired to a grid through the List Views editor. On the column row, set the refList field to the list's name:

{
  "name": "logBusinessUnit",
  "label": "Business unit",
  "labelFr": "Unité d'activité",
  "type": "string",
  "refList": "business-units",
  "width": 150,
  "visible": true,
  "filter": true
}

Effects on the grid:

  • Cell renderer — instead of the raw code, each cell shows code — label (FR or EN depending on the locale). Empty values stay blank.
  • Per-column filter row — the text input is replaced by a searchable dropdown populated from the list's rows. Each entry is code — label.
  • Advanced Filters multi-select picker — the list seeds the multi-select picker. Picking several entries issues an IN (?,?,?) clause on the server.

No code change is needed — adding a row to the list, syncing it from a connector, or renaming a label refreshes the grid on the next render.

REST endpoints​

The list editor and the grid consumers share the same back-end:

MethodPathPurpose
GET/api/ref-listsReturns every defined list with its rows. The grid loads this once per session and caches the result; the editor invalidates the cache on save.
GET/api/ref-lists/{name}Returns one list with its rows + the sync config when present.
PUT/api/ref-lists/{name}Writes the list. Body: { name, rows: [...], sync: {...} or null }.
POST/api/ref-lists/{name}/syncTriggers the sync. Returns the rebuilt row set on success, the underlying connector error on failure.

Tips & best practices​

  • Pick a stable name. The list's name is what column specs reference under refList. Renaming a list later breaks every column spec that points to it — better to delete and recreate under the new name once the column specs have been updated.
  • Keep the FR label populated. The cell renderer falls back to the FR label when the active locale is FR; an empty FR label surfaces the raw code in the grid, which is rarely what an operator wants.
  • One connector query, many lists. When several lists share the same back-end query (e.g. active business units for company 00070 vs. active business units for company 00080), save the query once on a SQL or API connector and feed different Parameters per list. The endpoint defaults fill in the rest.
  • A connector sync replaces, the NomaUBL source adds. With an API or SQL connector, a Sync now removes every existing row before inserting the new ones, so manual edits made between two syncs are lost. With the NomaUBL database, the sync only adds the new codes and keeps the labels typed by hand.
  • Hidden columns can still be filtered. A column bound to a custom list can be marked visible: false in the spec and still surface in Advanced Filters — useful for technical fields like logBusinessUnit that operators want to filter on but not display.