Skip to content

Commit fdb8b30

Browse files
john-d03john-d03
authored
Merge pull request #59 from ohcnetwork/docs/care-team-concept-flow-reference-7557d85a76a5abf8
[docs] Care team concept, flow, and reference
2 parents a073c80 + 4d1edb0 commit fdb8b30

8 files changed

Lines changed: 429 additions & 2 deletions

File tree

‎versioned_docs/version-3.0/concepts/clinical/care-team.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
sidebar_position: 15
3+
---
4+
5+
# Care team
6+
7+
## Definition
8+
9+
The **care team** of an [encounter](../clinical/encounter.mdx) is the list of users who look after the patient during that episode of care. Each member holds a practitioner role, such as a physician or a nurse. The first member in the list is the primary member, and Care shows that member on the encounter card and on printed documents. A care team belongs to one encounter, so a patient with two open encounters has two separate care teams.
10+
11+
## Key Attributes
12+
13+
| Components | What it captures |
14+
| --- | --- |
15+
| Member | The Care user who takes part in the episode of care. |
16+
| Role | The practitioner role of the member for this encounter, such as physician or nurse. |
17+
| Primary | The first member in the list. Care shows this member as the main contact for the encounter. |
18+
| Order | The position of each member in the list. The order sets which member is primary. |
19+
20+
### Member
21+
22+
You select a member in two steps. First you select a facility department. Then you select a user from that department. A user can appear only once in a care team. Care shows an error if you add the same user two times.
23+
24+
### Role
25+
26+
The role comes from the Practitioner Role value set. The value set holds the SNOMED CT healthcare professional and healthcare-related organization codes. You must select a role for each member.
27+
28+
The care team has no status of its own. It follows the encounter: when the encounter is complete, you can no longer change the care team.
29+
30+
## Permissions
31+
32+
Care controls the care team through the encounter, not through a separate permission of its own.
33+
34+
| Permission | Description | System Roles |
35+
| --- | --- | --- |
36+
| `can_read_encounter` | See the care team of an encounter. | Admin, Doctor, Nurse, Facility Admin |
37+
| `can_write_encounter` | Add a member, remove a member, or change the primary member. | Admin, Doctor, Nurse, Facility Admin |
38+
39+
Two more rules apply to a change:
40+
41+
- Care refuses the change when the encounter is in a completed state.
42+
- Care refuses a member who cannot see the encounter.
43+
44+
Users get these roles through their organization and facility memberships. Permissions cascade down the organization tree, so a role at a parent organization applies to the facilities and encounters below it.
45+
46+
## Related
47+
48+
- Concept: [Encounter](../clinical/encounter.mdx)
49+
- Concept: [Patient](../clinical/patient)
50+
- Flow: [Manage the care team of an encounter](../../flows/clinical/manage-encounter-care-team.mdx)
51+
- Reference: [Care team](../../references/clinical/care-team.mdx)
52+
- Reference: [Encounter](../../references/clinical/encounter.mdx)

