Skip to content

Commit 4044960

Browse files
github-actions[bot]Copilot
github-actions[bot]
and
Copilot
authored
docs: add responsibility concept, reference, and flows
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent fdb8b30 commit 4044960

14 files changed

Lines changed: 756 additions & 3 deletions

File tree

‎versioned_docs/version-3.0/concepts/access-governance/responsibility.mdx‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
sidebar_position: 5
3+
---
4+
5+
# Responsibility
6+
7+
## Definition
8+
9+
A **responsibility** in Care is a named group of staff, such as Doctors, Nurses, Technicians, or Volunteers. It records the designation that a user holds in that group, and it groups people for work that follows a designation instead of a place. A responsibility is one type of [organization](../access-governance/organization.mdx). It is flat: a responsibility has no child organizations.
10+
11+
A responsibility answers "which group of staff is this person part of, and as what?". A governance organization answers "which place or administrative boundary does this person belong to?".
12+
13+
## Key Attributes
14+
15+
| Components | What it captures |
16+
| --- | --- |
17+
| Name | The name of the responsibility, such as Doctors or Volunteers. |
18+
| Description | What the responsibility is used for. Optional. |
19+
| Managing Responsibilities | The responsibilities that govern this one. |
20+
| Managed Responsibilities | The responsibilities that this one can govern. |
21+
| Members | The users assigned to the responsibility, each with one designation. |
22+
23+
### Designation
24+
25+
Every member of a responsibility holds one **designation**. Care ships three designations for responsibilities:
26+
27+
| Designation | What the member can do |
28+
| --- | --- |
29+
| Admin | Manage the responsibility, and manage its members. |
30+
| Manager | List members, and manage members of the responsibilities that this one governs. |
31+
| Member | View the responsibility. |
32+
33+
A designation is a [role](../../references/access-governance/role.mdx) with the Responsibility context. Care keeps these designations separate from facility and government organization roles. A designation gives no clinical access on its own.
34+
35+
### Governance links
36+
37+
Responsibilities are flat, but they are not isolated. One responsibility can govern another. Care calls the two directions **Managing Responsibilities** and **Managed Responsibilities**.
38+
39+
A governance link lets an Admin or a Manager of the governing responsibility manage the members of the responsibility below it. A responsibility cannot manage itself.
40+
41+
:::note
42+
A responsibility is not a permission bundle. A designation names what a person is in the group. A role in a facility or a government organization decides what a person can do with patients and records. See [Roles and permissions](../access-governance/access-control.mdx).
43+
:::
44+
45+
## Related
46+
47+
- Flow: [Create a responsibility](../../flows/access-governance/create-a-responsibility.mdx)
48+
- Flow: [Assign a user to a responsibility](../../flows/access-governance/assign-a-user-to-a-responsibility.mdx)
49+
- Flow: [Link responsibilities for governance](../../flows/access-governance/link-responsibilities-for-governance.mdx)
50+
- Concept: [Organization](../access-governance/organization.mdx) · [Roles and permissions](../access-governance/access-control.mdx) · [User](../access-governance/user.mdx)
51+
- Reference: [Organization](../../references/access-governance/organization.mdx) · [Role](../../references/access-governance/role.mdx)

‎versioned_docs/version-3.0/flows/access-governance/_category_.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"label": "Access & Governance",
3+
"position": 2,
4+
"key": "access-governance-flows"
5+
}

