Promotion

The Promotion page moves configuration from one instance to another — development to test, test to production — item by item, with the files each item uses. Export builds a package; import shows what the package would change, field by field, then writes it after a version snapshot. The keys that belong to an instance — passwords, URLs, hosts, the license, the environment name… — never travel and are never overwritten on the target.

Open it from Management → Promotion. The page has three views: Export (build a package, or promote the selection straight to another instance), Import (apply a package) and History.

---

At a glance

---

What can be promoted

Kind	Content of the item	Travels with it
Document template	A document.	Its files — pre-processing XSL, indexation XSL, RTF, UBL XSLT and its PDF companion (.pdf.json), custom Schematron — and the PDF template it names.
PDF template	A PDF template.	—
Entry form	An entry form of the invoice editor.	— (role grants stay with each environment's roles)
List	A reference list or a custom list.	—
Notification rule	A notification rule.	—
Explorer analysis · Explorer dashboard	A saved Explorer analysis or dashboard.	A dashboard brings the analyses of its tiles.
Daily digest · Auto-retry · Lifecycle check	A daily digest, an auto-retry or a lifecycle check.	—
Connector	An API, SQL, database or FTP connector, without its secrets and targets.	—
Settings template	E-invoicing, e-reporting, directory lookup, watched folders, integrity checks, report queries or JDE print queue, without its instance keys.	—
File	The shared UBL defaults file (ubl-defaults.xsl, the operator values of the common XSL), and each file a document uses — transform, XSL, RTF, UBL stylesheet, customer Schematron, PDF layout — listed by its path with Used by … the documents that use it. A file can be promoted alone, for example a stylesheet shared by several documents.	—

The global settings, single sign-on and the column overrides of the NomaUBL database are never promoted: they describe the instance itself.

---

Export

1. Pick the items in the tree, grouped by kind with their count. The kind check box selects every visible item of the kind; Filter items… narrows the tree.
2. Read the dependencies shown under each item: the files it uses and the items added with it. A PDF template named by a selected document is ticked automatically and flagged dependency.
3. Export package downloads the ZIP. The side panel counts the items, dependencies and files of the selection; Clear selection starts again.

Package content

Entry	Content
manifest.json	The items with their kind and checksum, the source instance and release, the author and the date.
items/	One JSON fragment per item.
files/	The referenced files, with their path relative to the environment root — the %APP_HOME% and %ENV% placeholders of the properties stay valid on the target.

What never travels

Passwords, secrets, tokens, API keys, the license, URLs, hosts, users, the database schema, the environment name and colour, and the watermarks of the jobs (last BIP job, last scan, last retrieval) are never exported. On import, the target keeps its own values for these keys.

---

Import

From DEV · release 10.24.1 · admin · 2026-10-24 09:15

Kind	Item	State	Changes	Detail	Applied
Document template	invoices	changed	3
PDF template	standard	identical	0
File	xsl/invoices.xsl	new	0

Preview
Items: 0 new, 1 changed, 1 identical, 0 skipped
Files: 1 new, 0 changed, 0 identical, 0 skipped
Changed items and files
Replace with the package ▾
Comment for the snapshots and the log
✓ Apply

1. Choose a promotion package (.zip). The page reads the manifest — source environment, release, author, date — and computes the preview without writing anything.
2. Read the preview. Each item and each file has a state: new, changed, identical or skipped. The grid gives the number of changed fields per item; a row opens the field diff — key, change (set, added, changed, removed), Target value and Package value.
3. Choose the policy for changed items and files:
   • Replace with the package — changed items and files take the package version;
   • Keep the target, write only new ones — only new items and files are written.
4. Add a comment, recorded with the snapshots and in the log.
5. Apply and confirm. The panel switches to Result, the Applied column marks what was written, and Choose another package clears the page.

What Apply writes:

• each item is inserted or updated by name in its own configuration file;
• each file is written after a version snapshot, visible and restorable in File versions;
• the instance keys already present on the target keep their value;
• the import is one entry of the versioning log, with its author and comment.

The grid is the shared data table; its view is listed in the List views editor.

---

Promote to another instance

When the two instances can reach each other, the selection of the Export view is sent straight to a target instance, without handling a ZIP file. The package is built as for an export, sent to the target's own preview, then to its import.

1. Pick the items in the Export view (with their dependencies).
2. Under Promote to an instance, at the bottom of the Export side panel, choose the Target instance (the last one used is remembered) and click Promote….
3. The Promote to … window shows the target's own preview — new, changed, identical, skipped, with the field diffs. Nothing is written yet: Promote checks the selection on the target first and shows what would change there; nothing is written until you confirm.
4. In the same window, choose the policy for Changed items and files — Replace with the package or Keep the target, write only new ones — and a comment, then click Promote n item(s) and n file(s). The target takes a version snapshot before each write, and its instance keys keep their values. The window then reads Promoted to …: n item(s) and n file(s) written.

The ZIP export stays for instances that cannot reach each other.

Target instances

The targets are defined once in Settings → Promotion targets (Platform area); while none is defined, the Settings header offers Add promotion targets. Each target has:

Field	Description
Name	Shown in the target list of the Promotion page.
URL	Root of the target instance, with its path prefix when it has one (e.g. https://test.example/nomaubl).
Username / Password	Account on the target, which must hold the Settings access feature there; leave blank when the target runs without sign-in. The password is stored encoded and decoded on the server only for the call.

The account is never sent to the browser and never travels in a package. This editor is in English in the application.

---

History

The History view lists every package exported, import applied and promotion applied on the instance, newest first:

Column	Description
When	Date and time.
Direction	Export, Import or Promoted.
Counterpart	The target of a promotion, the source of an import.
Author	Who ran it.
Policy	replace or keep.
Items / Files	Counts.
Comment	The comment entered.

A row opens the entry with its full plan and diffs. A source instance keeps its promotions, a target its imports. Each entry is a JSON file under the environment's promotions folder.

---

Access

Grant Promotion in the Management group on the Roles page. The settings grant is also required.

The Package mode of File versions remains available for raw files that belong to no item.

---

Tips & best practices

• Promote from the lower environment up. Edit in development, check in test, then import the same package in production: the package is the record of what was moved.
• Read the diff before applying. A changed item with an unexpected key often reveals an edit made directly on the target.
• Use Keep the target to add without overwriting — for example to bring a new document to an instance whose existing documents have been tuned locally.
• Write a meaningful comment. It is the label of the snapshots to restore if the import has to be undone.