Roles
This screen manages NomaUBL's role-based access control. Each role bundles four kinds of grant:
- A list of pages the role can reach.
- A per-action whitelist of operations the role is allowed to perform (Edit, Delete, Resend, Push status…).
- A data scope — the companies the role is restricted to and optional row filters that narrow the visible rows by column value.
- The members assigned to the role.
Roles are application-wide and source-agnostic — they apply equally whether NomaUBL is plugged into JD Edwards, SAP, NetSuite or a custom ERP. Default roles (admin, viewer) are seeded by the Initialize Database action in Database Connectors → NomaUBL.
Opening the editor
- Sidebar → Configuration → Security → Roles.
- The page opens with every existing role as a card. Click any card to expand the edit panel below the list. Use + New Role at the top right to start from scratch — the same edit panel opens with the Name field unlocked.
At a glance
Roles list
The top of the page lists every existing role as a card.
| Element | Description |
|---|---|
| Name | Internal identifier of the role (e.g. admin, operator, customer_acme). Used to bind users to the role from the Users editor. |
| Description | Free-text human-readable summary. |
| Member count | Number of users currently assigned to the role. |
| Badge | Admin when the role has the Settings access feature, User otherwise. Quick read of the role's reach. |
| ⎘ Copy | Duplicates the role: pre-fills the edit panel with all grants of the source role; the Name field is empty for the operator to choose a new one; the description gets (copy) appended. |
| 🗑 Delete | Removes the role after confirmation. Users assigned to it lose every permission until reassigned. |
Click any card to open the Edit panel below the list. Use + New Role at the top right to create a role from scratch.
Identity (always visible)
The role's Name (visible only when creating) and Description sit above the tab bar, so the operator never has to switch tabs to relabel a role.
| Field | Description |
|---|---|
| Name | Internal identifier of the role. Must be unique. Locked once created. |
| Description | Human-readable summary shown in the role list. |
Tab — Access
Defines what the role can reach: features and pages.
Features
A short list of binary feature flags. Each row carries a checkbox plus a one-line helper that explains what the flag does.
| Feature | Helper text | Effect |
|---|---|---|
| Settings access | Can open the Settings page (template / connector editing). | Opens the entire Configuration menu. The role is then displayed with the Admin badge in the list. |
| Read-only mode | No edit / delete / resend actions, even on permitted pages. | Members can browse the application but every write action is disabled — overrides the Actions tab entirely. |
Allowed Pages
The pages are laid out as one card per group of the side menu — same groups, same order, same names: Navigation, Sync, Processing, UBL, Extract, Management, Documentation. Each page is a chip carrying its menu label; a ticked chip shows a check mark, and hovering it shows the page id. The card header gives the number of pages granted (3/10) and an all / none link that flips the whole group.
| Group | Pages (id) |
|---|---|
| Navigation | Billing overview (synthese), Operations (dashboard), Statistics (statistics), IT dashboard (techdashboard), E-Invoicing (invoices), E-Documents (edocuments), E-Reporting (ereporting), E-Directory (edirectory), VAT declaration (vatdeclaration), Reports (reports), Explorer (explorer), Notifications (notifications), then Diagnostics and its four views: Integration errors (integrationerrors), Processing log (processinglog), Failures (errors), Server log (serverlog). |
| Sync | Fetch Input (fetchinput), Fetch Import (import), Fetch Statuses (retrievestatuses), Scheduled Jobs (scheduledjobs). |
| Processing | Process Document (process), Extract & Process (extractandprocess), Process API (processapi). |
| UBL | UBL Validation (validate), XSL Editor (xsleditor), XML Viewer (xmlviewer), UBL Defaults (ubldefaults). |
| Extract | Extract from Archive (extract), Extract FTP (extractftp), Extract from BIP (extractbip, JD Edwards-specific). |
| Management | Documents (documents), PDF Templates (pdftemplates), Actions (actions), Notification Rules (notificationrules), Watched Folders (watchfolders), File Versions (fileversions), Promotion (promotion). |
| Documentation | Release Notes (releasenotes), Upgrade History (upgradehistory), Status Reference (statusreference), Reason Codes (reasoncodes), UBL Reference (ublreference), Business Rules (businessrules, which also opens Schematrons), Developer (xref), API Reference (apireference). |
A few chips carry a hint:
- Diagnostics is one page with four views: each view is a grant of its own, and the menu shows Diagnostics as soon as one of them is granted. See Diagnostics.
- Scheduled Jobs covers every job — polls, batch jobs, daily digests, auto-retries, lifecycle checks, retention. Running, pausing or saving a job also requires the Run batch jobs action (
integration.run). See Scheduled jobs. - Watched Folders grants the configuration of the folders; their schedule is on Scheduled Jobs.
- Promotion also requires the Settings access feature. See Promotion.
- Developer opens the Developer reference: tables, configuration keys, flows, impact, API.
- Billing overview and Statistics are pages of their own, checked by the server and by the tools of the AI assistant. The upgrade gives both, once, to every role that had Operations, so nobody loses a page; removing them from a role afterwards is kept.
- Business Rules also opens Schematrons.
- After sign-in, the user opens on the start page of the instance when the role grants it, else on the Billing overview, else on the first page the role grants.
Rules:
- All / None above the cards grant or revoke every page at once.
- Empty list = all pages allowed. Same convention as the other lists: an unfiltered role sees everything.
- The
adminrole created at initialisation receives every page id listed above, including VAT declaration, Reports and Upgrade History.
Tab — Actions
Defines what the role can do on the pages it can reach.
Restrict toggle
| Toggle | Effect |
|---|---|
| Off (default) | Empty whitelist on the server — the role can perform every action allowed by its pages. |
| On | Only the actions checked below are allowed. Switching on pre-fills the list with every action so the role does not suddenly lose access — uncheck from there. |
The helper text under the toggle states Off (default) = role can perform every action allowed by its pages. On = only the checked actions below are allowed.
The section header above the toggle reflects the current state:
(every action is allowed — no whitelist set)when the toggle is off.(N actions explicitly allowed — everything else is blocked)when the toggle is on and N actions are checked.(0 actions allowed — same effect as Read-only)when the whitelist is on but empty.(Read-only mode is on under Access — every action is blocked)when the Read-only feature is on — the whole tab is greyed out.
Check all / Uncheck all buttons appear under the toggle (disabled when the whitelist is off).
Action catalog
Grouped by the page where the button lives — the same key can power buttons on more than one page.
| Group | Action | Key | Effect |
|---|---|---|---|
| Invoices | Create | invoice.create | The New Invoice button of the E-Invoicing list. |
| Invoices | Edit | invoice.edit | Update invoice fields from the detail modal / edit panel. |
| Invoices | Mark reviewed | invoice.review | Mark invoices in error as reviewed by customer service, or clear the mark — invoice list and window. The upgrade gives it to the roles that have Edit or Push status (DB). |
| Invoices | Delete | invoice.delete | Hard-delete an invoice and all its child records. |
| Invoices | Delete lifecycle event | invoice.lifecycle-delete | Remove a single status event from an invoice history; the header realigns on the last remaining event. |
| Invoices | Resend to PA | invoice.resend | Submit / re-submit an invoice (or a bulk batch) to the PA. |
| Invoices | Push status (PA) | invoice.status.pa | Send a status event through the PA — payment received, in dispute, etc. (the Set Status modal's PA tab). |
| Invoices | Push status (DB) | invoice.status.db | Directly update a status in the database, bypassing the PA — admin break-fix path used when the PA round-trip is broken. |
| Invoices | Validate UBL | invoice.validate | Run XSD + Schematron validation against the stored UBL XML (Validate button in the History tab). |
| Invoices | Download UBL | invoice.download | Read the raw UBL XML BLOB — the Download UBL button and the underlying /xml endpoint. |
| Invoices | Preset actions | invoice.preset-action | Use the per-status preset buttons (Resend on 9904, …) in the seller actions row. |
| Invoices | Custom actions | invoice.custom-action | Use the admin-defined custom buttons in the custom actions row. |
| Invoices | Email PDF | invoice.email | Send the rendered PDF via the configured SMTP relay. |
| Lists | Share views | listview.share | Share one's saved views with every user. Saving private views needs no grant. |
| E-Reporting | Generate batch | ereporting.generate | Build a new e-reporting batch from the Generate dialog. |
| E-Reporting | Resend batch | ereporting.resend | Re-submit an existing e-reporting batch to the PA. |
| Integration ops | Run batch jobs | integration.run | Trigger Import statuses / Fetch received / Retrieve statuses from the toolbar. |
The detail modal renders Parties, Invoice Lines, TVA recap and Notes from the UBL XML endpoint, which is read-open (still subject to row filters and page visibility). Only the explicit Download UBL button is gated by invoice.download — view-only roles can therefore inspect the invoice content without the right to extract the raw XML.
Invoice entry forms
Below the action cards, when at least one entry form exists: Invoice entry forms (none ticked = the complete editor). Tick Complete and the forms the role may use; with two or more, Opens on picks the form the invoice editor opens on. A role without any form keeps the complete editor.
Tab — Data scope
Defines which rows the role can see — companies and optional row filters.
Companies
An add-row table of company codes (KCO) the role is scoped to. Each row carries a free-form input and a × button to remove it; + Add company at the bottom appends a new row.
- Empty list = all companies. This is the typical default — leaving the table empty grants the role access to every company in the database.
- Adding even one row restricts the role to just the listed companies.
- The placeholder hint reads KCO code (e.g. 00001) and the input uses a monospace font to make typos easier to spot.
Row filters
A more granular restriction: on a field, the role can be restricted to one or more exact values. Typical use case — an external customer who should only see invoices issued to its own alpha key (UHALKY).
The column picker lists each field once, by scope:
| Group | Fields | Secures |
|---|---|---|
| Keys — every table (doc, dct, kco) | Document number, Document type, Company. | Every table that has these keys. |
| Document (F564230) — every linked table | The fields of the archived document: activity code, business unit, sub-type, source file, job, program, routing… | Every table linked to the document. |
| Invoice (F564231) | The invoice header: customer alpha key, customer name, contract… | That table. |
| Validation findings (F564236) | Severity, source, rule… | That table. |
| Processing log / E-reporting | Their own columns. | That table. |
Each entry reads label · FIELD (— select column — until one is picked). For the picked field, enter one or more values (Value (exact match)); + Add value (OR) appends another value, Remove value and Remove filter drop a value or the whole filter. + Add row filter combines filters on different fields.
Combination rules
| Pattern | Combined as |
|---|---|
| Multiple values on the same field | OR — the role sees rows that match any of the values. |
| Multiple fields in the filter list | AND — the role sees only rows that match every constraint. |
| Companies grant + row filters | AND — both must be satisfied. |
Where row filters apply
A row filter is not a UI hint — it is enforced everywhere a forbidden row could otherwise leak:
- Every list that has the field, under the name that list gives it (customer, activity code, job, UBL number, status…). A list without the field ignores the filter: a role restricted to the
FATALseverity keeps its invoices, documents and dashboards and sees only the fatal findings. - The dashboards — Billing overview, Operations, Statistics, status counts — and the E-Documents window, which opens under the same rules as its list.
- Per-row endpoints — lifecycle, lines, XML download, PDF render, status push, delete, resend, email PDF.
- The rendered PDF byte stream — a forbidden row cannot even be turned into a PDF.
Forbidden rows return the same "not found" shape the UI uses for genuinely missing data, so the response cannot be used to probe for invoices a role should not know exist.
Tab — Members
Available only when editing an existing role (hidden during creation).
Lists every user currently bound to the role:
| Column | Description |
|---|---|
| Username | The user's login. |
| Full name | The user's display name (or – when not set). |
| Status | Active (green) or Inactive (red). |
This view is read-only — to add or remove a user from a role, edit the user from Configuration → Security → Users.
Save / Cancel
- Create (when creating) / Save (when editing) persists the role and refreshes the list — available on every tab except Members.
- Cancel discards changes and closes the panel.
- Inline status messages appear below the panel (
Role created,Role updated,Role deleted, error messages).
How grants are stored
Every grant is one row in F564254. The shape:
F564254
PMROLE — role name (FK to F564251.RLNAME)
PMCRAPPID — grant type: 'page' / 'company' / 'feature' / 'action'
/ 'row-filter'
PMCRAPPVAL — grant value, encoded per type:
page → page id (e.g. 'invoices')
company → KCO code (e.g. '00001')
feature → flag ('settings', 'readonly', 'actions-whitelist')
action → action key (e.g. 'invoice.delete')
row-filter → 'column=value' (e.g. 'UHALKY=123456')
PMENABL — '1' enabled / '0' disabled (used during dialect-specific bootstrapping)
Row-filter grants are persisted as flat column=value strings — one row per (column, value) pair. The editor groups them by column on load and re-flattens them on save, so the operator never sees the raw shape.
Adding a future permission dimension becomes an INSERT in this same table — no DDL change required.
The bootstrap is idempotent: dropping F564254 and re-running Initialize Database re-seeds the default admin and viewer grants without touching role rows. The init log reports the count of newly-inserted grants for visibility.
Delete a role
Clicking the 🗑 icon on a role card opens a confirmation modal:
Delete role "X"? Users assigned to this role will lose their permissions.
Confirming removes the role and every grant row in F564254 keyed by it. Users previously bound to the role keep their account but lose every permission until they are reassigned to another role.
Tips & best practices
- Create one role per profile, not per individual.
operator,auditor,customer_<name>are simpler to maintain than per-user roles. - Grant Settings access sparingly. It opens the entire Configuration menu — limit it to a small admin group.
- Pair Read-only with Actions off for compliance / audit accounts — both layers reinforce each other.
- Use the Companies table to enforce multi-tenant isolation. Leaving it empty defeats company-level filtering for the role.
- Row filters first, action whitelist second when scoping an external user. The row filter hides everything the user should not see; the action whitelist controls what they can do with what they see.
- A role sees the Operations dashboard as a whole or not at all. To keep a team on business figures only, grant the Billing overview and Statistics without Operations.
- Use Copy when forking a role. Starting from an existing role with one or two grants flipped is faster than rebuilding the checklists from scratch — and the result is closer to the source role's intent.
- Re-run Initialize Database (Database Connectors → NomaUBL) if the default
adminorviewergrants are missing — it re-seeds the rows without touching custom roles. - Delete a role only after re-binding its members. Once deleted, members lose access to everything until reassigned. The Members tab is the fastest way to check who would be affected.