‎versioned_docs/version-3.0/flows/access-governance/assign-a-user-to-a-responsibility.mdx‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# How to assign a user to a responsibility
6+
7+
## Overview
8+
9+
This flow describes how to add a user to a [responsibility](../../concepts/access-governance/responsibility.mdx), and how to give that user a designation in the group.
10+
11+
## Pre-requisites
12+
13+
- The responsibility exists in Care.
14+
- The user has an account in Care. If the user has no account, create the account first.
15+
- You are an Admin of the responsibility, or an Admin or a Manager of a responsibility that governs it.
16+
- You have the permissions listed below.
17+
18+
## Permissions
19+
20+
| Permission | Access |
21+
| --- | --- |
22+
| Can List Users in an Organizations | See the members of the responsibility. |
23+
| Can Manage Users in an Organization | Add a member, change a designation, and remove a member. |
24+
| Can Manage Connected Role Organizations | Do the same for the responsibilities that your responsibility governs. |
25+
26+
:::note
27+
You can grant only a designation that your own designation already covers. You cannot remove a member whose access is above your own.
28+
:::
29+
30+
## Steps
31+
32+
### 1. Open the responsibility
33+
34+
Select the responsibility in the sidebar switcher. Care opens the responsibility and shows its members.
35+
36+
You can also open the responsibility from the responsibility directory in the administration menu.
37+
38+
### 2. Open the users list
39+
40+
Select **Users**. Care lists the current members and the designation of each one.
41+
42+
### 3. Link the user
43+
44+
Select **Link User**. Care opens a panel titled **Link User to Organization**.
45+
46+
| Components | What it captures |
47+
| --- | --- |
48+
| User | The account that you add. Search for the user by username. |
49+
| Role | The designation that the user holds in the group. Use **Select Role**. |
50+
51+
Select **Link to Organization**. Care adds the member and shows the message "User added to organization successfully".
52+
53+
### 4. Change a designation
54+
55+
To change the designation of a member, select **Edit** on the member card. Select a different designation, then save the change. Care shows the message "User role updated successfully".
56+
57+
Use the same panel to remove the member from the responsibility.
58+
59+
## Expected Outcome
60+
61+
- The user appears in the members list of the responsibility, with the designation that you selected.
62+
- The responsibility appears in the sidebar switcher of that user.
63+
64+
## Related
65+
66+
Concepts:
67+
68+
- [Responsibility](../../concepts/access-governance/responsibility.mdx)
69+
- [User](../../concepts/access-governance/user.mdx)
70+
- [Roles and permissions](../../concepts/access-governance/access-control.mdx)
71+
72+
Flows:
73+
74+
- [Create a responsibility](./create-a-responsibility.mdx)
75+
- [Link responsibilities for governance](./link-responsibilities-for-governance.mdx)

‎versioned_docs/version-3.0/flows/access-governance/create-a-responsibility.mdx‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# How to create a responsibility
6+
7+
## Overview
8+
9+
This flow describes how to create a [responsibility](../../concepts/access-governance/responsibility.mdx) — a named group of staff such as Doctors, Nurses, or Volunteers.
10+
11+
## Pre-requisites
12+
13+
- You sign in to Care as a superadmin. Only a superadmin can create, rename, or delete a responsibility.
14+
- You know the name of the group that you want to create. The name must be unique.
15+
16+
## Permissions
17+
18+
| Permission | Access |
19+
| --- | --- |
20+
| Superadmin | Create, rename, and delete a responsibility. |
21+
22+
:::note
23+
No system role grants this action. Care rejects the request from every non-superadmin account.
24+
:::
25+
26+
## Steps
27+
28+
### 1. Open the responsibility workspace
29+
30+
Select **Organizations** in the administration menu. Then select **Responsibilities**. Care shows the responsibility directory on the left, and the details panel on the right.
31+
32+
### 2. Start a new responsibility
33+
34+
Select **Create Responsibility**. Care opens a panel titled **Create Responsibility**.
35+
36+
### 3. Enter the details
37+
38+
| Components | What it captures |
39+
| --- | --- |
40+
| Name | The name of the group, such as Doctors. Required. |
41+
| Description | What the responsibility is used for. Optional. |
42+
43+
### 4. Save the responsibility
44+
45+
Select **Create Responsibility** at the bottom of the panel. Care creates the group and shows the message "Organization created successfully".
46+
47+
## Expected Outcome
48+
49+
- The new responsibility appears in the responsibility directory.
50+
- You can now assign users to it, and link it to other responsibilities for governance.
51+
52+
## Related
53+
54+
Concepts:
55+
56+
- [Responsibility](../../concepts/access-governance/responsibility.mdx)
57+
- [Organization](../../concepts/access-governance/organization.mdx)
58+
59+
Flows:
60+
61+
- [Assign a user to a responsibility](./assign-a-user-to-a-responsibility.mdx)
62+
- [Link responsibilities for governance](./link-responsibilities-for-governance.mdx)