‎versioned_docs/version-3.0/flows/clinical/manage-encounter-care-team.mdx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# How to manage the care team of an encounter
6+
7+
## Overview
8+
9+
This flow describes how to add, remove, and order the members of the [care team](../../concepts/clinical/care-team.mdx) of an [encounter](../../concepts/clinical/encounter.mdx).
10+
11+
## Pre-requisites
12+
13+
- The patient is registered in Care.
14+
- The encounter is open at your facility. You cannot change the care team of a completed encounter.
15+
- Each user that you add is a member of a department in the same facility.
16+
- Each user that you add can see the encounter.
17+
- You have the permissions listed below.
18+
19+
## Permissions
20+
21+
| Permission | Access |
22+
| --- | --- |
23+
| Can Read encounter | See the care team of the encounter. |
24+
| Update Encounter non clinical | Add a member, remove a member, or change the primary member. |
25+
26+
Without the update permission, Care shows the care team as read-only. The title of the panel is then **View Care Team**.
27+
28+
## Steps
29+
30+
### 1. Open the encounter
31+
32+
Go to the facility, and select the patient encounter that you want to change. The encounter opens on the **Updates** tab.
33+
34+
### 2. Open the care team panel
35+
36+
Find the **Manage Care Team** panel in the summary panel of the encounter. Select the edit icon. Care opens the care team sheet.
37+
38+
You can also open the sheet from the command dialog. Press `Shift + E` to open the command dialog, then select **Manage Care Team**.
39+
40+
### 3. Select the department
41+
42+
Select a facility department in the organization selector at the top of the sheet. Care then shows the users of that department.
43+
44+
### 4. Add a member
45+
46+
| Components | What it captures |
47+
| --- | --- |
48+
| Member | The user that you add to the care team. Use **Select Member**. |
49+
| Role | The practitioner role of the member. Use **Select Role**. |
50+
51+
Select **Add**. Care adds the member and shows the message "Member added successfully".
52+
53+
:::note
54+
A user can be in the care team only one time. If the user is already a member, Care shows the message "Member already added".
55+
:::
56+
57+
### 5. Set the primary member
58+
59+
Care marks the first member in the list with the **Primary** badge. To make a different member primary, select **Mark as Primary** on that member. Care moves the member to the top of the list.
60+
61+
### 6. Remove a member
62+
63+
Select the remove action on the member, then confirm the action. Care shows the message "Member removed successfully".
64+
65+
## Expected Outcome
66+
67+
- The care team of the encounter holds the members that you selected, each with a practitioner role.
68+
- The primary member is at the top of the list, and Care shows that member on the encounter card.
69+
- The encounter is now in the encounter list of each member of the care team.
70+
71+
## Related
72+
73+
Concepts:
74+
75+
- [Care team](../../concepts/clinical/care-team.mdx)
76+
- [Encounter](../../concepts/clinical/encounter.mdx)
77+
- [Patient](../../concepts/clinical/patient)

