Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:06:40Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:36, 6 July 2026
Line 326:		Line 326:
	* <code>metadata</code> is the supported place for deployment-specific key-value data without schema migrations; the specs pass it through verbatim as <code>dict</code>.		* <code>metadata</code> is the supported place for deployment-specific key-value data without schema migrations; the specs pass it through verbatim as <code>dict</code>.
	* Soft-delete applies (via <code>EMRBaseModel</code>); an organization can't be deleted while it still has children, and system-generated orgs can't be deleted.		* Soft-delete applies (via <code>EMRBaseModel</code>); an organization can't be deleted while it still has children, and system-generated orgs can't be deleted.

			{{Navbox access governance}}

	{{Related}}		{{Related}}
			Wiki: ohcnwiki.tellmey.fyi

Admin: OHC identity seed

2026-07-04T22:43:48Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=access-governance
|title=Organization
|order=1
|introduced=3.0
|model=Organization
|reference=References/Permission
}}

Organizations are Care's FHIR-aligned grouping primitive: a nested tree that groups permissions and resources. A node might represent all doctors, a <code>Cardiology</code> sub-team, or a governance unit, and permissions attached to a parent flow implicitly to every descendant. You touch them whenever you model who can do what, and where.

'''Source:''' [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/organization.py <code>care/emr/models/organization.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/organization/spec.py <code>resources/organization/spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/organization/organization_user_spec.py <code>resources/organization/organization_user_spec.py</code>]

The Django model is only the storage layer. Its opaque columns — <code>JSONField</code>s (<code>metadata</code>, <code>cached_parent_json</code>) and arrays (<code>parent_cache</code>, <code>managing_organizations</code>) — get their structure from the resource specs under <code>care/emr/resources/organization/</code>, which also define the <code>org_type</code> enum, validation, the nested JSON returned for <code>parent</code>, and the read/write API schemas. See [[#resource-specs-api-schema|Resource specs (API schema)]].

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>OrganizationCommonBase</code>
| Abstract base holding the tree structure, caching, and uniqueness logic shared by both organization types
|-
| <code>Organization</code>
| Instance-wide organization (permission/governance tree, not tied to a facility)
|-
| <code>FacilityOrganization</code>
| Facility-scoped organization (departments/teams within one <code>Facility</code>)
|-
| <code>OrganizationUser</code>
| Membership row linking a <code>User</code> to an <code>Organization</code> with a <code>RoleModel</code>
|-
| <code>FacilityOrganizationUser</code>
| Membership row linking a <code>User</code> to a <code>FacilityOrganization</code> with a <code>RoleModel</code>
|}

<code>Organization</code> and <code>FacilityOrganization</code> extend <code>OrganizationCommonBase</code>, which extends [[References/Base models & conventions|<code>EMRBaseModel</code>]] — the shared Care EMR base providing <code>external_id</code>, audit fields, soft-delete, and <code>history</code>/<code>meta</code> JSON. <code>OrganizationUser</code> and <code>FacilityOrganizationUser</code> extend <code>EMRBaseModel</code> directly. <code>OrganizationCommonBase</code> is <code>abstract = True</code> and has no table of its own.

== <code>OrganizationCommonBase</code> fields ==

These columns land on both the <code>Organization</code> and <code>FacilityOrganization</code> tables.

=== Identity & classification ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=Organization|section=Identity & classification|name=name|type=CharField(255)|notes=yes}}
{{Field|model=Organization|section=Identity & classification|name=org_type|type=CharField(255)|notes=yes}}
{{Field|model=Organization|section=Identity & classification|name=description|type=TextField|notes=no}}
{{Field|model=Organization|section=Identity & classification|name=active|type=BooleanField|notes=no}}
{{Field|model=Organization|section=Identity & classification|name=system_generated|type=BooleanField|notes=no}}
{{Field|model=Organization|section=Identity & classification|name=metadata|type=JSONField|notes=no}}
|}

=== Tree structure ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=Organization|section=Tree structure|name=parent|type=FK → self|notes=no}}
{{Field|model=Organization|section=Tree structure|name=root_org|type=FK → self|notes=no}}
{{Field|model=Organization|section=Tree structure|name=has_children|type=BooleanField|notes=no}}
|}

=== Denormalized caches ===

Care rebuilds these on insert so reading the tree doesn't need recursive joins. Do not set them from clients.