‎versioned_docs/version-3.0/flows/access-governance/link-responsibilities-for-governance.mdx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# How to link responsibilities for governance
6+
7+
## Overview
8+
9+
This flow describes how to connect one [responsibility](../../concepts/access-governance/responsibility.mdx) to another, so that the members of the governing group can manage the members of the group below it.
10+
11+
## Pre-requisites
12+
13+
- Both responsibilities exist in Care.
14+
- You can manage both responsibilities. A superadmin, or an Admin of both groups, can make the link.
15+
- You have the permissions listed below.
16+
17+
## Permissions
18+
19+
| Permission | Access |
20+
| --- | --- |
21+
| Can Manage Organizations | Add or remove a governance link. Care checks this permission on both responsibilities. |
22+
23+
## Steps
24+
25+
### 1. Open the responsibility
26+
27+
Select **Organizations** in the administration menu. Then select **Responsibilities**. Select the responsibility that you want to change.
28+
29+
### 2. Open the governance panel
30+
31+
Find the **Governance** section of the details panel. Care shows two lists:
32+
33+
| Components | What it captures |
34+
| --- | --- |
35+
| Managing Responsibilities | The responsibilities that govern this one. |
36+
| Managed Responsibilities | The responsibilities that this one can govern. |
37+
38+
### 3. Add a managing responsibility
39+
40+
Select a responsibility in **Add Managing Organization**. Then select **Add**. Care creates the link and shows the message "Managing organization added successfully".
41+
42+
### 4. Add a managed responsibility
43+
44+
Select a responsibility in **Add Managed Responsibility**. Then select **Add**. Care creates the link and shows the message "Managed responsibility added successfully".
45+
46+
:::note
47+
A responsibility cannot manage itself. Care shows the message "A responsibility cannot manage itself".
48+
:::
49+
50+
### 5. Remove a link
51+
52+
Select the remove icon next to the responsibility in either list. Care removes the link.
53+
54+
## Expected Outcome
55+
56+
- The two responsibilities appear in each other's governance lists.
57+
- An Admin or a Manager of the governing responsibility can now list and manage the members of the governed responsibility.
58+
59+
## Related
60+
61+
Concepts:
62+
63+
- [Responsibility](../../concepts/access-governance/responsibility.mdx)
64+
- [Organization](../../concepts/access-governance/organization.mdx)
65+
66+
Flows:
67+
68+
- [Create a responsibility](./create-a-responsibility.mdx)
69+
- [Assign a user to a responsibility](./assign-a-user-to-a-responsibility.mdx)