‎versioned_docs/version-3.0/references/clinical/care-team.mdx‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
sidebar_position: 15
3+
---
4+
5+
# Care team
6+
7+
Technical reference for the encounter care team in Care EMR. See the [care team concept](../../concepts/clinical/care-team.mdx) for the plain-language view.
8+
9+
**Source:**
10+
- Model: [`care/emr/models/encounter.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/models/encounter.py)
11+
- Specs: [`care/emr/resources/encounter/spec.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/encounter/spec.py) · [`valueset.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/encounter/valueset.py)
12+
- Viewset: [`care/emr/api/viewsets/encounter.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/encounter.py)
13+
14+
The care team has no model of its own. It is stored on the `Encounter` model as an opaque `JSONField`, and the real shape lives in the Pydantic specs. The write path is a dedicated action on the encounter viewset, not the encounter create or update schema.
15+
16+
## Models
17+
18+
| Model | Purpose |
19+
| --- | --- |
20+
| `Encounter` | Owns the care team through the `care_team` and `care_team_users` fields |
21+
22+
`Encounter` extends [`EMRBaseModel`](../foundation/base-model.mdx).
23+
24+
## `Encounter` care team fields
25+
26+
| Field | Type | Notes |
27+
| --- | --- | --- |
28+
| `care_team` | `JSONField` | Default `{}`. Stored as a list of `{ "user_id": int, "role": Coding }` entries. Excluded from `EncounterCreateSpec` and `EncounterUpdateSpec` |
29+
| `care_team_users` | `ArrayField[int]` | Denormalized cache of the internal user IDs in `care_team`. Platform-maintained |
30+
31+
The stored `user_id` is the internal integer primary key of `User`. The API accepts and returns the `external_id` (UUID) instead.
32+
33+
### Stored shape
34+
35+
```text
36+
care_team: [
37+
{
38+
"user_id": int, # internal User pk
39+
"role": Coding { system, code, display }
40+
}
41+
]
42+
```
43+
44+
## Resource specs (API schema)
45+
46+
| Spec | Role |
47+
| --- | --- |
48+
| `EncounterCareTeamMemberSpec` | write · one member: `user_id: UUID4`, `role: ValueSetBoundCoding[system-practitioner-role-code]` |
49+
| `EncounterCareTeamMemberWriteSpec` | write · the full replacement list: `members: list[EncounterCareTeamMemberSpec]` |
50+
| `EncounterListSpec` | read · list. Serializes `care_team` as `[{ "member": UserSpec, "role": Coding }]` |
51+
| `EncounterRetrieveSpec` | read · detail. Same `care_team` serialization as the list spec |
52+
53+
On read, each member is expanded from the cached `UserSpec` for the stored `user_id`. The list order of `care_team` is preserved, so the first entry is the primary member.
54+
55+
### `PRACTITIONER_ROLE_VALUESET`
56+
57+
`role` is bound to the system value set with slug `system-practitioner-role-code`. It composes two SNOMED CT `is-a` filters:
58+
59+
| Concept | Meaning |
60+
| --- | --- |
61+
| `223366009` | Healthcare professional |
62+
| `224930009` | Healthcare related organization |
63+
64+
## API integration notes
65+
66+
- Write endpoint: `POST /api/v1/encounter/{external_id}/set_care_team_members/`. The body is `EncounterCareTeamMemberWriteSpec`, and the response is `EncounterRetrieveSpec` in the schema.
67+
- The write is a **full replacement**. Send the complete member list on every call. To remove a member, send the list without that member. To change the primary member, send the list with that member first.
68+
- `set_care_team_members` calls `authorize_update`, which resolves to `can_update_encounter_obj`. That check returns `False` when the encounter status is in `COMPLETED_CHOICES`, so a closed encounter rejects the write.
69+
- Each member in the body is checked with `can_view_encounter_obj`. A member who cannot view the encounter causes a `PermissionDenied`.
70+
- A repeated `user_id` in the body causes a `ValidationError` with `{"user": "repeats are not allowed"}`.
71+
- Filtering: the encounter list supports `care_team_user=<username>`, which resolves the username to a user ID and matches it against `care_team_users`.
72+
73+
## Methods & save behaviour
74+
75+
- `Encounter.sync_care_team_users_cache()` rebuilds `care_team_users` from `care_team`. `Encounter.save()` calls it on every save, so the cache never drifts from the JSON field.
76+
- `sync_care_team_users_cache()` only rebuilds the cache when `care_team` is a list. The model default is a dict, so an encounter with no care team keeps an empty cache.
77+
- `set_care_team_members` saves with `update_fields=["care_team", "care_team_users", "updated_by", "modified_date"]`.
78+
79+
## Related
80+
81+
- Concept: [Care team](../../concepts/clinical/care-team.mdx)
82+
- Reference: [Encounter](../clinical/encounter.mdx)
83+
- Reference: [User](../access-governance/user.mdx)
84+
- Flow: [How to manage the care team of an encounter](../../flows/clinical/manage-encounter-care-team.mdx)

‎versioned_docs/version-3.1/concepts/clinical/care-team.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
sidebar_position: 15
3+
---
4+
5+
# Care team
6+
7+
## Definition
8+
9+
The **care team** of an [encounter](../clinical/encounter.mdx) is the list of users who look after the patient during that episode of care. Each member holds a practitioner role, such as a physician or a nurse. The first member in the list is the primary member, and Care shows that member on the encounter card and on printed documents. A care team belongs to one encounter, so a patient with two open encounters has two separate care teams.
10+
11+
## Key Attributes
12+
13+
| Components | What it captures |
14+
| --- | --- |
15+
| Member | The Care user who takes part in the episode of care. |
16+
| Role | The practitioner role of the member for this encounter, such as physician or nurse. |
17+
| Primary | The first member in the list. Care shows this member as the main contact for the encounter. |
18+
| Order | The position of each member in the list. The order sets which member is primary. |
19+
20+
### Member
21+
22+
You select a member in two steps. First you select a facility department. Then you select a user from that department. A user can appear only once in a care team. Care shows an error if you add the same user two times.
23+
24+
### Role
25+
26+
The role comes from the Practitioner Role value set. The value set holds the SNOMED CT healthcare professional and healthcare-related organization codes. You must select a role for each member.
27+
28+
The care team has no status of its own. It follows the encounter: when the encounter is complete, you can no longer change the care team.
29+
30+
## Permissions
31+
32+
Care controls the care team through the encounter, not through a separate permission of its own.
33+
34+
| Permission | Description | System Roles |
35+
| --- | --- | --- |
36+
| `can_read_encounter` | See the care team of an encounter. | Admin, Doctor, Nurse, Facility Admin |
37+
| `can_write_encounter` | Add a member, remove a member, or change the primary member. | Admin, Doctor, Nurse, Facility Admin |
38+
39+
Two more rules apply to a change:
40+
41+
- Care refuses the change when the encounter is in a completed state.
42+
- Care refuses a member who cannot see the encounter.
43+
44+
Users get these roles through their organization and facility memberships. Permissions cascade down the organization tree, so a role at a parent organization applies to the facilities and encounters below it.
45+
46+
## Related
47+
48+
- Concept: [Encounter](../clinical/encounter.mdx)
49+
- Concept: [Patient](../clinical/patient)
50+
- Flow: [Manage the care team of an encounter](../../flows/clinical/manage-encounter-care-team.mdx)
51+
- Reference: [Care team](../../references/clinical/care-team.mdx)
52+
- Reference: [Encounter](../../references/clinical/encounter.mdx)

