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

2026-07-06T04:08:15Z

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

← Older revision		Revision as of 09:38, 6 July 2026
Line 328:		Line 328:
	* To change a role's membership, write <code>RolePermission</code> rows rather than editing <code>RoleModel</code> directly. Use the ORM so the cache-invalidation signal fires; raw SQL leaves the Redis cache stale.		* To change a role's membership, write <code>RolePermission</code> rows rather than editing <code>RoleModel</code> directly. Use the ORM so the cache-invalidation signal fires; raw SQL leaves the Redis cache stale.
	* Other access-control models (organization memberships, patient/encounter associations) reference roles to resolve a user's effective permissions in a given context.		* Other access-control models (organization memberships, patient/encounter associations) reference roles to resolve a user's effective permissions in a given context.

			{{Navbox access governance}}

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

Admin: OHC identity seed

2026-07-04T22:43:57Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=access-governance
|title=Role
|order=3
|introduced=3.0
|model=Role
|reference=References/Base models & conventions
}}

A role is a flat set of permissions granted to a user inside one organizational boundary. It carries no semantics of its own — "Doctor", "Doctor Read Only" and "Doctor Scheduler" are three unrelated permission sets, not variations on a job title. A user can hold roles in many organizations but only one role per organization chain. <code>RolePermission</code> join rows expand a role into its effective permission list.

Two layers back the concept. The Django model (<code>care/security/models/role.py</code>) is storage: <code>name</code>, <code>description</code>, flags, and the <code>contexts</code> array. The Pydantic resource specs (<code>care/emr/resources/role/spec.py</code>, <code>care/emr/resources/permissions.py</code>) define the API read/write schemas, bind <code>contexts</code> to an enum, type the permissions field, and hold every create/update validation rule.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/models/role.py <code>care/security/models/role.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/role/spec.py <code>care/emr/resources/role/spec.py</code>]
* Permissions mixins: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/permissions.py <code>care/emr/resources/permissions.py</code>]
* Role definitions: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/roles/role.py <code>care/security/roles/role.py</code>]
* Permission registry: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/permissions/base.py <code>care/security/permissions/base.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>RoleModel</code>
| A named role grouping a set of permissions
|-
| <code>RolePermission</code>
| Join table linking a <code>RoleModel</code> to a <code>PermissionModel</code>
|}

Both extend <code>BaseModel</code> (see [[References/Base models & conventions|Base model]]), so they get <code>external_id</code>, <code>created_date</code>/<code>modified_date</code>, and soft-delete via <code>deleted</code> — but none of the <code>created_by</code>/<code>updated_by</code>/history/meta fields that <code>EMRBaseModel</code> adds.

== <code>RoleModel</code> fields ==

User-created roles can be deleted by anyone holding the right permission. System roles (<code>is_system=True</code>) are exempt: the API blocks creating, updating, or deleting them.

=== Identity & description ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=Role|section=Identity & description|name=name|type=CharField(1024)|notes=yes}}
{{Field|model=Role|section=Identity & description|name=description|type=TextField|notes=no}}
{{Field|model=Role|section=Identity & description|name=contexts|type=ArrayField[CharField(24)]|notes=yes}}
|}

=== Status flags ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=Role|section=Status flags|name=is_system|type=BooleanField|notes=no}}
{{Field|model=Role|section=Status flags|name=temp_deleted|type=BooleanField|notes=no}}
{{Field|model=Role|section=Status flags|name=is_archived|type=BooleanField|notes=no}}
|}

=== Meta / constraints ===

<code>name</code> is unique only among non-deleted rows, enforced by a partial constraint:

<syntaxhighlight lang="text">UniqueConstraint(fields=["name"], condition=Q(deleted=False), name="unique_name_if_not_deleted")</syntaxhighlight>
<code>RoleCreateSpec</code> checks the same uniqueness case-insensitively (<code>name__iexact</code>) before the request ever reaches the DB constraint.

== Related models ==

=== <code>RolePermission</code> ===

Each row connects a role to one permission; a role accumulates its grants across many rows.

<syntaxhighlight lang="text">role → FK RoleModel (CASCADE, required)
permission → FK PermissionModel (CASCADE, required)
temp_deleted → BooleanField (default False)</syntaxhighlight>
<code>temp_deleted</code> excludes a grant from the role without deleting the row — permission lookups filter on <code>rolepermission__temp_deleted=False</code>.

=== <code>PermissionModel</code> ===

The permission a <code>RolePermission</code> points at ([[References/Permission]]).

<syntaxhighlight lang="text">slug → CharField(1024) unique, indexed
name → CharField(1024)
description → TextField (default "")
context → CharField(1024) # one of the PermissionContext values
temp_deleted → BooleanField (default False)</syntaxhighlight>
The set of available permissions lives in code, not as fixed DB rows. <code>PermissionController</code> (<code>care/security/permissions/base.py</code>) registers them by aggregating per-domain <code>enum.Enum</code> handlers such as <code>PatientPermissions</code> and <code>FacilityPermissions</code>, where each member's value is a <code>Permission(name, description, context, roles)</code> dataclass.