‎versioned_docs/version-3.0/references/access-governance/responsibility.mdx‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
sidebar_position: 6
3+
---
4+
5+
# Responsibility
6+
7+
Technical reference for the **responsibility** — the `role` organization type of the `Organization` model in Care EMR. See the [Responsibility](../../concepts/access-governance/responsibility.mdx) concept for the plain-language layer, and the [Organization](../access-governance/organization.mdx) reference for the full model.
8+
9+
**Source:**
10+
11+
- [`care/emr/models/organization.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/models/organization.py)
12+
- [`care/emr/resources/organization/spec.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/organization/spec.py)
13+
- [`care/emr/resources/organization/organization_user_spec.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/organization/organization_user_spec.py)
14+
- [`care/emr/api/viewsets/organization.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/organization.py)
15+
- [`care/security/authorization/organization.py`](https://github.com/ohcnetwork/care/blob/develop/care/security/authorization/organization.py)
16+
- [`care/security/permissions/organization.py`](https://github.com/ohcnetwork/care/blob/develop/care/security/permissions/organization.py)
17+
- [`care/security/roles/role.py`](https://github.com/ohcnetwork/care/blob/develop/care/security/roles/role.py)
18+
19+
A responsibility has no model of its own. It is an `Organization` row whose `org_type` is `role`, one of the four values of `OrganizationTypeChoices` (`team`, `govt`, `role`, `product_supplier`). The behaviour that makes it a responsibility comes from the viewset, the authorization handler, and the role contexts.
20+
21+
## Distinguishing fields
22+
23+
| Field | Type | Behaviour for `org_type = "role"` |
24+
| --- | --- | --- |
25+
| `org_type` | `CharField(255)` | Fixed to `role`. Writes bind to `OrganizationTypeChoices` |
26+
| `parent` | `FK(self), nullable` | Always null. `authorize_create` rejects any organization created under a `role` organization |
27+
| `has_children` | `BooleanField` | Always `False`. Responsibilities are flat |
28+
| `managing_organizations` | `ArrayField[int]` | Internal ids of the responsibilities that govern this one. Only `role` organizations may appear here |
29+
| `name` | `CharField(255)` | Unique among siblings, enforced by `Organization.validate_uniqueness` |
30+
| `description` | `TextField, nullable` | Free text. Defaults to `""` in the spec |
31+
32+
`OrganizationRetrieveSpec` expands `managing_organizations` to nested `OrganizationReadSpec` JSON, and adds the caller's `permissions`.
33+
34+
## Membership
35+
36+
Membership is an `OrganizationUser` row: `organization` + `user` + `role`. For a responsibility, that `role` is the member's designation.
37+
38+
```text
39+
OrganizationUser
40+
organization -> Organization (org_type = "role")
41+
user -> users.User
42+
role -> security.RoleModel (contexts contains ROLE_ORG)
43+
```
44+
45+
`OrganizationUser.save()` clears `User.cached_role_orgs` whenever the linked organization is of type `role`, so the user's cached responsibility list rebuilds on the next read. `User.get_cached_role_orgs()` repopulates it from `OrganizationUser.get_cached_role_orgs(user_id)`, which serializes each membership with `OrganizationUserExtendedReadSpec`. `UserSpec` and `UserRetrieveSpec` expose the result as `role_orgs`.
46+
47+
`UserCreateSpec` accepts `role_orgs: list[UserRoleOrgCreateSpec]` (each `{ organization, role }`). `UserViewSet.perform_create` creates the memberships inside the same transaction, rejects any organization whose `org_type` is not `role`, and authorizes each pair through `can_manage_organization_users_obj`.
48+
49+
## Designation roles
50+
51+
`RoleModel.contexts` is an `ArrayField` of `RoleContext` values: `FACILITY`, `GOVT_ORG`, `ROLE_ORG`. Only roles carrying `ROLE_ORG` are selectable as designations. `RoleController.internal_roles` defines three:
52+
53+
| Role constant | Name | Description |
54+
| --- | --- | --- |
55+
| `ROLE_ORGANIZATION_ADMIN_ROLE` | Admin | Administrator of a role organization |
56+
| `ROLE_ORGANIZATION_MANAGER_ROLE` | Manager | Manager of a role organization |
57+
| `ROLE_ORGANIZATION_MEMBER_ROLE` | Member | Member of a role organization |
58+
59+
## Authorization
60+
61+
The `OrganizationViewSet` treats responsibilities differently from other organization types:
62+
63+
| Action | Behaviour |
64+
| --- | --- |
65+
| create | `authorize_create` raises `PermissionDenied` for `org_type` in `govt`, `role` unless the caller is a superuser |
66+
| update | `authorize_update` raises `PermissionDenied` for `org_type` in `govt`, `role` unless the caller is a superuser |
67+
| destroy | `authorize_destroy` raises `PermissionDenied` for `org_type` in `govt`, `role` unless the caller is a superuser, and for any organization that still has children |
68+
| retrieve | `get_queryset` returns the unfiltered queryset when the requested organization is of type `role` |
69+
| `managing_organization` | Both the target and the requested organization must be of type `role`. The caller needs `can_manage_organization_obj` on both |
70+
| `accessible_role_organizations` | See below |
71+
72+
`OrganizationAccess.can_list_organization_users_obj` and `can_manage_organization_users_obj` widen the search set for a `role` organization from `[*parent_cache, id]` to `[id, *managing_organizations]`. `can_manage_organization_users_obj` therefore passes when the caller holds `can_manage_organization_users` on the responsibility itself, **or** `can_manage_connected_role_organizations` on one of its managing responsibilities. `check_role_subset` still applies: the requested designation must be a subset of the caller's own permissions.
73+
74+
### Permission slugs
75+
76+
| Permission | Roles |
77+
| --- | --- |
78+
| `can_view_organization` | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (responsibility), Manager (responsibility), Member (responsibility) |
79+
| `can_manage_organization` | Admin, Admin (responsibility) |
80+
| `can_list_organization_users` | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (responsibility), Manager (responsibility) |
81+
| `can_manage_organization_users` | Admin, Administrator, Facility Admin, Admin (responsibility) |
82+
| `can_manage_connected_role_organizations` | Admin (responsibility), Manager (responsibility) |
83+
84+
### `accessible_role_organizations`
85+
86+
`GET /api/v1/organization/accessible_role_organizations/` returns `{ count, results }`, where each result is `{ role, organization }`. The set is:
87+
88+
- every `role` organization the caller is a member of, with `role` set to the caller's designation, and
89+
- every `role` organization governed by a responsibility where the caller holds `can_manage_connected_role_organizations`, with `role` set to `null` when the caller is not a member.
90+
91+
Superusers receive every `role` organization.
92+
93+
## API integration notes
94+
95+
- Responsibilities use the standard organization endpoints under `/api/v1/organization/`, filtered with `org_type=role`.
96+
- Governance links are written through `POST /api/v1/organization/{id}/managing_organization/` with `{ organization, action }`, where `action` is `add` or `remove`. The body's `organization` is the managing responsibility, and `{id}` is the managed one.
97+
- Members are read and written through `/api/v1/organization/{id}/users/`.
98+
- `role_orgs` on the user read specs is a cached, denormalized list. Treat it as read-only.
99+
100+
## Related
101+
102+
- Concept: [Responsibility](../../concepts/access-governance/responsibility.mdx)
103+
- Reference: [Organization](../access-governance/organization.mdx) · [Role](../access-governance/role.mdx) · [User](../access-governance/user.mdx) · [Permission](../access-governance/permission.mdx)

0 commit comments

Comments
 (0)