Overview

Metadata lifecycle

The metadata lifecycle keeps the history of everything that makes up a WUIC app (routes, menus, permissions, translations, dashboards, workflows, reports...), lets you compare two versions, create releases, export them to a .wuicpkg package and promote them from one environment to another (dev → test → prod) with a dry-run plan, application in a transaction, verification and rollback. The APIs are under api/meta-lifecycle/* (dedicated controller, superadmin only, checked against the DB); the page is Administration → App lifecycle (route meta-lifecycle). The administrator created by the first-run wizard is a superadmin (Admin role): on a new installation it can use the lifecycle right away.

When to use it (use cases)

  • Know who changed what: every save from the designers and from the metadata CRUD leaves a version with author and date.
  • Compare a route, a dashboard or a workflow with a previous version and restore it.
  • Promote the changes made in development to test and production with a single file, without hand-written SQL scripts.
  • Protect production: blocked design changes (design lock), dual approval, signed packages.
  • Automate the release in a CI/CD pipeline with the scripts/wuic-meta.ps1 CLI.

Concepts

  • Artifact: the unit of versioning and promotion. A route bundles into a single JSON the _metadati__tabelle row, the columns, styles, actions, conditions and nested grid links. The other types: route-grants, menu, translations (per namespace, the first two segments of the key), theme, scheduler-job, mailing-template, webhook-event, webhook-endpoint, dashboard, pivot, workflow, report, scene3d, scene3d-asset, routing, bi-universe.
  • Canonical form: DBMS-neutral JSON, sorted keys, csProperty property names, local ids (md_id, mc_id, mm_id, role ids) replaced by symbolic references ({"$ref":"route","key":"clienti"}, roles by name), environment values replaced by bindings (${conn:...}, ${secret:...}), derived data removed.
  • uid: stable identity of the artifact (UUID v5 from type + natural key), the same in every environment. The identity map (_wuic_meta_identity) of each environment links the uid to the local id.
  • Hash: SHA-256 of the canonical form = version of the artifact. Two environments with the same hash have the same content; comparing environments costs a hash comparison.

What is versioned and what is not

ClassExamplesHandling
APProutes, menus, role permissions, app translations, themes, jobs, dashboards, pivots, workflows, reportshistory, comparison, packages
DERIVEDworkflow transitions and SLAs, wf_sla_tick::* and PivotDynamicRefresh_* jobs, scene bindingsnot copied: regenerated in the target
ENVIRONMENTusers, Aziende, connection strings, webhook and scheduler URLs and secrets, mailing recipientsnever in the package: becomes a binding
RUNTIMElogs, workflow instances, notifications, scheduler runs, chatexcluded
SYSTEMrows with md_is_system_metadata / issystemroute, md_id < 1001, system menus, framework translation keysframework baseline: never enters packages

Per-user permissions and action-bound permissions are exported with a warning (role permissions are promoted by role name).

History and comparison

  • Every metadata save leaves a signal in _wuic_meta_dirty (with the author, read from the DB for the session user); the builtin job meta_history_job (every minute) exports the flagged artifacts and records a version only if the hash has changed. Once a day the reconciliation also records changes made outside the APIs (direct SQL); the first run creates the baseline commit.
  • History tab: artifacts with their latest version, versions of an artifact, explicit commit with message and tag.
  • Compare tab: two sides (a version or the current live state) in the Monaco DiffEditor, with the list of differences per property. Designer noise (x/y positions of workflow nodes, tag/inputProps of dashboards) does not show up as a change.
  • History / Compare button in the designers: workflow designer (menu), dashboard designer (toolbar), pivot builder, theme builder and metadata editor (Metadata menu). Workflows and dashboards also have the visual diff (canvas with nodes and links colored by status; dashboards side by side, read-only).
  • Restore this version: 3-way import plan whose base is the following version (the one being undone): if the item changed again afterwards on the same properties the plan shows the conflict and you choose (keep mine, take the source or per-property merge), as in a promotion. Without following versions the restore is direct.
  • Undo this recording (only on the latest applied recording with items; empty ones do not count): the items it touched go back to the previous version with a 3-way plan, and the apply saves a rollback recording. Intermediate recordings cannot be undone (shelve them), the baseline can be neither undone nor shelved. An empty recording (0 items) is highlighted with the "empty" tag and only has Remove, which takes it out of the history without changing anything (not the baseline, nor a recording referenced by a release or a shelving).
  • Undo on an item of the "Recorded items" grid (also of an intermediate recording): only if the recorded version is still the current one of the item (applied or reapplied) and it is not the baseline; brings just that item back to the previous version (removed if it was new, recreated if it was deleted), 3-way plan and rollback recording.
  • Shelve (version row and Compare tab) brings the item back to the previous version (removes it if it was new, recreates it if it was a deletion); Shelve the recording does the same for all its items with a single plan. The shelved version stays in the list, highlighted, with status shelved. Reapply (on the version or the recording) puts it back with the 3-way plan: if the item changed in the meantime the plan shows the conflict. Status column of versions and recordings: applied, shelved, reapplied, superseded (a later version exists); Shelved only filter. Shelvings are per environment and visible to all superadmins; releases and packages export the current state (a shelving that was not reapplied is not there).
  • Items with no rows: every route has its route-grants item even when it has no permissions of its own; in the tables (History list, differences of a recording, plan, release) the row stays but is dimmed, with the no permissions label (the tooltip explains it); the Hide without permissions filter removes it from the History lists.
  • Restores, shelvings and reapplies go through the plan in the Packages tab; Apply asks for confirmation with the recording message (proposed, editable: "restore of the recording of ...", "shelving of version ...", "reapplying of ..."). The apply saves a recording of kind restore, shelve or reapply; rolling back the promotion also undoes the shelving or the reapply.
  • Live history: while the page is open, every recording with items (automatic job, manual, import, reconcile, restore, shelving) arrives as one meta-history-commit message on the /ws/notifications channel, only to the tenant's superadmins, without bell or notifications. The touched rows update (versions, date, new and removed items) and stay highlighted until you pick the row; sorting, filters and selection are kept; if the selected item is among the touched ones its versions are reloaded. An empty recording sends nothing.
APIUse
GET history/artifacts?type=&q=artifacts with their latest version
GET history/{type}/{uid}versions of an artifact
GET history/versions/{id}canonical form of a version
GET history/compare?type=&uid=&left=&right=two sides (version id or live) and differences
GET history/visual?type=&uid=&left=&right=sides of the visual diff (workflow, dashboard)
POST history/versions/{id}/restore-planrestore plan for a version
POST history/commitexplicit commit { "message": "...", "tag": "..." }
GET history/commits/{id}/itemsitems saved by a recording (version, previous one, new/changed/deleted, status): the page shows them when you click the recording, "Differences with the current state" shows what changed since then
POST history/commits/{id}/restore-plan[?versionId=]plan undoing the latest recording, or just one of its items with versionId (409 not_latest_version; not_latest_commit, baseline_protected)
DELETE history/commits/{id}removes an empty recording (409 commit_not_empty, commit_in_use, baseline_protected)
POST history/versions/{id}/shelve-planplan shelving a version
POST history/commits/{id}/shelve-planplan shelving all items of a recording
POST history/shelves/{id}/reapply-planplan reapplying a shelving
POST history/commits/{id}/reapply-planplan reapplying the shelved items of a recording
POST promotions/{id}/apply { "planHash": "...", "message": "..." }apply; message = recording message (plans from History)

Snapshot

Logical picture of the definition tables of the metadata DB, with consistency check and differential restore. Every apply creates one (before-import) as a restore point. Snapshots are managed only through the API (table below): the "App lifecycle" page has no Snapshot tab.

APIUse
GET snapshots / POST snapshotslist / create { "label": "..." }
POST snapshots/{id}/verifyis the current state consistent with the snapshot?
POST snapshots/{id}/restorerestore (first creates a before-restore snapshot) and verify

Releases

A release is a named picture of the app state: the frozen uid → hash manifest of every artifact (_wuic_meta_release_item), with the changelog (new, changed, removed, excluded artifacts; authors and dates).

  • New release (Releases tab): preview of the changes since the last release, checkbox exclusions (an excluded artifact keeps the hash of the previous release: half-done work is not promoted), tag and message.
  • Release comparison and diff of an artifact between two releases.
  • Export: full package of the release or delta against a previous release.
APIUse
GET releases / POST releaseslist / create { "tag": "1.4.0", "message": "...", "exclude": ["route/<uid>"] }
GET releases/previewwhat would go into the next release
GET releases/{tag}manifest and changelog
GET releases/{tag}/diff?against=<tag>comparison between two releases (&type=&uid= for one artifact)
POST releases/{tag}/exportpackage; { "deltaFrom": "<tag>" } for the delta

Packages

The .wuicpkg package is a ZIP with manifest.json (SHA-256 of every file, source environment, frameworkMin, release notes), the artifacts in canonical form and the files (.mrt reports without connections, CSS, 3D assets).

TypeContentUse
fullall the app artifacts (current state or a release)standard promotion: works on any target state
deltaonly the artifacts changed between two releasesapplicable only to a target exactly at the base release, without prune
singleonly the version to restore"Restore this version"

Signature: with MetaLifecycle:SigningKey the export signs the manifest.json (RSA-PSS SHA-256, signature.json in the package). On upload the signature is trusted (key in MetaLifecycle:TrustedPackageKeys), untrusted, unsigned, invalid (always rejected) or local (package generated by the server itself).

Export from the page: in the background and by type

On the "App lifecycle" page Export (Packages) and Export / Export delta (Releases) do not wait for the file: the server builds it in the background with the user and tenant of the request and answers at once ("Export started"); you can leave the page. When it is done a notification arrives in the bell ("Export ready", or the error if it failed) that opens the tab it started from and downloads the file; while the page is open the export list shows the status and a Download button. The file is kept in Tmp_export with a random name and deleted after tmpExportRetentionHours (default 24 h), like grid exports; unlike those it can be downloaded only from the page and only by the user who asked for it (403 for anyone else, superadmins included).

Next to Export you choose the types to put in the package (default all = complete package; "All" / "None"); the file name lists them when they are not all (app-menu+route-grants-<date>.wuicpkg). Without the route type the page warns you: items that point to a route look it up by name in the target installation and, if it is missing, the plan stops with an error naming the missing route. Prune touches only the types in the package.

APIUse
POST packages/export-jobsstarts the package export ({ "types": [...] }, empty = everything) → job
POST releases/{tag}/export-jobsstarts the release export ({ "deltaFrom": "<tag>" } for the delta)
GET packages/export-jobs, GET packages/export-jobs/{id}the user's exports / status (running, done, failed)
GET packages/export-jobs/{id}/downloadthe ready file (404 expired, 403 another user, 409 not ready)

The synchronous exports (POST packages/export, POST releases/{tag}/export) stay for the CLI and pipelines.

Import: plan, conflicts, apply, verification, rollback

1. Upload the package (POST packages/upload, binary or multipart body): integrity, limits, zip-slip, signature.

2. Plan (always a dry run, POST promotions/plan): for each artifact it compares three hashes, base (the target release known to the source), source (package) and target (current state):

CaseOutcome
source = targetskip
changed only in the sourceupdate
changed only in the target (hotfix)keep with a warning
changed on both sidesautomatic per-property merge; where the two sides differ, conflict
missing in the targetcreate
only in the targetdelete only with prune
no release in commonevery difference is a conflict to confirm

3. Conflicts (Packages tab, conflict view): per artifact or per property you pick source or target (POST promotions/{id}/resolve, or resolveAll = source/target in the plan); every choice recomputes the plan and its hash. With open conflicts the apply is rejected (409 errors.meta_lifecycle.conflicts_unresolved).

4. Apply (POST promotions/{id}/apply with { "planHash": "..." }): before-import snapshot, one transaction on the metadata DB, staged files, regeneration of derived data, identity realignment, cache invalidation, import commit in the history and registration of the release in the target. A plan that changed in the meantime is rejected (409 errors.meta_lifecycle.plan_outdated).

5. Verification: re-export of the imported artifacts and hash comparison; any difference marks the promotion failed.

Automatic return: if the apply fails (an error halfway or a failed verification) the metadata go back by themselves to the before-import snapshot and the touched files to their previous content; then the state is checked again. Outcome: result.status = failed with result.autoRollback (rolledBack, metadataCongruent, filesRestored, filesNotRestored, dataPhaseKept, errors = original errors, error = why the return failed); the promotion becomes rolled_back with the auto-rollback event in the audit. An error halfway answers 409 errors.meta_lifecycle.apply_failed (everything undone), apply_failed_data_kept (undone, but the data DB stays), apply_failed_not_rolled_back (the return failed too: the promotion stays failed and is undone with the rollback of step 6) or apply_failed_auto_rollback_off. The data DB phase (created tables and columns, _wuic_data_migration log) is never undone: the outcome and the promotion log say so. For diagnosis MetaLifecycle:Apply:AutoRollback=false leaves the writes in place (default: automatic).

6. Rollback (POST promotions/{id}/rollback): restores the before-import snapshot and the files, checks consistency and cancels the release registration.

Other APIs: POST packages/export ({ "types": [...] }, empty = everything), POST packages/{id}/diff, GET promotions, GET promotions/{id} (plan and audit), GET promotions/{id}/artifacts/{type}/{uid} (base, source, target and merge).

Environments, design lock, approvals, signature

Snippet 1JSON
{
  "MetaLifecycle": {
    "Environment": { "Name": "prod-eu", "Role": "prod" },
    "DesignLock": "warn",
    "RequireSecondApprover": "",
    "RequireSignature": "",
    "SigningKey": "C:\\secrets\\wuic-dev-signing.pem",
  • Environment:Role (dev, test, prod, other): the configuration wins over the _wuic_meta_env registry in the DB.
  • DesignLock: off, warn (banner in the designers), on (423 errors.meta_lifecycle.design_locked on design saves: designer AsmxProxy, CRUD on the definition tables, report designer); empty = warn in prod, off elsewhere. With on, only lifecycle apply and rollback change the metadata. GET design-lock (any authenticated user) feeds the banners.
  • RequireSecondApprover: whoever planned (or resolved the conflicts) cannot apply; empty = active only in prod.
  • RequireSignature: unsigned packages or packages with an untrusted key are rejected (403); empty = active only in prod.
  • SigningKey (PEM or path, never in the package), SigningKeyPassword, SigningKeyId (default: key fingerprint), TrustedPackageKeys:<id> (trusted public keys). RSA key of at least 2048 bits.
  • GET environment returns role, design lock, dual approval, required signature and key ids.
  • Audit: every plan, resolution, apply (rejected ones too) and rollback in _wuic_meta_promotion with user, IP, hash and package signature.

CLI for pipelines

scripts/wuic-meta.ps1 (PowerShell 7) calls the same APIs with a personal token with the `meta-lifecycle` scope, created from the "API Token" dialog by a superadministrator (the token is valid only on /api/meta-lifecycle/*, it cannot read OData; the owner must remain superadmin).

Snippet 2PowerShell
$env:WUIC_META_URL = 'https://dev.example.com'; $env:WUIC_META_TOKEN = '<token di dev>'
pwsh -File scripts/wuic-meta.ps1 release-create --tag 1.4.0 --message "sprint 12"
pwsh -File scripts/wuic-meta.ps1 export --tag 1.4.0 --out release-1.4.0.wuicpkg
$env:WUIC_META_URL = 'https://prod.example.com'; $env:WUIC_META_TOKEN = '<token di chi pianifica>'
pwsh -File scripts/wuic-meta.ps1 plan --package release-1.4.0.wuicpkg --json > plan.json
pwsh -File scripts/wuic-meta.ps1 apply --promotion <id> --plan-hash <hash>

Commands: status, export, releases, release-create, diff, plan, resolve, apply, rollback. Exit codes: 0 ok, 2 open conflicts, 3 rejected (401/403/409/423, plan with errors), 1 error.

Multi-tenant

With multi-tenant enabled each company has its own metadata DB: identity map, history, releases, packages and promotions are per tenant (tables in the tenant DB). A promotion can target a list of tenants:

  • GET tenants: primary (scope 0) + companies with their own metadata DB and a connection present in the configuration (companies mapped to MetaDataSQLConnection are the primary).
  • POST promotions/tenants/plan { "packageId": "...", "tenants": [0, 1, 2], "stopOnFirstError": true }: plan per tenant in sequence; the package is re-uploaded into each tenant (signature verified with its own rules) after bringing its metadata DB up to the primary's migrations. Each tenant has its own promotion and its own plan hash.
  • POST promotions/tenants/apply and POST promotions/tenants/rollback { "items": [{ "tenantId": 1, "promotionId": "...", "planHash": "..." }], "stopOnFirstError": true }.
  • The summary reports per tenant the status (planned, applied, rolled_back, failed, skipped), counts per action and typed error; with "stop on first error" the following tenants remain skipped.
  • ?tenant=<id> on GET promotions, GET promotions/{id}, resolve, artifacts, apply and rollback acts on a single tenant; an unconfigured tenant returns 404 errors.meta_lifecycle.tenant_unknown.
  • In the Packages tab, with more than one tenant, the tenant selection appears together with "Stop on first error".

History retention

The builtin job meta_history_retention_job (every 60 minutes, per tenant) deletes intermediate versions older than MetaLifecycle:History:KeepDays days (default 180; 0 = unlimited retention) while always keeping the latest MetaLifecycle:History:MinVersions of each artifact (default 10). It never deletes: versions of tagged commits or of a release, versions referenced by a release manifest, binary files (3D assets), manual snapshots, the restore point of a promotion not yet superseded by a later apply. Automatic snapshots (before-import, before-restore, before-framework-upgrade) beyond the retention period are deleted.

The versions of a shelving that was not reapplied (the shelved version and the one the item went back to) are never deleted.

System rows and framework updates

SYSTEM rows (routes, columns, styles, actions, conditions, permissions and menus that the framework ships with the first-run scripts) never enter packages: the framework itself updates them. Each version embeds its system baseline in the DLL (framework-system-baseline.json.gz, one section per DBMS, key = primary key: system ids are fixed and app rows reference them by number). At every startup, after the migrations and the translations, and for every tenant metadata DB, the framework runs a row-by-row 3-way comparison between the base recorded in the DB (_wuic_meta_system_baseline, the framework row of the last realignment), the new framework row and the current row:

CaseWhat happens
current = frameworknothing; the base becomes the framework row
current = base, framework changedthe row is updated (changed columns only)
framework = base, current changedcustomization: left untouched
both changed on different columnsonly the columns changed by the framework are taken
both changed on the same columnconflict: that column stays as it is, the others are updated
missing row, never recordedinserted with its key
row recorded and then deletedstays deleted
row removed from the frameworknever deleted, only reported
id taken by another (app) row, or row already present with another idleft untouched, reported

On the first realignment (no recorded base, e.g. the first time after updating to this version) nothing is overwritten: only missing rows are inserted and differences are left for review. Writes run in one transaction preceded by a before-framework-upgrade snapshot (restorable with POST snapshots/{id}/restore); the history records the effects on app artifacts with a framework-upgrade commit by the author framework, never by a user.

The Changed from the framework tab of the page lists the rows to review (customized, in conflict, without base, deleted, removed from the framework, with a taken id) with base / framework / current per column and an explicit choice: Keep mine, Take the framework or Apply the merge (column by column). The choice is recorded: the row comes back to the list only if the framework or the row change. API: GET system-baseline, POST system-baseline/resolve { "table", "key", "choice": "keep|framework|merged", "columns": { "col": "mine|framework" } }, POST system-baseline/run (on-demand run), all with ?tenant=.

The startup realignment is controlled by MetaLifecycle:SystemBaseline:Mode: apply (default), report (log report only, no writes), off.

With multi-tenant, at startup only the tenants already brought to the lifecycle migrations are realigned (migrations at startup run on the primary only); the others at first use: POST system-baseline/run?tenant=<id> migrates and realigns them, and so does the first startup after a per-tenant plan.

Available updates

The Updates tab of the page (read only) shows the installed and the available version of the framework and, when the content root has the wuic-app.json manifest of a free app, of the app too, with the link to the release notes and what to do: for a binary installation the manual instructions (download the zip, "Upgrade" section of the notes), for an installation from sources the command to run in the repository (pwsh scripts/wuic-app-upgrade.ps1 -To <versione> for a free app, update of WuicCore on NuGet and wuic-framework-lib on npm for your own app). Nothing is applied from the browser. With a binary free app the new framework only comes with a new release of the app; if the new version of the app needs a more recent framework (frameworkMin) the tab says so.

What it checks and what it sends: the server reads the Updates:FeedUrl feed (default https://wuic-framework.com/downloads/releases.json) a few minutes after startup and then every 24 hours, with a single GET without custom headers, cookies or identifiers of the installation; the comparison happens on the server. Feed unreachable or invalid: one line in the log, no error to the user. For every new version the superadmins get one notification in the bell (state in App_Data/update-check.json). Updates:Check=false turns the check off (no request); Updates:TimeoutSeconds (default 10) and Updates:InitialDelayMinutes (default 3) set the timings. API (superadmin only): GET updates (last result), POST updates/check (check now).

Limitations

  • 4 DBMSs: history, releases, packages, plan, apply and rollback are verified on SQL Server, MySQL, PostgreSQL and Oracle by the parity tests (MetaLifecycleParity*).
  • Same DBMS: promotion between different DBMSs is not supported (free SQL in the metadata is not translated).
  • Data DB: structure, migrations and reference data of existing apps are not covered; the package carries only tables, reference data and demo data of apps created by the generator.
  • File-only transport (.wuicpkg + CLI): no direct push between environments.
  • SYSTEM rows: not promoted between environments; framework updates realign them 3-way without ever overwriting customizations (above). Framework translations only arrive as missing keys.
  • Multi-tenant: the installation files (reports, CSS, assets) are shared across tenants.

Quick example via API

Snippet 3Bash
# dev: release e pacchetto
curl -s -X POST "$WUIC/api/meta-lifecycle/releases" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"tag":"1.4.0","message":"sprint 12"}'
curl -s -X POST "$WUIC/api/meta-lifecycle/releases/1.4.0/export" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}' -o release-1.4.0.wuicpkg
# prod: carica, pianifica, applica
curl -s -X POST "$PROD/api/meta-lifecycle/packages/upload" -H "Authorization: Bearer $PROD_TOKEN" -H "Content-Type: application/octet-stream" --data-binary @release-1.4.0.wuicpkg
curl -s -X POST "$PROD/api/meta-lifecycle/promotions/plan" -H "Authorization: Bearer $PROD_TOKEN" -H "Content-Type: application/json" -d '{"packageId":"<packageId>"}'
curl -s -X POST "$PROD/api/meta-lifecycle/promotions/<promotionId>/apply" -H "Authorization: Bearer $APPROVER_TOKEN" -H "Content-Type: application/json" -d '{"planHash":"<hash>"}'

Screenshot

History: the versions of the cities route with date, author and message of each commit
History: the versions of the cities route with date, author and message of each commit
Compare: visual diff between two versions and table of the changed properties
Compare: visual diff between two versions and table of the changed properties
Recorded releases with the previous release, the number of items and the full or delta export
Recorded releases with the previous release, the number of items and the full or delta export
Promotion plan: 3-way conflict on the cities route (base, source, target) with a per-property choice; apply stays blocked while conflicts are open
Promotion plan: 3-way conflict on the cities route (base, source, target) with a per-property choice; apply stays blocked while conflicts are open