== Enum / value tables ==

=== <code>RoleContext</code> values ===

Each element of <code>contexts</code> is validated against this enum (<code>care/security/roles/role.py</code>). These name the organizational boundary a role can apply to — a different axis from <code>PermissionContext</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>FACILITY</code>
| Role applies within a facility
|-
| <code>GOVT_ORG</code>
| Role applies within a government organization
|-
| <code>ROLE_ORG</code>
| Role applies within a role (user-group) organization
|}

=== <code>PermissionContext</code> values ===

<code>PermissionModel.context</code> / <code>Permission.context</code> is one of these (<code>care/security/permissions/constants.py</code>). The <code>permissions</code> mixins below filter grants by context to resolve a user's effective permissions.

{| class="wikitable"
|-
! Value
|-
| <code>GENERIC</code>
|-
| <code>FACILITY</code>
|-
| <code>PATIENT</code>
|-
| <code>QUESTIONNAIRE</code>
|-
| <code>ORGANIZATION</code>
|-
| <code>FACILITY_ORGANIZATION</code>
|-
| <code>ENCOUNTER</code>
|}

=== <code>PermissionEnum</code> (write field for <code>permissions</code>) ===

<code>RoleCreateSpec.permissions</code> is typed against <code>PermissionController.get_enum()</code>, a <code>str</code> enum built at runtime from every registered permission <code>name</code> across all handlers. Values are permission identifiers (slugs) like <code>can_create_patient</code>, <code>can_write_patient</code>, <code>can_list_patients</code>, <code>can_view_clinical_data</code>. The set is the union of <code>PermissionController.internal_permission_handlers</code> plus anything plugins register, so it varies by deployment.

=== Built-in (<code>is_system</code>) roles ===

<code>RoleController</code> (<code>care/security/roles/role.py</code>) seeds these with <code>is_system=True</code>. None can be created, updated, or deleted through the API.

{| class="wikitable"
|-
! Role
! Contexts
|-
| <code>Doctor</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Nurse</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Staff</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Volunteer</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Pharmacist</code>
| <code>FACILITY</code>
|-
| <code>Administrator</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Facility Admin</code>
| <code>FACILITY</code>
|-
| <code>Admin</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Admin</code> (role org)
| <code>ROLE_ORG</code>
|-
| <code>Manager</code> (role org)
| <code>ROLE_ORG</code>
|-
| <code>Member</code> (role org)
| <code>ROLE_ORG</code>
|}

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> (<code>care/emr/resources/base.py</code>), which supplies <code>serialize</code> (DB → Pydantic, via <code>perform_extra_serialization</code>) and <code>de_serialize</code> (Pydantic → DB, via <code>perform_extra_deserialization</code>). <code>RoleBaseSpec</code> sets <code>__exclude__ = ["permissions"]</code> so each subclass declares <code>permissions</code> itself instead of inheriting it.

{| class="wikitable"
|-
! Spec class
! Role
! Fields
|-
| <code>RoleBaseSpec</code>
| shared base
| <code>id</code>, <code>name</code>, <code>description</code>, <code>is_system</code>, <code>is_archived</code>, <code>contexts</code>
|-
| <code>RoleCreateSpec</code>
| write · create & update
| base fields + <code>permissions: list[PermissionEnum]</code>
|-
| <code>RoleReadSpec</code>
| read · detail/list
| base fields + <code>permissions: list[PermissionSpec]</code>
|-
| <code>RoleReadMinimalSpec</code>
| read · minimal/embedded
| base fields only
|-
| <code>PermissionSpec</code>
| nested (read)
| <code>name</code>, <code>description</code>, <code>slug</code> (<code>SlugType</code>), <code>context</code>
|}

=== Field shapes & bindings ===

{| class="wikitable"
|-
! Field
! Spec type
! Notes
|-
| <code>id</code>
| <code>UUID4 | None</code>
| The role's <code>external_id</code> on read (set in <code>perform_extra_serialization</code>); ignored on write
|-
| <code>name</code>
| <code>str | None</code>
| Required and non-blank on create; case-insensitive uniqueness enforced
|-
| <code>description</code>
| <code>str | None</code>
| Optional
|-
| <code>is_system</code>
| <code>bool | None</code> (default <code>False</code>)
| Must be falsy on write — <code>True</code> is rejected
|-
| <code>is_archived</code>
| <code>bool | None</code> (default <code>False</code>)
| —
|-
| <code>contexts</code>
| <code>list[RoleContext]</code>
| Bound to the <code>RoleContext</code> enum
|-
| <code>permissions</code> (write)
| <code>list[PermissionEnum]</code> (default <code>[]</code>)
| Dynamic <code>str</code> enum of every registered permission name; must contain ≥ 1 entry
|-
| <code>permissions</code> (read)
| <code>list[PermissionSpec]</code>
| Resolved server-side from the role's active grants
|-
| <code>PermissionSpec.slug</code>
| <code>SlugType</code>
| <code>str</code>, length 5–50, pattern <code>^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$</code>
|}

=== Validation (<code>RoleCreateSpec.validate_role</code>, mode="after") ===

The validator runs on both create and update; it reads the <code>is_update</code> flag and the target <code>object</code> from the serializer context.

* On create, <code>name</code> must be present and non-blank (<code>"Role name cannot be empty"</code>).
* <code>name</code> must be unique case-insensitively (<code>name__iexact</code>), excluding the current row on update. A duplicate raises <code>"Role with this name already exists"</code>.
* Updating a role with <code>is_system=True</code> raises <code>"Cannot update system roles"</code>.
* <code>is_system=True</code> in the payload raises <code>"Cannot create system roles"</code>.
* <code>permissions</code> must be non-empty, otherwise <code>"At least one permission must be assigned to the role"</code>.
* <code>permissions</code> is de-duplicated (<code>list(set(...))</code>).

=== Server-side serialization behaviour ===

* '''Write''' (<code>RoleCreateSpec.perform_extra_deserialization</code>): the validated <code>permissions</code> list is attached to the instance as <code>obj.permissions</code>, a transient attribute — <code>permissions</code> is in <code>__exclude__</code> and isn't a model column. The view/service layer materializes it into <code>RolePermission</code> rows.
* '''Read detail''' (<code>RoleReadSpec.perform_extra_serialization</code>): sets <code>id = obj.external_id</code> and fills <code>permissions</code> from <code>obj.get_permissions_for_role()</code>, the cached <code>{name, slug, context, description}</code> list for every active (non-<code>temp_deleted</code>) grant.
* '''Read minimal''' (<code>RoleReadMinimalSpec.perform_extra_serialization</code>): sets <code>id = obj.external_id</code> and nothing else; <code>permissions</code> is omitted.

=== Permission resolution mixins ===

<code>care/emr/resources/permissions.py</code> defines mixins that other resource specs inherit to expose the '''calling user's''' effective permissions on an object — not the role's own permission list. They populate <code>mapping["permissions"]</code> in <code>perform_extra_user_serialization</code>, but only when an authenticated <code>user</code> is passed to <code>serialize</code>.

{| class="wikitable"
|-
! Mixin
! Resolves
! Context filter
|-
| <code>PermissionsMixin</code>
| base — adds <code>permissions: list[str]</code>
| —
|-
| <code>PatientPermissionsMixin</code>
| roles the user holds on a patient
| <code>permission__context in ("PATIENT", "FACILITY")</code>
|-
| <code>EncounterPermissionsMixin</code>
| roles the user holds on an encounter
| <code>permission__context in ("ENCOUNTER", "PATIENT")</code>
|-
| <code>FacilityPermissionsMixin</code>
| roles on facility root + sub-orgs; also exposes <code>root_org_permissions</code> and <code>child_org_permissions</code> (child set excludes <code>can_update_facility</code>)
| none (root) / excludes <code>can_update_facility</code> (child)
|}

== Methods & save behaviour ==

<code>RoleModel</code> resolves its effective permissions through two cached helpers backed by the Django cache (Redis) with a 7-day TTL:

* <code>get_permission_sk_for_role() → list[str]</code> — the <code>slug</code> of every active permission on the role. Cache key <code>role_permissions_cache:{id}</code>.
* <code>get_permissions_for_role() → list[dict]</code> — full detail (<code>name</code>, <code>slug</code>, <code>context</code>, <code>description</code>) for every active permission. Cache key <code>role_permissions:{id}</code>. Used by <code>RoleReadSpec</code>.

Both queries join through <code>RolePermission</code> and exclude <code>temp_deleted=True</code> grants.

=== Cache invalidation signal ===

<code>invalidate_role_permissions_cache</code>, a <code>@receiver([post_save, post_delete], sender=RolePermission)</code> handler, clears both cache keys for the affected <code>role_id</code> on every create, update, or delete of a <code>RolePermission</code>. ORM writes invalidate the cache automatically; raw SQL writes skip the signal and leave stale caches behind.

== API integration notes ==

* Both create and update go through <code>RoleCreateSpec</code>. <code>permissions</code> is required (≥ 1) and de-duplicated; you never set <code>is_system</code>, and <code>True</code> is rejected.
* Reads use <code>RoleReadSpec</code> (full, with nested <code>PermissionSpec[]</code>) or <code>RoleReadMinimalSpec</code> (no permissions), depending on the endpoint.
* To change a role's membership, write <code>RolePermission</code> rows rather than editing <code>RoleModel</code> directly. Use the ORM so the cache-invalidation signal fires; raw SQL leaves the Redis cache stale.
* Other access-control models (organization memberships, patient/encounter associations) reference roles to resolve a user's effective permissions in a given context.

{{Related}}

References/Role - Revision history

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

Admin: OHC identity seed