{| class="wikitable"
|-
! Field
! Type
! Default
! Rebuilt by
! Shape
|-
| <code>level_cache</code>
| <code>IntegerField</code>
| <code>0</code>
| <code>set_organization_cache()</code>
| Depth in the tree (<code>parent.level_cache + 1</code>)
|-
| <code>parent_cache</code>
| <code>ArrayField[int]</code>
| <code>[]</code> (<code>list</code>)
| <code>set_organization_cache()</code>
| Full ancestor '''internal id''' chain (<code>parent.parent_cache + [parent.id]</code>)
|-
| <code>cached_parent_json</code>
| <code>JSONField</code>
| <code>{}</code> (<code>dict</code>)
| <code>get_parent_json()</code>
| Materialized parent record (shape below). Rebuilt after <code>cache_expiry_days</code> (15)
|}

<code>cached_parent_json</code> is built in <code>get_parent_json()</code> and is <code>{}</code> for root orgs:

<syntaxhighlight lang="text">{
id: str (parent.external_id, UUID as string)
name: str
description: str | null
org_type: str (OrganizationTypeChoices value)
metadata: dict
parent: dict (recursively, the parent's own cached_parent_json)
level_cache: int
cache_expiry: str (ISO datetime; cache is reused while now < cache_expiry)
}</syntaxhighlight>
This is the same structure <code>OrganizationReadSpec.parent</code> returns on read (see [[#parent-read-shape|<code>parent</code> read shape]]).

== Related models ==

=== <code>Organization</code> ===

Instance-wide organization. Adds one field on top of <code>OrganizationCommonBase</code>:

{| class="wikitable"
|-
! Field
! Type
! Default
! Notes
{{Field|model=Organization|section=Organization|name=managing_organizations|type=ArrayField[int]|notes=<code>[]</code> (<code>list</code>)}}
|}

=== <code>FacilityOrganization</code> ===

Facility-scoped organization — departments, teams, and groups within one facility. Adds one field on top of <code>OrganizationCommonBase</code>:

<syntaxhighlight lang="text">facility → FK facility.Facility (CASCADE)</syntaxhighlight>
Its <code>org_type</code> binds to <code>FacilityOrganizationTypeChoices</code> rather than <code>OrganizationTypeChoices</code> (see [[#facility-organization-type-values|Facility organization type values]]), and its specs live in <code>resources/facility_organization/</code>. <code>FacilityOrganizationWriteSpec</code> requires <code>facility</code> + <code>org_type</code> + optional <code>parent</code> (validated to be in the same facility); <code>FacilityOrganizationReadSpec</code> / <code>FacilityOrganizationRetrieveSpec</code> mirror the instance read specs, resolving the caller's <code>permissions</code> through <code>get_permission_on_facility_organization</code>. See [[References/Facility]].

=== <code>OrganizationUser</code> ===

Grants a user access to an organization's resources through a role — only the resources assigned to the org, not everything it owns.

<syntaxhighlight lang="text">organization → FK Organization (CASCADE)
user → FK users.User (CASCADE)
role → FK security.RoleModel (CASCADE)</syntaxhighlight>
=== <code>FacilityOrganizationUser</code> ===

The facility-scoped equivalent of <code>OrganizationUser</code>.

<syntaxhighlight lang="text">organization → FK FacilityOrganization (CASCADE)
user → FK users.User (CASCADE)
role → FK security.RoleModel (CASCADE)</syntaxhighlight>
== Enum & coded values ==

=== Organization type values ===

<code>Organization.org_type</code> is a <code>CharField</code> in the DB, but every write binds to <code>OrganizationTypeChoices</code> (<code>resources/organization/spec.py</code>).

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>team</code>
| A working / department-style grouping of people (the default)
|-
| <code>govt</code>
| A governance unit mirroring a real administrative hierarchy (<code>State → District → …</code>). Any user can view these to support cross-governance coordination; create/edit is superadmin-only; facilities and patients reference these nodes geographically
|-
| <code>role</code>
| A '''user group''' — a flat set of users, e.g. ''Volunteer'', ''ASHA Worker''. Adding an <code>OrganizationUser</code> to a <code>role</code>-typed org invalidates that user's <code>cached_role_orgs</code> (see [[#organizationusersave
|-
| <code>product_supplier</code>
| Supplier organization (links to the supply chain)
|}

=== Facility organization type values ===

<code>FacilityOrganization.org_type</code> binds to a '''separate''' enum — <code>FacilityOrganizationTypeChoices</code> (<code>resources/facility_organization/spec.py</code>), '''not''' <code>OrganizationTypeChoices</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>root</code>
| System-generated top node, one per facility (cannot be edited or deleted)
|-
| <code>dept</code>
| A department within the facility
|-
| <code>team</code>
| A team, often nested under a department
|-
| <code>role</code>
| A facility-scoped user group
|-
| <code>other</code>
| Any grouping outside the categories above
|}

Root, <code>govt</code>, and <code>role</code> (instance) organizations, plus any system-generated organization, are restricted to superadmin management.

== Resource specs (API schema) ==

Resource specs (<code>EMRResource</code> subclasses) are the API layer. <code>serialize</code> builds a read object from a DB row, running the <code>perform_extra_serialization</code> / <code>perform_extra_user_serialization</code> hooks; <code>de_serialize</code> builds a DB row from a write payload, running <code>perform_extra_deserialization</code>. <code>__exclude__</code> lists the model fields the base serializer skips so a hook can handle them instead.

=== Organization specs (<code>resources/organization/spec.py</code>) ===

{| class="wikitable"
|-
! Spec
! Role
! Fields exposed
! Notes
|-
| <code>OrganizationBaseSpec</code>
| shared
| <code>id</code>, <code>active</code>, <code>org_type</code>, <code>name</code>, <code>description</code>, <code>metadata</code>
| <code>__model__ = Organization</code>, <code>__exclude__ = ["parent"]</code>. <code>org_type</code> bound to <code>OrganizationTypeChoices</code>; <code>description</code> defaults <code>""</code>; <code>metadata</code> defaults <code>{}</code>
|-
| <code>OrganizationUpdateSpec</code>
| write · update
| (inherits <code>OrganizationBaseSpec</code>)
| No extra fields — <code>parent</code> can't change on update
|-
| <code>OrganizationWriteSpec</code>
| write · create
| base + <code>parent: UUID4 | null</code>
| Validates <code>parent</code> exists (<code>validate_parent_organization</code>); on create, <code>perform_extra_deserialization</code> resolves <code>parent</code> from <code>external_id</code> (or sets <code>None</code>)
|-
| <code>OrganizationReadSpec</code>
| read · list
| base + <code>level_cache</code>, <code>system_generated</code>, <code>has_children</code>, <code>parent: dict</code>
| <code>perform_extra_serialization</code> sets <code>id = external_id</code> and <code>parent = obj.get_parent_json()</code> — see [[#parent-read-shape
|-
| <code>OrganizationRetrieveSpec</code>
| read · detail
| <code>OrganizationReadSpec</code> + <code>permissions: list[str]</code>, <code>managing_organizations: list[dict]</code>
| <code>perform_extra_user_serialization</code> fills <code>permissions</code> (via <code>AuthorizationController.get_permission_on_organization</code> for the requesting user), expands <code>managing_organizations</code> to nested <code>OrganizationReadSpec</code> JSON, and adds audit users (<code>serialize_audit_users</code>)
|}

==== <code>parent</code> read shape ====

On read, <code>OrganizationReadSpec.parent</code> (and <code>OrganizationRetrieveSpec.parent</code>) is '''not''' a UUID — it's the nested object from <code>get_parent_json()</code>, sharing the shape of [[#denormalized-caches|<code>cached_parent_json</code>]]: <code>{ id, name, description, org_type, metadata, parent (recursive), level_cache, cache_expiry }</code>, or <code>{}</code> for root orgs. On write, <code>parent</code> is instead a plain <code>UUID4</code> (the parent's <code>external_id</code>).

=== Membership specs (<code>resources/organization/organization_user_spec.py</code>) ===

{| class="wikitable"
|-
! Spec
! Role
! Fields exposed
! Notes
|-
| <code>OrganizationUserBaseSpec</code>
| shared
| (none)
| <code>__model__ = OrganizationUser</code>, <code>__exclude__ = ["user", "role"]</code>
|-
| <code>OrganizationUserUpdateSpec</code>
| write · update
| <code>role: UUID4</code>
| <code>validate_role</code> requires the <code>RoleModel</code> to exist; <code>perform_extra_deserialization</code> resolves <code>role</code> from <code>external_id</code>. Only the role can change on update
|-
| <code>OrganizationUserWriteSpec</code>
| write · create
| <code>role: UUID4</code> + <code>user: UUID4</code>
| Extends the update spec; <code>validate_user</code> requires the <code>User</code> to exist. On create, resolves both <code>user</code> and <code>role</code> from <code>external_id</code>
|-
| <code>OrganizationUserReadSpec</code>
| read
| <code>id: UUID4</code>, <code>user: dict</code>, <code>role: dict</code>
| <code>user</code> = cached <code>UserSpec</code> JSON (<code>model_from_cache</code>); <code>role</code> = <code>RoleReadSpec</code> JSON (full permissions)
|-
| <code>OrganizationUserExtendedReadSpec</code>
| read
| <code>id: UUID4</code>, <code>role: dict</code>, <code>organization: dict</code>
| Used by <code>OrganizationUser.get_cached_role_orgs()</code>. <code>organization</code> = <code>OrganizationReadSpec</code> JSON; <code>role</code> = <code>RoleReadMinimalSpec</code> JSON (no permission list)
|}

Nested membership JSON shapes (from <code>resources/role/spec.py</code>, <code>resources/user/spec.py</code>):

<syntaxhighlight lang="text">role (RoleReadSpec): { id: UUID, name, description, is_system: bool,
is_archived: bool, contexts: [RoleContext],
permissions: [{ name, description, slug, context }] }
role (RoleReadMinimalSpec): same as above without `permissions`
user (UserSpec): cached user summary JSON</syntaxhighlight>
== Methods & save behaviour ==

=== <code>OrganizationCommonBase.save()</code> ===

On insert (no <code>id</code> yet), the base saves the row, then calls <code>set_organization_cache()</code> to populate the tree caches. Updates save normally and don't recompute caches.

<code>set_organization_cache()</code> side effects when a <code>parent</code> is set:

# Computes <code>parent_cache</code> = <code>parent.parent_cache + [parent.id]</code> and <code>level_cache</code> = <code>parent.level_cache + 1</code>.
# Derives <code>root_org</code> from the parent (<code>parent.root_org</code>, or the parent itself if the parent is a root).
# If the parent had no children before, flips <code>parent.has_children = True</code> and persists only that field.

=== <code>get_parent_json()</code> ===

Returns the cached parent JSON while <code>cached_parent_json</code> is present and <code>cache_expiry</code> is still in the future. Otherwise it recursively rebuilds the nested parent record, stamps a new expiry (<code>cache_expiry_days = 15</code>), and persists <code>cached_parent_json</code>. Returns <code>{}</code> for root orgs. This is what <code>OrganizationReadSpec.parent</code> exposes on every read.

=== <code>validate_uniqueness(queryset, pydantic_instance, model_instance)</code> ===

Classmethod enforcing <code>name</code> uniqueness among '''siblings''' — those sharing the same <code>root_org</code> and <code>level_cache</code>. For a new org it derives <code>level_cache</code>/<code>root_org</code> from the supplied <code>parent</code> (<code>external_id</code>); a null parent means <code>level_cache = 0</code> and a null <code>root_org</code>. The resource layer calls it before create/update.

=== <code>OrganizationUser.save()</code> ===

After saving, if the linked organization's <code>org_type</code> is <code>role</code> (<code>OrganizationTypeChoices.role</code>), it clears <code>user.cached_role_orgs</code> (sets it to <code>None</code> and persists that field) so the user's role-org cache rebuilds on the next read.

<code>OrganizationUser.get_cached_role_orgs(user_id)</code> is a classmethod that serializes all of a user's <code>role</code>-typed org memberships via <code>OrganizationUserExtendedReadSpec</code>.

== API integration notes ==

* Organizations are exposed through Care's REST API and align with the FHIR <code>Organization</code> resource. Tree position (<code>level_cache</code>, <code>parent_cache</code>, <code>root_org</code>), <code>has_children</code>, and <code>cached_parent_json</code> are platform-maintained — don't set them from clients.
* '''Write path:''' <code>OrganizationWriteSpec</code> (create) / <code>OrganizationUpdateSpec</code> (update). <code>org_type</code> is constrained to <code>OrganizationTypeChoices</code>; <code>parent</code> is supplied as the parent's <code>external_id</code> (UUID) and validated to exist; <code>validate_uniqueness</code> enforces sibling-name uniqueness. <code>parent</code> is immutable after create (the update spec omits it).
* '''Read path:''' <code>OrganizationReadSpec</code> (list) returns <code>parent</code> as nested JSON (<code>get_parent_json()</code>) plus <code>level_cache</code>/<code>system_generated</code>/<code>has_children</code>; <code>OrganizationRetrieveSpec</code> (detail) adds the caller's <code>permissions</code>, expanded <code>managing_organizations</code>, and audit users.
* Membership is managed through <code>OrganizationUser</code> / <code>FacilityOrganizationUser</code> (specs above); <code>role</code> is required and bounded by the assigning user's own role in that org. Adding a member to a <code>role</code>-typed org invalidates that user's <code>cached_role_orgs</code>.
* <code>metadata</code> is the supported place for deployment-specific key-value data without schema migrations; the specs pass it through verbatim as <code>dict</code>.
* Soft-delete applies (via <code>EMRBaseModel</code>); an organization can't be deleted while it still has children, and system-generated orgs can't be deleted.

{{Related}}

References/Organization - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed