[docs] Organization docs for Access & Governance

versioned_docs/version-3.0/concepts/access-governance/organization.mdx

@@ -4,69 +4,45 @@ sidebar_position: 2
 
 # Organization
 
-An **organization** is how Care groups people and permissions so that access is defined once and reused, instead of configured per person. Organizations form a tree, and a role granted on a parent flows down to everything beneath it — they are the backbone of who-can-do-what across a deployment. (FHIR calls this grouping primitive *Organization*; Care uses that term rather than "group," which is ambiguous in a clinical setting.)
+An **[organization](https://build.fhir.org/organization.html)** in Care is a group of people that holds access. You add a person to an organization with a role, and the role gives that person access to everything the organization covers. Organizations form a tree, and access on a parent organization applies to every organization below it. An organization is not a facility: a facility is a place where care happens, and the departments inside a facility are [facility organizations](../access-governance/facility-organization.mdx).
 
-## What it represents
+## Key Attributes
 
-The job of an organization is to **group the permissions assigned to resources**. Rather than granting each new doctor a long list of permissions, you create a "Doctors" organization once, give it the access it should carry — hospital-wide questionnaires, say — and add doctors to it. A child "Cardiology" organization can layer on cardiology-specific forms while still inheriting everything from "Doctors." The next doctor who arrives is simply added to the group; no permissions are defined by hand.
-
-An organization is not a facility. A facility is a physical place where care happens; an organization is an administrative grouping that lives instance-wide. The departments and teams *inside* a single hospital are modelled separately as [facility organizations](../access-governance/facility-organization.mdx) — this concept is the platform-wide tree above them.
-
-## Organization types
-
-The `org_type` says what kind of grouping a node is, and Care treats each differently — most visibly in who is allowed to manage it.
-
-| Type | What it is |
+| Components | What it captures |
 | --- | --- |
-| `team` | A working grouping of people — the everyday default |
-| `govt` | A governance / governmental unit that mirrors a real administrative hierarchy |
-| `role` | A **user group**: a flat set of users grouped for a shared purpose (assigning questionnaires, and later prescribing and approvals) |
-| `product_supplier` | A supplier organization that links into the [supply chain](../supply/product.mdx) |
-
-### Government hierarchies
-
-`govt` organizations model real-world governance — a public-health administration laid out as `State → District → Block → Panchayat`, for example. They are the geographic backbone a deployment hangs facilities and patients off: a facility's governing organization and a patient's administrative area both point into this tree. That is how a district health officer reaches every facility and patient beneath their district without being added to each one.
-
-Because governance structures have to be visible to coordinate across them, **anyone in Care may view `govt` organizations**, but only a superadmin may create or edit them. Their names and shape are treated as fixed reference data, not something an individual facility can change.
+| Name | The name of the organization. Two organizations under the same parent cannot use the same name. |
+| Description | A short note about what the organization is used for. |
+| Type | The kind of group. See Types below. |
+| Parent organization | The organization directly above this one in the tree. |
+| Active | Shows if the organization is in use. |
 
-### Role organizations (user groups)
+### Types
 
-A `role` organization is a **user group** — a flat list of users grouped for a shared purpose rather than a place in a hierarchy. Care uses them to decide things like which users a questionnaire is assigned to, and they are built to extend to prescribing, approving requests, and similar group-driven workflows. A deployment defines the groups it needs — in palliative care these might be *Volunteer*, *ASHA Worker*, or *MLSP* — and a user can be placed into them when their account is created. Unlike the governance and team trees, role organizations are flat and are managed by superadmins.
-
-:::note Role vs. role organization
-A **role** is an arbitrary set of permissions — `Doctor`, `Doctor (Read Only)`, `Doctor (Scheduler)` — nothing more than a named bundle, never a job title. A **role organization** is a group of users. They are independent: you grant a role to a user *within* an organization. See [Roles & permissions](../access-governance/access-control.mdx).
-:::
-
-## How the tree works
-
-Organizations nest. A root sits at the top with no parent; every other node points to a single parent, forming chains like `Government → State Health Dept → District → Cardiology`.
-
-The defining behaviour is **inheritance**: a role granted on a parent applies implicitly to every descendant. Make someone an admin of a district and they can act across every team beneath it without being added to each. This is what makes the tree an access structure and not just a folder hierarchy.
-
-A few rules keep it consistent: siblings under the same root must have unique names; a parent cannot be deleted while it still has children; system-generated and `govt` organizations cannot be edited; and a node's parent is fixed once created — you move people, not the node.
-
-## Membership, roles & responsibility
+| Type | What it groups |
+| --- | --- |
+| Government | An administrative area, such as a state, a district, or a local body. |
+| Team | A working group of people. |
+| Responsibility | A flat group of people who share a designation, such as Volunteer or Nurse Practitioner. |
+| Supplier | A vendor organization that supplies products. |
 
-People gain access by being added to an organization **with a role** — that triple of user + organization + role is what grants permission. Membership grants access *through* the organization, not *to* everything it touches: a user can act on the resources assigned to their organization (and, by inheritance, its descendants), always bounded by what their role allows. An organization "for nurses with access to patients in wards Y and Z" reaches exactly those patients — not every patient in the deployment.
+Government organizations model the real administrative map. A facility and a patient each sit under a government organization, so an administrator of a district reaches every facility and patient in that district. Every user can see government organizations, because coordination needs them. Only an instance administrator can create or change them.
 
-Care guards against privilege escalation right at the membership boundary: the role you assign to someone can be **at most the role you yourself hold** in that organization, and you can only remove members whose access sits below your own. No one can grant — or revoke — more than they have.
+A responsibility organization is a flat list of people. Care uses it for designations and governance, and it has no organizations below it.
 
-Administering a *user* (resetting a password, editing details, changing group memberships) follows the same principle through a separate **management hierarchy**: a user can be administered only by someone in a managing organization above them, never by an arbitrary peer. That is how a governance admin can legitimately reset a password for someone beneath them, while no one can seize control of a user they don't already oversee.
+### The tree
 
-## Permissions
+Each organization has one parent, and a root organization has no parent. A role that you grant on a parent applies to every organization below it. You cannot change the parent after you create the organization, and you cannot delete an organization that still has organizations below it. Your deployment sets a maximum depth for the tree.
 
-Access to organizations is governed by the permissions below. Each lists the system roles that carry it by default.
+### Membership
 
-| Permission | Description | System Roles |
-| --- | --- | --- |
-| `can_create_organization` | Create a new organization under a parent the user can already manage (root, governance, and role organizations remain superadmin-only) | Admin |
-| `can_view_organization` | View organizations and list/retrieve them through the accessible-organizations filter | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org), Member (role org) |
-| `can_manage_organization` | Update an organization's name, description, and metadata, manage its connected role organizations, and delete it once it has no children | Admin, Admin (role org) |
-| `can_list_organization_users` | List the members of an organization | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org) |
-| `can_manage_organization_users` | Add, remove, and assign roles to members of an organization (bounded by the actor's own role privileges) | Admin, Administrator, Facility Admin, Admin (role org) |
-| `can_manage_connected_role_organizations` | Add, remove, and assign roles to members of connected role organizations | Admin (role org), Manager (role org) |
+A person gets access through a membership: one user, one organization, one role. You can give another person only a role that is within your own role in that organization. The same rule applies when you remove a person. A person cannot be a member of an organization and of a parent or a child of that organization at the same time.
 
 ## Related
 
-- Reference: [Organization (technical)](../../references/access-governance/organization.mdx)
-- Concept: [Roles & permissions](../access-governance/access-control.mdx) · [Facility Organization](../access-governance/facility-organization.mdx) · [Facility](../facility/facility.mdx)
+- Flow: [Create an organization](../../flows/access-governance/create-an-organization.mdx)
+- Flow: [Add a user to an organization](../../flows/access-governance/add-a-user-to-an-organization.mdx)
+- Flow: [Change the role of a user in an organization](../../flows/access-governance/change-a-user-role-in-an-organization.mdx)
+- Concept: [Roles and permissions](../access-governance/access-control.mdx)
+- Concept: [Facility organization](../access-governance/facility-organization.mdx)
+- Concept: [User](../access-governance/user.mdx)
+- Reference: [Organization](../../references/access-governance/organization.mdx)

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

@@ -0,0 +1,5 @@
+{
+  "label": "Access & Governance",
+  "position": 2,
+  "key": "access-governance-flows"
+}

versioned_docs/version-3.0/flows/access-governance/add-a-user-to-an-organization.mdx

@@ -0,0 +1,76 @@
+---
+sidebar_position: 2
+---
+
+# How to add a user to an organization
+
+## Overview
+
+This flow describes how to add a [user](../../concepts/access-governance/user.mdx) to an [organization](../../concepts/access-governance/organization.mdx) and give that user a role. The role decides what the user can do in that organization and in every organization below it.
+
+## Pre-requisites
+
+- The organization exists in Care.
+- If you link an account that already exists, the user has an account in Care.
+- The user is not already a member of this organization, of a parent of it, or of an organization below it.
+- The role that you give is within your own role in that organization. You cannot give more access than you hold.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can View Organizations | Open the organization. |
+| Can List Users in an Organizations | See the members of the organization. |
+| Can Manage Users in an Organization | Add a member, change a role, and remove a member. |
+
+## Steps
+
+### 1. Open the organization
+
+Select the organization that you want to change. Care opens the organization.
+
+### 2. Open the users tab
+
+Select **Users**. Care shows the members of the organization. Use the search box to find a member by name, by username, or by phone number.
+
+### 3. Select how you add the user
+
+| Option | When to use it |
+| --- | --- |
+| Link User | The user already has an account in Care. |
+| Add User | The user has no account, so you create the account first. |
+
+### 4. Link a user that already has an account
+
+Select **Link User**. Search for the user by username. Select the user in the results.
+
+| Components | What it captures |
+| --- | --- |
+| User | The account that you add to the organization. |
+| Role | The role that the user holds in this organization. |
+
+Select **Link User to Organization**. Care adds the user to the organization.
+
+### 5. Add a user that has no account
+
+Select **Add User**. Complete the user form, then save it. Care creates the account and opens the **Link User** panel with the new user selected. Select the role, then select **Link User to Organization**.
+
+## Expected Outcome
+
+- The user is in the members list of the organization, with the role that you selected.
+- The user has the access of that role in this organization and in every organization below it.
+- You can select **Edit Role** on the member to change the role later.
+
+## Related
+
+Concepts:
+
+- [Organization](../../concepts/access-governance/organization.mdx)
+- [User](../../concepts/access-governance/user.mdx)
+- [Roles and permissions](../../concepts/access-governance/access-control.mdx)
+
+Flows:
+
+- [Create an organization](./create-an-organization.mdx)
+- [Change the role of a user in an organization](./change-a-user-role-in-an-organization.mdx)

versioned_docs/version-3.0/flows/access-governance/change-a-user-role-in-an-organization.mdx

@@ -0,0 +1,66 @@
+---
+sidebar_position: 3
+---
+
+# How to change the role of a user in an organization
+
+## Overview
+
+This flow describes how to change the role of a member of an [organization](../../concepts/access-governance/organization.mdx), and how to remove that member. The role decides what the member can do in the organization and in every organization below it.
+
+## Pre-requisites
+
+- The user is already a member of the organization.
+- The new role is within your own role in that organization. You cannot give more access than you hold.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can View Organizations | Open the organization. |
+| Can List Users in an Organizations | See the members of the organization. |
+| Can Manage Users in an Organization | Change the role of a member, and remove a member. |
+
+## Steps
+
+### 1. Open the members list
+
+Open the organization, then select **Users**. Care shows the members of the organization.
+
+### 2. Open the member
+
+Find the member that you want to change. Select **Edit Role**. Care opens the **Edit User Role** panel and shows the **Current Role** of the member.
+
+### 3. Select the new role
+
+Select the role in **Select New Role**.
+
+| Components | What it captures |
+| --- | --- |
+| Current Role | The role that the member holds now. |
+| Select New Role | The role that the member holds after you save. |
+
+Select **Update Role**. Care saves the new role.
+
+### 4. Remove the member
+
+To take away the access of the member, select **Remove User** in the same panel. Care asks you to confirm the action in the **Remove User from Organization** dialog. Select **Remove**.
+
+## Expected Outcome
+
+- The member holds the new role, and the members list shows it.
+- The access of the member changes at once in this organization and in every organization below it.
+- If you removed the member, the user is no longer in the members list, and the account stays in Care.
+
+## Related
+
+Concepts:
+
+- [Organization](../../concepts/access-governance/organization.mdx)
+- [User](../../concepts/access-governance/user.mdx)
+- [Roles and permissions](../../concepts/access-governance/access-control.mdx)
+
+Flows:
+
+- [Add a user to an organization](./add-a-user-to-an-organization.mdx)

versioned_docs/version-3.0/flows/access-governance/create-an-organization.mdx

@@ -0,0 +1,81 @@
+---
+sidebar_position: 1
+---
+
+# How to create an organization
+
+## Overview
+
+This flow describes how to create an [organization](../../concepts/access-governance/organization.mdx) in Care. You create an organization to group people, and then you give those people access through that group.
+
+## Pre-requisites
+
+- You have an administrator account in Care.
+- The parent organization exists, because Care creates every new organization under a parent.
+- If you create a government organization, a responsibility, or a supplier organization, you are an instance administrator.
+- The tree below the parent is not at the maximum depth that your deployment sets.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can View Organizations | See the organization and the organizations below it. |
+| Can Create Organizations | Create an organization under a parent that you manage. |
+| Can Manage Organizations | Change or delete an organization after you create it. |
+
+## Steps
+
+### 1. Open the administration area
+
+Select **Admin** in the main navigation. Care opens the administration area.
+
+### 2. Select the organization type
+
+Open **Organizations** in the administration navigation, then select the type that you want:
+
+| Option | What it creates |
+| --- | --- |
+| Governance | A government organization, such as a state or a district. |
+| Responsibilities | A flat group of people who share a designation. |
+| Suppliers | A vendor organization. |
+
+### 3. Select the parent organization
+
+For **Governance**, select the organization that you want to create the new organization under. Care shows the organizations below it. Use the search box to find an organization by name.
+
+For **Responsibilities** and **Suppliers**, the list is flat, so there is no parent to select.
+
+### 4. Open the form
+
+Select **Add Organization**. Care opens the form panel.
+
+### 5. Complete the form
+
+| Components | What it captures |
+| --- | --- |
+| Name | The name of the organization. This field is mandatory. Two organizations under the same parent cannot use the same name. |
+| Description | A short note about what the organization is used for. This field is optional. |
+
+Care sets the type from the page that you started on, so you do not select it.
+
+### 6. Save the organization
+
+Select **Create Organization**. Care creates the organization and shows it in the list.
+
+## Expected Outcome
+
+- The organization is in the list under the parent that you selected.
+- You can now add users to the organization, and give each user a role.
+- You can select **Edit** on the organization to change its name or its description.
+
+## Related
+
+Concepts:
+
+- [Organization](../../concepts/access-governance/organization.mdx)
+- [Roles and permissions](../../concepts/access-governance/access-control.mdx)
+
+Flows:
+
+- [Add a user to an organization](./add-a-user-to-an-organization.mdx)