govoplan-idm/docs/FUNCTION_ASSIGNMENT_WORKFLOWS.md

Function Assignment Request And Grant Workflows

Purpose

Assigning an identity to an organization function is a governed business change, not just an IDM table edit. IDM owns the request or grant record and the resulting effective-dated assignment. Organizations owns units and function definitions. Policy resolves who may initiate, clear, accept, reject, revoke, or recover a change. Workflow Engine runs the selected, version-pinned process.

An assignment workflow never grants generic application permissions by itself. Access may project an accepted function assignment into roles only through an explicit function mapping.

Two User Journeys

Request A Function

An eligible user finds a function, sees whether it can be requested and why, provides the required justification/evidence, and submits a request. The effective policy determines whether the request goes to a current holder, a clearing authority, both in sequence, or is unavailable because only an authority may initiate the assignment.

The requester can inspect progress, respond to questions, withdraw while permitted, and receive the final decision. No effective assignment exists until all required approvals and any configured recipient acceptance are complete.

Bestow A Function

An effective function holder or authority selects an eligible identity and proposes a function assignment with scope, validity, delegation, and evidence. The policy determines whether the holder may complete the grant, whether an authority must clear it, or whether only the authority can initiate and grant it. Recipient acceptance can be required or waived only by an explicit policy with recorded provenance.

Grant Profiles

The first policy profiles are:

• holder_grant: an effective holder may initiate and approve within the configured scope and duration ceilings.
• holder_with_authority_clearance: a holder or eligible requester may initiate, but the configured authority must clear the change.
• authority_only: only the configured authority may initiate and approve; other users receive an unavailable action with an explanation.

Profiles may additionally configure self-request eligibility, recipient acceptance, evidence requirements, separation of duties, quorum, expiry, maximum validity, delegation limits, vacancy routing, and escalation. Function or function-type configuration references a profile; Policy produces the effective decision and provenance rather than IDM duplicating policy logic.

IDM Aggregate

IDM should persist one function-assignment change aggregate for both journeys:

• change ID, tenant, kind (request or grant), function, unit, candidate identity/account, requested validity, and assignment source
• initiator, represented actor/function where applicable, policy profile and decision revision
• pinned workflow definition/revision and workflow instance reference
• justification, evidence references, comments, and redacted process variables
• state and append-only state history
• resulting assignment ID, or rejection/withdrawal/expiry reason
• idempotency key and optimistic-concurrency revision

Candidate states are draft, submitted, awaiting_holder, awaiting_authority, awaiting_recipient, approved, accepted, applied, rejected, withdrawn, expired, cancelled, and failed_manual_review. Not every profile uses every state.

The workflow instance coordinates the process, but the IDM change record is the business source of truth. A workflow callback applies the assignment exactly once after successful completion. Failed or outcome-unknown application is reconciled without starting a second grant.

Required Guarantees

• Every action rechecks current identity, holder, authority, function, and Policy facts. Authorization captured at submission is evidence, not a future permission grant.
• A holder who loses the source function cannot approve later unless Policy explicitly permits continuity for an already-open case.
• Vacancy and unavailable authority routes produce a visible blocked/escalated state rather than silently granting or losing the request.
• The proposer and required clearer cannot be the same actor where separation of duties applies.
• Effective dates, revocation, expiry, delegation, and acting-for semantics use the canonical IDM assignment contract.
• Notifications are emitted for durable waiting states and final outcomes when Notifications is installed.
• Audit receives non-secret evidence for every transition when Audit is installed.
• The direct administrative write path is either disabled for governed functions or treated as an explicit emergency override with reason, provenance, and equivalent evidence.

Module Boundaries

• Organizations: function definitions and assignment-policy profile reference.
• IDM: request/grant aggregate, candidate validation, effective assignment, and assignment lifecycle.
• Policy: effective initiator/approver/acceptance/quorum/expiry decisions and explanations.
• Workflow Engine: versioned definition installation and process execution.
• Workflow: optional authoring, inspection, and override UI.
• Notifications: waiting-state and outcome notifications.
• Audit: immutable transition and assignment evidence.
• Access: optional projection of accepted function facts into roles/rights.