120 lines
5.5 KiB
Markdown
120 lines
5.5 KiB
Markdown
# Organization Model
|
|
|
|
The organization model answers where responsibility lives.
|
|
|
|
## Layers
|
|
|
|
- Tenant: the administrative space.
|
|
- Organization unit type: an abstract type such as faculty, institute,
|
|
committee, department, team, service desk, or legal entity.
|
|
- Organization structure: a named way to look at the institution. Several
|
|
structures may exist in parallel, for example employer hierarchy, academic
|
|
structure, committees, memberships, or classifications.
|
|
- Relation type: the permitted edge between units inside a structure.
|
|
- Organization unit: a concrete department, office, committee, service desk,
|
|
school, institute, or other unit.
|
|
- Function: a named responsibility in an organization unit, such as clerk,
|
|
reviewer, approver, committee secretary, intake desk, or resource manager.
|
|
|
|
## Boundary With Identity And IDM
|
|
|
|
This module does not own login accounts, identity lifecycle, account linking,
|
|
or identity-to-function assignments. `govoplan-identity` owns the
|
|
identity/account directory. `govoplan-idm` records that an identity currently
|
|
holds an organizational function and may constrain that link to one account.
|
|
|
|
Resolving accounts to identities, choosing candidate identities for an
|
|
organization assignment, and importing those mappings from external directories
|
|
belongs to `govoplan-idm`, not to organizations.
|
|
|
|
## Boundary With Access
|
|
|
|
An IDM function assignment does not grant rights on its own. `govoplan-access`
|
|
maps organization and IDM facts to roles, rights, permission decisions,
|
|
delegation enforcement, and explain responses.
|
|
|
|
This separation keeps the institution model stable even when authorization
|
|
policy changes.
|
|
|
|
## Access Projection Migration
|
|
|
|
`govoplan-access` now prefers `organizations.directory` for organization units
|
|
and function definitions when the Organizations module is installed. It uses
|
|
`govoplan-idm` for identity-to-function assignment facts and Access-owned
|
|
external function-role mappings to turn accepted function facts into rights.
|
|
|
|
The legacy Access tables `access_organization_units`, `access_functions`, and
|
|
`access_function_assignments` remain readable as compatibility/projection
|
|
tables during rollout. They are no longer the target model for new module
|
|
integrations.
|
|
|
|
Rollout plan:
|
|
|
|
- keep direct Access function/organization reads as a fallback when
|
|
Organizations or IDM are not installed;
|
|
- backfill Organizations units/functions from the Access projection for
|
|
existing installations that enable the Organizations module later;
|
|
- move new identity-to-function assignment workflows to IDM rather than adding
|
|
assignment ownership to Organizations;
|
|
- use Access external function-role mappings for authorization and check that
|
|
the referenced Organizations function is still active before granting
|
|
derived permissions;
|
|
- retire Access-owned organization/function tables only after a release-level
|
|
migration/backfill and rollback plan exists.
|
|
|
|
The close-out condition is that Access role resolution works with canonical
|
|
Organizations plus IDM installed and still works through projection fallback
|
|
for transition deployments.
|
|
|
|
## Directory Contracts
|
|
|
|
`organizations.directory` remains the small compatibility contract for direct
|
|
unit and function lookup. It deliberately retains the legacy `parent_id`
|
|
projection needed by existing Access and IDM integrations.
|
|
|
|
`organizations.hierarchyDirectory` is the structure-aware contract for new
|
|
consumers. It provides:
|
|
|
|
- tenant-scoped unit-type and function-type references;
|
|
- function resolution by type and an explicit set of units;
|
|
- unit resolution by type, optionally bounded to one named structure;
|
|
- batched ancestor, descendant, and path resolution with a required structure,
|
|
optional relation-type filter, and bounded depth;
|
|
- the exact structure, relation type, and relation edge for every path step;
|
|
- explicit missing, inactive, unreachable, invalid-filter, cycle, and
|
|
depth-limit state.
|
|
|
|
An edge is traversed from `source_unit_id` to `target_unit_id` for descendant
|
|
lookups and in reverse for ancestor lookups. Consumers must select a structure;
|
|
the provider never treats `parent_id` or one arbitrary structure as the
|
|
institution's universal hierarchy.
|
|
|
|
Committed changes emit versioned `organizations.<resource>.<action>.v1`
|
|
platform events for units, functions, their types, structures, relation types,
|
|
and relation edges. The event payload contains schema version `1`, tenant and
|
|
resource references, status, changed fields, and routing-relevant IDs so
|
|
directory consumers can invalidate derived addresses without importing this
|
|
module's models.
|
|
|
|
## UI Boundary
|
|
|
|
The organization workspace at `/organizations` is the primary module UI for
|
|
modelling the meta-model, concrete units, structures, and function definitions.
|
|
Admin-only organization controls are still owned by this
|
|
module, but are contributed to the platform admin shell through the
|
|
`admin.sections` WebUI capability.
|
|
|
|
The admin contribution must not duplicate the organization editor. It is for
|
|
governance and policy settings: whether tenant admins may customize the
|
|
meta-model, whether model changes require recorded change requests, and how
|
|
audit detail and retention behave for organization changes.
|
|
|
|
## Boundary With IDM
|
|
|
|
`govoplan-idm` may import organization-unit and organization-function
|
|
definitions from external directories. It should write those definitions
|
|
through organization capabilities or APIs after preview, approval, and rollback
|
|
planning. IDM owns identity-to-function assignments and bridge views that
|
|
combine identity and organization facts, such as identity candidates for
|
|
function assignments.
|