Merge pull request #78 from ohcnetwork/docs/facility-department-location

Add Department and Location docs for 3.1

Author: aravindm4

versioned_docs/version-3.1/concepts/facility/department.mdx

@@ -0,0 +1,52 @@
+---
+sidebar_position: 2
+---
+
+# Department
+
+## Definition
+
+A **[department](https://build.fhir.org/organization.html)** in Care is a group inside a facility, such as a ward, a clinical team, or an administrative unit. A department can hold sub-departments, so the departments of a facility form a hierarchy. Care models a department on the FHIR Organization resource.
+
+Note: Care creates one root department named Administration for every new facility. You cannot create, edit, or delete this root department from the settings screens. You also cannot create a department under it. The person who creates the facility becomes the Facility Admin of the root department.
+
+Note: Your deployment sets the maximum nesting depth and the maximum number of departments for each facility.
+
+## Key Attributes
+
+| Components | What it captures |
+| --- | --- |
+| Name | The name of the department. This is required. |
+| Description | A description of the department. This is optional. |
+| Type | The kind of department. Select Department or Team. |
+| Parent department | The department that this department sits under. A department with no parent is a top-level department in the facility. |
+| Active | Whether the department is active. |
+
+### Type
+
+Type records the kind of department. You select the type when you create the department, and you can change it later. Care offers these two values:
+
+- Department
+- Team
+
+Note: Care keeps other department types for its own use, such as the root Administration department. Care does not offer these types on the department settings screens.
+
+## Permissions
+
+| Permission | What it allows |
+| --- | --- |
+| Can Create Facility Organizations | Create a new department. The Facility Admin role holds this permission. |
+| Can Manage Facility Organizations | Edit the name, description, and type of a department. The Facility Admin and Administrator roles hold this permission. |
+| Can Delete Facility Organizations | Delete a department. The Facility Admin role holds this permission. |
+| Can List Users in a Facility Organizations | See the members of a department. The Facility Admin, Admin, Staff, Doctor, Administrator, and Nurse roles hold this permission. |
+| Can Manage Users in a Facility Organization | Add a member to a department, remove a member from it, or change the role of a member in it. The Facility Admin and Administrator roles hold this permission. |
+
+Note: A role that you grant on a department also applies to the sub-departments of that department.
+
+## Related
+
+- Flow: [Create a department](../../flows/facility/department/create-department.mdx)
+- Flow: [Update a department](../../flows/facility/department/update-department.mdx)
+- Flow: [Add users to a department](../../flows/facility/department/add-users-to-department.mdx)
+- Flow: [Delete a department](../../flows/facility/department/delete-department.mdx)
+- Concept: [Facility](../../concepts/facility/facility.mdx)

versioned_docs/version-3.1/concepts/facility/location.mdx

@@ -2,77 +2,98 @@
 sidebar_position: 4
 ---
 
-# Location
+# Locations
 
-A **location** is a physical place inside a facility where care happens or resources sit — a building, a wing, a ward, a room, or a single bed. Locations form a nested tree that mirrors the real geography of your facility, so the platform can answer questions like "which bed is this patient in?" and "who is allowed into this ward?".
+## Definition
 
-## What it represents
+A **[location](https://build.fhir.org/location.html)** in Care is a physical place inside a facility. A location can be a building, a ward, a room, or a bed. Locations sit inside one another and form a hierarchy. For example, a building contains wards, a ward contains rooms, and a room contains beds.
 
-In Care's FHIR-aligned model, a location maps to the **Location** resource. Each location records:
+## Key Attributes
 
-- **What kind of place it is** — a name, a description, and a physical form such as ward, room, or bed
-- **Where it sits in the tree** — its parent and children, since every place can nest inside a larger one and hold smaller ones, with no fixed limit on depth
-- **Whether it is usable** — and, for beds and rooms, a finer operational state (occupied, unoccupied, housekeeping, contaminated, isolated, closed)
-- **Who is in it** — the encounter, if any, currently occupying the place (most meaningful for a bed)
-- **Who may work there** — the organizations granted access to this part of the facility
+| Components | What it captures |
+| --- | --- |
+| Name | The name of the location. You must enter a name. |
+| Description | A description of the location. This is optional. |
+| Location Form | The type of place that the location represents. You must choose a Location Form when you create the location. You cannot change it later. |
+| Status | The state of the location. You must choose a status. |
+| Operational Status | The current use of the location. You must choose an operational status. |
+| Parent location | The location that this location sits under in the hierarchy. You set the parent location when you create the location. |
+| Order among siblings | The position of the location among the locations under the same parent location. |
+| Organizations | The facility departments that you link to the location. |
+| Availability | Whether the location is Available or Reserved. |
+| Current Encounter | The encounter of the patient who uses this location now. |
 
-A location is a *place*, not a *department* or a *team*. A ward as a physical space is a location; the unit of staff and responsibility that runs it is an [organization](../access-governance/organization.mdx). The two are linked, but they are different primitives — you nest places inside places, and you grant an organization access to a place.
+### Location Form
 
-## Classification
+The Location Form tells Care what type of place the location is. Choose one of these forms:
 
-Two attributes describe what a location *is*, and they are fixed when it is created.
+- Site
+- Building
+- Wing
+- Ward
+- Level
+- Corridor
+- Room
+- Bed
+- Vehicle
+- House
+- Cabinet
+- Road
+- Area
+- Jurisdiction
+- Virtual
 
-- **Mode** separates a *kind* of place from a concrete *instance* of one. A `kind` is a class of location — "a ward", "a building" — and can contain children. An `instance` is one specific place — "Bed 12", "Room 4" — and is a leaf: instances cannot have children.
-- **Form** is the physical type, drawn from a standard FHIR list: site, building, wing, ward, level, corridor, room, bed, vehicle, house, and more. This is what lets a deployment model the difference between a wing and the beds inside it.
+### Parent location and hierarchy
 
-Beds are not a separate concept in Care — a bed is simply a location whose form is `bed` and whose mode is `instance`. The whole facility map, from building down to bed, is one uniform tree.
+A location with no parent location is a top-level location for the facility. Only some Location Forms can hold child locations. A Ward can hold child locations. A Bed cannot hold child locations.
 
-## Lifecycle
+Note: You must choose a parent location before you create a Bed.
 
-A location's own status is deliberately simple — it describes whether the place exists and is usable, not whether someone is in it.
+Note: Your deployment sets the limit for the depth of the hierarchy. Your deployment also sets the limit for the total number of locations in one facility.
 
-```text
-active → inactive
-        (unknown)
-```
+You can change the order of the locations under the same parent location. See [Reorder locations](../../flows/facility/location/reorder-locations.mdx).
 
-- **active** — the location is live and can be used for encounters and assignments
-- **inactive** — retired from routine use but kept for history; it does not disappear
-- **unknown** — status has not been determined
+### Organizations
 
-Separately, beds and rooms carry an **operational status** that changes far more often: occupied, unoccupied, housekeeping, contaminated, isolated, or closed. This is the day-to-day signal a bed-management board reads, and it is distinct from the location simply being `active`.
+Organizations are the facility departments that you link to the location. The linked departments control which members can access the location. See [Manage a location's organizations](../../flows/facility/location/manage-location-organizations.mdx).
 
-## How it connects
+### Availability
 
-Locations are the spatial backbone that other primitives attach to.
+Care sets the availability of the location. The location is Reserved when a patient is assigned to it. In all other cases the location is Available. You cannot set the availability yourself.
 
-- **Encounters** occupy locations over time. When a patient is admitted to a bed, a record captures *which* place, *when* occupancy began, and *whether* it is planned, active, reserved, or completed. From these records the platform derives a location's current encounter and whether it is free or reserved — which is how a bed knows it is taken.
-- **Organizations** are granted access to locations. Giving a [facility organization](../access-governance/facility-organization.mdx) access to a ward lets every user under that organization work in the ward and its descendants, through the role they hold. Access flows *downward*: grant it at the building and it reaches every room and bed inside.
-- **Facility** owns the whole tree. Every location belongs to exactly one [facility](../facility/facility.mdx), and the root of its tree sits at the facility level.
+## Status
 
-One important consequence of the tree: access and other inherited properties cascade to descendants asynchronously. When you change who can reach a ward, the rooms and beds beneath it settle a moment later rather than instantly — expect it to be eventually consistent, not immediate.
+| Status | Description |
+| --- | --- |
+| Active | The facility uses the location. |
+| Inactive | The facility does not use the location. |
+| Unknown | The state of the location is not known. |
 
-## Permissions
+## Operational Status
 
-Access to locations is governed by facility-level permissions. Viewing the location tree is open to most clinical roles; changing the tree or its access grants is reserved for administrators and senior staff.
+| Operational Status | Description |
+| --- | --- |
+| Closed | The location is closed for use. |
+| Housekeeping | Housekeeping staff prepare the location. |
+| Occupied | A patient uses the location. |
+| Unoccupied | No patient uses the location. |
+| Isolated | The location is under isolation. |
+| Contaminated | The location is contaminated. |
 
-| Permission | Description | System Roles |
-| --- | --- | --- |
-| `can_write_facility_locations` | Create, edit, or delete a location, and add or remove an organization's access to one (add a ward, room, or bed; change status; grant org access) | Facility Admin, Admin, Staff |
-| `can_create_facility_organization` | Create a root location (one with no parent) at the top of the facility tree | Facility Admin |
-| `can_list_facility_locations` | View a facility's locations, the location tree, and which organizations have access to a location | Admin, Doctor, Facility Admin, Administrator, Nurse, Staff, Pharmacist |
-| `can_manage_facility_organization` | Grant or change an organization's access to a location | Facility Admin, Administrator |
-| `can_write_encounter` | Assign or move an encounter (a patient) to a location, such as placing them in a bed | Admin, Doctor, Nurse, Facility Admin |
+## Permissions
 
-Roles are granted through facility and organization memberships, and because location access follows the tree, a permission held at a parent location cascades down to everything nested beneath it.
+| Permission | What it allows |
+| --- | --- |
+| Can List Facility Locations | View locations. |
+| Can Create/Update Facility Locations | Create, edit, reorder, and delete locations. |
 
-## Related
+Note: To manage the organizations of a location, you also need permission to manage the facility department that you link or unlink.
 
-- Reference: [Location (technical)](../../references/facility/location.mdx)
-- Concept: [Facility](../facility/facility.mdx)
-- Concept: [Facility organization](../access-governance/facility-organization.mdx)
-- Concept: [Encounter](../clinical/encounter.mdx)
-
-## FHIR reference
+## Related
 
-Care's location aligns with the FHIR [Location](https://build.fhir.org/location.html) resource, including its mode (`kind` / `instance`), physical-form codes, and operational-status codes for beds and rooms.
+- Flow: [Create a location](../../flows/facility/location/create-location.mdx)
+- Flow: [View locations](../../flows/facility/location/view-locations.mdx)
+- Flow: [Edit a location](../../flows/facility/location/edit-location.mdx)
+- Flow: [Reorder locations](../../flows/facility/location/reorder-locations.mdx)
+- Flow: [Delete a location](../../flows/facility/location/delete-location.mdx)
+- Flow: [Manage a location's organizations](../../flows/facility/location/manage-location-organizations.mdx)

versioned_docs/version-3.1/flows/facility/department/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Department",
+  "position": 2,
+  "key": "facility-department-flows"
+}

versioned_docs/version-3.1/flows/facility/department/add-users-to-department.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_position: 3
+---
+
+# Add users to a department
+
+## Overview
+
+This flow describes how to manage the members of a [department](../../../concepts/facility/department.mdx) in Care. You can add a user, change a member's role, and remove a member.
+
+## Pre-requisites
+
+- The department is set up in the facility.
+- The user has an account in Care. If the user has no account, you can create the account during this flow.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can List Users in a Facility Organizations | Lets you view the members of a department. Facility Admin, Admin, Staff, Doctor, Administrator, and Nurse hold this permission. |
+| Can Manage Users in a Facility Organization | Lets you add a member, change a member's role, or remove a member. Facility Admin and Administrator hold this permission. |
+
+Note: You cannot give a member a role that carries more permissions than your own effective permissions on that department and its parent departments. Care blocks the attempt.
+
+## Steps
+
+### 1. Open the Users tab of the department
+
+Open the facility. Select Settings. Select Departments. Open the department. Select the Users tab.
+
+### 2. Add a user to the department
+
+Select Link User. Search for the user. Select the user. Under Select Role, select a role. Select Add to Organization.
+
+Note: To link a service account, select the Service accounts tab. Then select Link Service Account.
+
+Note: If the user has no account in Care, select Add User. Complete the user form. Care then opens the Link User form with the new user selected.
+
+### 3. Change a member's role
+
+Find the member in the list. Select Edit next to the member's name. Care opens the Edit User Role sheet. Under Select New Role, select the new role. Select Update Role.
+
+Note: You must select a role different from the member's current role.
+
+Note: Care blocks a role change that removes the last Facility Admin from the facility's root department.
+
+### 4. Remove a member
+
+Find the member in the list. Select Edit next to the member's name. In the sheet that opens, select Remove User. Select Remove to confirm.
+
+Note: Care blocks the removal of the last member of the facility's root department.
+
+## Expected Outcome
+
+- Care shows the new member in the Users tab of the department, with the role of the member.
+- Care shows a success message when you add a member, change a member's role, or remove a member.
+- Care removes the member from the list when you remove the member.
+
+## Related
+
+Concepts:
+
+- [Department](../../../concepts/facility/department.mdx)
+
+Flows:
+
+- [Create a department](./create-department.mdx)
+- [Update a department](./update-department.mdx)

versioned_docs/version-3.1/flows/facility/department/create-department.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_position: 1
+---
+
+# Create a department
+
+## Overview
+
+This flow describes how to create a new [department](../../../concepts/facility/department.mdx) in a facility in Care.
+
+## Pre-requisites
+
+- You are a member of the facility.
+- If you create the department under an existing department (a sub-department), open that parent department first.
+- You have the permission listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can Create Facility Organizations | Lets you create a department. Held by Facility Admin. |
+
+## Steps
+
+### 1. Open the departments settings
+
+Open the facility. Select Settings. Select Departments.
+
+### 2. Start the new department
+
+To create a top-level department, select Add Department/Team from the Departments list.
+
+To create a sub-department, open the parent department first. Then select Add Department/Team on the page of that department.
+
+Note: You cannot create a department under the root Administration department.
+
+### 3. Complete the form
+
+Care opens the Create Department/Team form.
+
+| Components | What it captures |
+| --- | --- |
+| Name | The name of the department. Required. |
+| Type | Choose Department or Team. |
+| Description | A description of the department. Optional. |
+
+Note: Care does not accept a duplicate department name. The name must be different from the names of the other departments at the same level under the same top-level department.
+
+Note: Your deployment sets a maximum nesting depth. Your deployment also sets a maximum total number of departments per facility. If you reach either limit, Care blocks the creation.
+
+### 4. Save the department
+
+Select Create Organization.
+
+## Expected Outcome
+
+- Care creates the department under the facility, or under the parent department you selected.
+- Care shows a success message.
+
+## Related
+
+Concepts:
+
+- [Department](../../../concepts/facility/department.mdx)
+
+Flows:
+
+- [Update a department](./update-department.mdx)
+- [Add users to a department](./add-users-to-department.mdx)