‎versioned_docs/version-3.1/flows/clinical/manage-encounter-care-team.mdx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# How to manage the care team of an encounter
6+
7+
## Overview
8+
9+
This flow describes how to add, remove, and order the members of the [care team](../../concepts/clinical/care-team.mdx) of an [encounter](../../concepts/clinical/encounter.mdx).
10+
11+
## Pre-requisites
12+
13+
- The patient is registered in Care.
14+
- The encounter is open at your facility. You cannot change the care team of a completed encounter.
15+
- Each user that you add is a member of a department in the same facility.
16+
- Each user that you add can see the encounter.
17+
- You have the permissions listed below.
18+
19+
## Permissions
20+
21+
| Permission | Access |
22+
| --- | --- |
23+
| Can Read encounter | See the care team of the encounter. |
24+
| Update Encounter non clinical | Add a member, remove a member, or change the primary member. |
25+
26+
Without the update permission, Care shows the care team as read-only. The title of the panel is then **View Care Team**.
27+
28+
## Steps
29+
30+
### 1. Open the encounter
31+
32+
Go to the facility, and select the patient encounter that you want to change. The encounter opens on the **Updates** tab.
33+
34+
### 2. Open the care team panel
35+
36+
Find the **Manage Care Team** panel in the summary panel of the encounter. Select the edit icon. Care opens the care team sheet.
37+
38+
You can also open the sheet from the command dialog. Press `Shift + E` to open the command dialog, then select **Manage Care Team**.
39+
40+
### 3. Select the department
41+
42+
Select a facility department in the organization selector at the top of the sheet. Care then shows the users of that department.
43+
44+
### 4. Add a member
45+
46+
| Components | What it captures |
47+
| --- | --- |
48+
| Member | The user that you add to the care team. Use **Select Member**. |
49+
| Role | The practitioner role of the member. Use **Select Role**. |
50+
51+
Select **Add**. Care adds the member and shows the message "Member added successfully".
52+
53+
:::note
54+
A user can be in the care team only one time. If the user is already a member, Care shows the message "Member already added".
55+
:::
56+
57+
### 5. Set the primary member
58+
59+
Care marks the first member in the list with the **Primary** badge. To make a different member primary, select **Mark as Primary** on that member. Care moves the member to the top of the list.
60+
61+
### 6. Remove a member
62+
63+
Select the remove action on the member, then confirm the action. Care shows the message "Member removed successfully".
64+
65+
## Expected Outcome
66+
67+
- The care team of the encounter holds the members that you selected, each with a practitioner role.
68+
- The primary member is at the top of the list, and Care shows that member on the encounter card.
69+
- The encounter is now in the encounter list of each member of the care team.
70+
71+
## Related
72+
73+
Concepts:
74+
75+
- [Care team](../../concepts/clinical/care-team.mdx)
76+
- [Encounter](../../concepts/clinical/encounter.mdx)
77+
- [Patient](../../concepts/clinical/patient)

0 commit comments

Comments
 (0)