Skip to main content
Promotion is the operation that turns a linked Application into a federated one: the org root moves from your Application to Alfiz Cloud, and organizational-domain data becomes centrally authoritative. It is a deliberate, validated, atomic operation, and it has a documented way back.

​
Prerequisites

Two things must be true before promotion can begin:
  • The Application is linked, so the provider handler is mounted, the secret is configured, and the health probe passes.
  • The Application’s catalog is published to the registry. The org root cannot hold roles and grants against vocabulary it cannot see.

​
What promotion does

1

Export over the Provider API

Alfiz Cloud pulls the Application’s organizational-domain data (groups, roles, global grants and revokes, the reporting hierarchy) through the same provider connection that carries everyday administrative traffic.
2

Validate through the standard import paths

The exported data passes through the same import paths as any external directory, so nothing about promotion is a special case. Group-parent cycles condense to virtual parents with warnings, exactly as they do during directory ingestion; nothing is silently dropped.
3

Flip authority atomically

Authority transfers as a single push, applied and then acknowledged: Alfiz Cloud sends one org.applySnapshot carrying authority: true, and your Application rejects local org-domain writes with ProviderWriteRejectedError (not_org_root) once it is rebuilt with the new flag. The snapshot is applied as a sequence of individual storage writes rather than inside a transaction, so run the transfer during a quiet window rather than under concurrent org-domain load.Because orgRoot is a constructor commitment, the provider handler calls your onAuthorityChanged hook with the applied authority value so the host process can rebuild its Application. The hook fires after every applied snapshot, including routine read-model syncs that pass authority: false, so branch on the argument rather than treating the call itself as a transfer. Wire it before you start promotion; see Handling authority transfer.
4

Push the read model down

Alfiz Cloud syncs the org-domain read model back down to the Application, which evaluates it locally, exactly as it did when it owned the data. Runtime checks never notice the move.
Pending access requests survive promotion untouched. Approval stages reference layers and roles, such as “2 layers up” or a named role id, and never resolved people, so they re-resolve correctly against the promoted hierarchy at decision time.

​
Merging a second application

When a second application federates and carries its own org-domain data, the merge follows three rules:
  • Positive data unions. Groups, role definitions, and global grants union safely, because union-only inheritance means unioning only ever widens, so a merged row can never take access away.
  • Id collisions with different definitions are surfaced for rename. Two roles both named editor with different patterns are not averaged or overwritten. The conflict is returned, and you rename one before the merge completes.
  • Reporting trees never auto-merge. A user cannot have two managers, so conflicting edges return per-user, and you resolve each one explicitly through the resolutions body on the federate call or from the Dashboard.

​
Demotion

Demotion is promotion’s inverse, available when one member application remains:
  • The org-domain dataset snapshots down into the Application.
  • The Application resumes authority, so orgRoot behavior returns to standalone semantics, and local org-domain writes are accepted again.
  • Cloud-only vocabulary stays behind. Roles and grants living entirely in cloud.*, which is vocabulary that exists only in the hosted domain, do not travel down; there is nothing local for them to bind to. The parallel to virtual-parent dissolution is exact: structure that existed only to make the hosted composition coherent dissolves when the composition ends, and everything that was yours comes home intact.

The catalog registry

Publishing is a promotion prerequisite, because versions, tombstones, and the drift report are covered in the registry guide.