@nzelajs/approver-orgchart

English below - Version francaise plus bas.

The org-chart approver resolver for the Nzela engine. It turns an abstract ApproverSpec (declared on a blueprint approval node) into concrete ResolvedApprover[] using the org chart: hierarchical echelons above the requester, self-approval for managers, vacancy escalation, durable delegation, desk queues and shared role queues. Org-driven: the blueprint names the target, the org chart supplies the people. Vendor-free.

English

Install

npm add @nzelajs/approver-orgchart @nzelajs/ports

Use

import { OrgChainApproverResolver } from "@nzelajs/approver-orgchart";

const resolver = new OrgChainApproverResolver({
  org, // an ApproverOrgStore (see below)
  directory, // optional DirectoryStore (display names)
  deskRules, // optional DeskRuleStore (only ORG_UNIT_VISA needs it)
  // optional reserved-resource routing for ORG_UNIT_QUEUE/VISA + resourceFrom:
  resolveResourceOwnerUnit: async (kind, code) => ownerUnitIdOrNull,
});

// Wired into the engine as its resolverFactory:
new NzelaEngine({ /* ... */, resolverFactory: () => resolver });

ApproverOrgStore (the read model it requires)

The Nzela port OrgStore is intentionally minimal (anchor unit, subtree, unit list, deprovision) and does not model management positions, their holders, ancestors or delegations. Resolving a chain of approvers needs those, so this package declares ApproverOrgStore, a SUPERSET of the port OrgStore: any store that satisfies it also satisfies the port. An app that wants org-chain resolution provides this richer read model (identities only, no PII, no business literals). The extra reads are: getUnitWithAncestors (nearest-first), getManagerPosition, getActiveAssignments (holders with role) and getActiveDelegationFrom.

Kinds resolved

• ORG_CHAIN: climb the real management echelons above the requester (anchor = the requester's/beneficiary's primary unit), pick the effective holder (titulaire > interim > suppleant), skip a vacant seat (escalate) and a self-conflict, honor a durable delegation. selfApproveIfManager skips the whole echelon when the requester runs their own anchor unit. A level above the available managers yields []: the chain length adapts to the requester's rank and the engine steps over the node.
• ORG_POSITION: the manager of the unit whose unitCode is given, escalating to fallbackUnitCode when the target is missing/vacant; [] as a last resort.
• ORG_UNIT_QUEUE: an unassigned task dropped in a unit's queue (queueUnitId); the target unit is read from unitFromForm, then a reserved resource owner (resourceFrom/resourceKind), then unitCode, then fallbackUnitCode.
• ORG_UNIT_VISA: a conditional visa placed after a queue step; the chief vises only when the desk rule says REQUIRES_CHIEF_VISA, otherwise [] (the agent closed end to end).
• TENANT_ROLE / ORG_ROLE / POSITION: a shared queue offered to every holder of a role / capability / position type (sharedQueueRole); no individual resolved here (claimed later).
• REQUESTER: the case's own requester (receipt confirmation).

A SOFT non-resolution (vacant, unknown unit, requester above the chain) returns [] and the engine steps over the node. A HARD error (missing spec, missing required field, unattached beneficiary) throws ApproverResolutionError.

Francais

Installation

npm add @nzelajs/approver-orgchart @nzelajs/ports

Role

Le resolveur d'approbateurs par organigramme du moteur Nzela : il transforme un ApproverSpec abstrait (declare sur un noeud d'approbation) en ResolvedApprover[] concrets via l'organigramme. Org-driven : le blueprint nomme la cible, l'organigramme fournit les personnes.

Construction : new OrgChainApproverResolver({ org, directory?, deskRules?, resolveResourceOwnerUnit? }).

ApproverOrgStore (le modele de lecture requis)

Le port OrgStore est volontairement minimal et ne modelise ni les postes de management, ni leurs titulaires, ni les ancetres, ni les delegations. La resolution d'une chaine en a besoin : ce paquet declare ApproverOrgStore, un SURENSEMBLE du port OrgStore (tout store qui le satisfait satisfait aussi le port). Une application qui veut la resolution par chaine fournit ce modele plus riche (identites seulement, jamais de PII ni de litteraux metier).

Types resolus

• ORG_CHAIN : montee des echelons de management reels au-dessus du demandeur (ancre = unite de rattachement), titulaire > interim > suppleant, saut d'un siege vacant (escalade) et d'un conflit d'interet, delegation durable honoree. selfApproveIfManager franchit l'echelon quand le demandeur dirige son unite d'ancrage. Un level au-dela des managers disponibles renvoie [].
• ORG_POSITION : chef de l'unite de code unitCode, repli vers fallbackUnitCode si absente/vacante ; [] en dernier recours.
• ORG_UNIT_QUEUE : tache deposee dans la file d'une unite (queueUnitId) ; unite lue via unitFromForm, puis gestionnaire d'une ressource reservee (resourceFrom/resourceKind), puis unitCode, puis fallbackUnitCode.
• ORG_UNIT_VISA : visa conditionnel apres une etape de file ; le chef vise uniquement si la regle de bureau exige REQUIRES_CHIEF_VISA, sinon [] (l'agent a cloture de bout en bout).
• TENANT_ROLE / ORG_ROLE / POSITION : file partagee offerte a tous les porteurs d'un role / d'une capacite / d'un type de poste (sharedQueueRole) ; personne n'est resolu ici.
• REQUESTER : le demandeur du dossier (confirmation de reception).

Une non-resolution DOUCE (vacance, unite inconnue, demandeur au-dessus de la chaine) renvoie [] et le moteur franchit le noeud. Une erreur DURE leve ApproverResolutionError.

License

Apache-2.0. See LICENSE and NOTICE.