Add Tag and Report Template docs for 3.1

versioned_docs/version-3.1/concepts/platform/report-template.mdx

@@ -0,0 +1,77 @@
+---
+sidebar_position: 2
+---
+
+# Report Template
+
+## Definition
+
+A **report template** in Care is a facility-level definition of a reusable, printable document, such as a discharge summary. A facility admin builds the template one time. Care team members then generate reports from the template for a patient's encounter, for a patient, or for a billing account. The type of the template decides which of these the report covers.
+
+Note: A report template is native to Care. It has no matching FHIR R5 resource.
+
+## Key Attributes
+
+| Components | What it captures |
+| --- | --- |
+| Name | The name of the template. Care team members see this name when they choose a template. |
+| Status | Whether the template is Draft, Active, or Retired. |
+| Default Format | The file format that Care produces for a report, either PDF or HTML. |
+| Template Type | The kind of record that the template is for: Discharge Summary, Patient Summary, or Account Report. |
+| Context | The set of data fields that the template can use. Care matches the context to the template type. |
+| Description | A short explanation of the purpose of the template. |
+| Template Body | The content and layout of the document. You write the body in the Jinja2 templating language, with placeholders that pull in real data when Care generates a report. |
+
+### Template Type and Context
+
+The template type states which kind of record the template describes. Select one of these values:
+
+- Discharge Summary
+- Patient Summary
+- Account Report
+
+The context is the set of data fields that the template can use. Care matches the context to the template type. The placeholders in the template body read their values from this context.
+
+### Generated Reports
+
+A report template is only the definition of a document. When a care team member generates a report from the template, Care creates a separate generated report with its own file in PDF or HTML format. Care stores the generated report, so that you can view it, download it, print it, or generate it again later.
+
+You can archive a generated report, and you must give a reason for the archive. The generated report stays available after you retire the template that produced it.
+
+## Status
+
+| Status | Description |
+| --- | --- |
+| Draft | The template is still in preparation. You cannot generate a report from it. |
+| Active | The template is ready for use. Only an Active template can produce a report. |
+| Retired | Care no longer offers the template for new reports. |
+
+Note: Care has no delete action for a report template. To take a template out of use, edit it and set the status to Retired.
+
+## Permissions
+
+| Permission | Roles |
+| --- | --- |
+| Can Create Template on Facility | Facility Admin, Admin, Doctor, Nurse |
+| Can Read Template | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist |
+| Can Preview Template | Facility Admin, Admin |
+| Can generate report from template | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist |
+| Can generate report for completed encounter | Facility Admin, Admin |
+
+Note: If the encounter is complete, you need Can generate report for completed encounter as well as Can generate report from template.
+
+## Where to find it
+
+Care shows report templates on the **Templates** page of a facility. This page holds the list of templates and the template builder.
+
+Care shows generated reports in the **Reports** section of the **Overview** tab of an encounter. This section lists the Active Discharge Summary templates that you can generate a report from.
+
+## Related
+
+- Flow: [Create a report template](../../flows/platform/report-template/create-a-report-template.mdx)
+- Flow: [Preview a template](../../flows/platform/report-template/preview-a-template.mdx)
+- Flow: [Edit a report template](../../flows/platform/report-template/edit-a-report-template.mdx)
+- Flow: [View report templates](../../flows/platform/report-template/view-report-templates.mdx)
+- Flow: [Generate and view a report](../../flows/platform/report-template/generate-and-view-a-report.mdx)
+- Concept: [Encounter](../../concepts/clinical/encounter.mdx)
+- Concept: [Diagnostic Report](../../concepts/clinical/diagnostic-report.mdx)

versioned_docs/version-3.1/concepts/platform/tagging.mdx

@@ -2,69 +2,95 @@
 sidebar_position: 1
 ---
 
-# Tagging
+# Tag
 
-A **tag** in Care is a reusable label you attach to a record — a patient, an encounter, an order — to classify it and find it again later. Tagging is how a deployment layers its own vocabulary on top of Care's clinical model: priority flags, dietary restrictions, drug categories, safety alerts, and any other grouping a workflow needs.
+## Definition
 
-## What it represents
+A **tag** in Care is a label that you define once and then attach to records such as encounters, service requests, and accounts. You define a tag for one facility, and staff at that facility can then apply it. A superuser can also define an instance-wide tag that every facility can use.
 
-A tag is not free text typed onto a record. Each label is a controlled definition — the `TagConfig` resource — created ahead of time, then reused across many records. That separation is the whole point: because every "Penicillin Allergy" tag traces back to one definition, you can filter, count, and report on it reliably instead of chasing a dozen spellings.
+Note: Care has no FHIR R5 resource for a tag. A tag works like a coded value that your organization defines for its own use.
 
-A definition carries the things that make a label usable: a human-readable name and category (`diet`, `drug`, `lab`, `admin`, `clinical`, `safety`, `advance_directive`, and a few more), display hints like a color and icon, an ordering priority, the one resource type it targets, the owner that governs it, and its place in the tag tree. The sections below cover the three of those that shape how tags behave: target, ownership, and hierarchy.
+Note: This document covers the tag definition only. To attach a tag to a record or remove it, read the documentation of that record. For encounters, read [Manage Encounter tags](../../flows/clinical/encounter/manage-encounter-tags.mdx).
 
-## How it connects
+## Key Attributes
 
-A tag never lives inside the thing it labels. The definition is created once and then *applied* to records of its target type, and each tagged record simply stores which tags it carries:
+| Components | What it captures |
+| --- | --- |
+| Display | The name of the tag that Care shows to users. |
+| Category | The subject area of the tag. |
+| Resource | The type of record that you can attach the tag to. You select this when you create the tag, and you cannot change it later. |
+| Priority | A number that sets the order of the tag in lists. The default value is 100. |
+| Status | Whether staff can apply the tag. |
+| Description | A short text that explains the purpose of the tag. |
+| Managing Organization | The facility organization that manages the tag. For an instance-wide tag, this is an instance-level organization. |
+| Has Children | Whether the tag has child tags under it. |
 
-- A **patient** can carry instance-wide tags and facility-specific tags.
-- An **encounter** carries its own set of tags.
-- Orders and financial records — service requests, prescriptions, charge items, supply requests, accounts, and more — each accept tags scoped to their resource type.
+### Category
 
-Because a definition declares exactly **one** target resource, a patient tag can never be applied to an encounter, and vice versa. This is a deliberate guardrail: it keeps each resource type's vocabulary clean and stops one sprawling, mixed-up pile of labels from forming.
+Category groups tags by subject area. Select one of these values:
 
-Ownership works the same way — a tag belongs to exactly one scope: an instance-wide organization, a facility-scoped organization, or a single facility. Instance tags give a deployment shared vocabulary everywhere; facility-scoped tags let a site add labels that only make sense locally.
+- Diet
+- Drug
+- Lab
+- Admin
+- Contact
+- Clinical
+- Behavioral
+- Research
+- Advance Directive
+- Safety
 
-## Tree structure
+### Resource
 
-Tags form a hierarchy, so a deployment can model a vocabulary from broad to narrow:
+Resource sets the type of record that staff can attach the tag to. Select one of these values:
 
-```text
-Allergy → Drug Allergy → Penicillin Allergy
-```
+- Encounter
+- Service Request
+- Charge Item
+- Charge Item Definition
+- Account
+- Token Booking
+- Medication Request Prescription
+- Supply Request Order
+- Supply Delivery Order
+- Patient
 
-A tag with no parent is a **root** — the top of a vocabulary. A **child** narrows its parent, and must target the **same resource type**, so a branch never mixes patient labels with encounter labels. The hierarchy lets you filter at any depth: ask for everything under "Allergy," or drill into just "Penicillin Allergy." You only choose each tag's parent; the platform maintains the tree positions behind it.
+### Parent and child tags
 
-## Lifecycle
+You can arrange tags in a tree. A root tag holds one or more child tags. A child tag takes the Category and the Resource of its parent tag, and you cannot change these two fields on the child tag.
 
-```text
-active → archived
-```
+Child tags under the same parent work as a set of choices. Staff can apply only one child tag from a parent group to a record at a time. If staff select a different child tag under the same parent, Care replaces the earlier selection. A root tag without children has no such limit, and staff can combine it with other tags.
 
-- **active** — the tag can be applied to new records.
-- **archived** — the tag is retired from new use but kept for history, so records labelled in the past stay correctly classified and auditable.
+## Status
 
-Archiving rather than deleting is what lets a vocabulary evolve without rewriting the past.
+Care has no delete action for a tag. To stop the use of a tag, set its status to Archived.
 
-## Permissions
+| Status | Description |
+| --- | --- |
+| Active | Staff can apply the tag to records. |
+| Archived | Staff can no longer apply the tag to records. |
+
+To archive a root tag, edit the tag. Change the Status field to Archived. Care has no one-click archive action for a root tag. For a child tag, Care shows an Archive action. Care asks you to confirm before it archives the child tag.
 
-Access to tags separates three actions: defining them, applying them, and reading them.
+## Permissions
 
-| Permission | Description | System Roles |
+| Permission | Who has it | What it allows |
 | --- | --- | --- |
-| `can_write_tag_config` | Create new tag definitions and edit existing ones within a facility (the viewset checks this for both create and update) | Facility Admin, Admin |
-| `can_read_tag_config` | List and retrieve tag definitions in a facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist |
-| `can_apply_tag_config` | Attach an existing tag to records of its target type (patients, encounters, and other resources) | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist |
+| Can Create Tag Config on Facility | Facility Admin, Admin | Create and update a tag. |
+| Can Apply Tag Config to Resources | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | Attach a tag to a record and remove it. |
+| Can Read Tag Config | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | View tags. |
 
-Permissions cascade down the organization tree, so curating the shared vocabulary stays with administrators while frontline clinical staff can apply and read tags during care.
+Note: Only a superuser can create or update an instance-wide tag.
 
-## Related
+## Where to find tags
 
-- Reference: [Tag Config (technical)](../../references/platform/tag-config.mdx)
-- Concept: [Patient](../clinical/patient) — carries instance and facility tags
-- Concept: [Encounter](../clinical/encounter.mdx) — carries its own tags
-- Concept: [Organization](../access-governance/organization.mdx) — tags can be org-scoped and reuse its tree pattern
-- Concept: [Facility](../facility/facility.mdx) — facility-scoped tags
+Care shows facility tags in the Settings area of a facility, under Tag config. Care shows instance-wide tags in a separate global Admin area.
 
-## FHIR reference
+## Related
 
-Care's tagging is a platform extension rather than a single FHIR resource. It plays the role FHIR fills with coded `tag` and `category` elements on a resource's `meta` — a controlled, hierarchical vocabulary applied to records for classification and filtering.
+- Flow: [Create a tag](../../flows/platform/tagging/create-a-tag.mdx)
+- Flow: [Create a child tag](../../flows/platform/tagging/create-a-child-tag.mdx)
+- Flow: [View tags](../../flows/platform/tagging/view-tags.mdx)
+- Flow: [Edit a tag](../../flows/platform/tagging/edit-a-tag.mdx)
+- Flow: [Archive a child tag](../../flows/platform/tagging/archive-a-child-tag.mdx)
+- Concept: [Encounter](../../concepts/clinical/encounter.mdx)

versioned_docs/version-3.1/flows/platform/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Platform",
+  "position": 7,
+  "key": "platform-flows"
+}

versioned_docs/version-3.1/flows/platform/report-template/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Report Template",
+  "position": 2,
+  "key": "platform-report-template-flows"
+}

versioned_docs/version-3.1/flows/platform/report-template/create-a-report-template.mdx

@@ -0,0 +1,79 @@
+---
+sidebar_position: 1
+---
+
+# Create a report template
+
+## Overview
+
+This flow describes how to create a new [report template](../../../concepts/platform/report-template.mdx) for a facility in Care.
+
+## Pre-requisites
+
+- You are a member of the facility that you create the template for.
+- You know which data the report must show, so that you can pick the correct template type and context.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can Create Template on Facility | Create a report template for the facility. Facility Admin, Admin, Doctor, and Nurse have this permission. |
+
+## Steps
+
+### 1. Open the template builder
+
+Open the **Templates** page of the facility.
+
+Select **Create Template**. Care opens the template builder.
+
+### 2. Fill in the template details
+
+Complete the fields in the builder.
+
+| Components | What it captures |
+| --- | --- |
+| Name | The name of the template. This field is required. Care creates a matching short name for the URL from the name. You can change the short name. The short name has 5 to 25 characters. Use lowercase letters, numbers, and hyphens only. |
+| Status | The state of the template: Draft, Active, or Retired. A new template normally starts as Draft. |
+| Template Type | The kind of document that the template produces: Discharge Summary, Patient Summary, or Account Report. This field is required. |
+| Context | The set of data fields that the template can use. This field is required. The context must match the template type that you select. |
+| Default Format | The output format of the report: PDF or HTML. This field is required. |
+| Description | A short text about the purpose of the template. This field is optional. |
+| Template Body | The content of the document. This field is required. Write the content in the Jinja2 templating language in the large text area. |
+
+### 3. Insert data fields into the template body
+
+The builder shows the available data fields for the context that you select in a side panel.
+
+Put the cursor in the template body at the position for the data field.
+
+Select a data field in the side panel. Care inserts a placeholder for that field at the cursor position.
+
+The placeholder shows the real value in the report. For example, insert the patient name or the discharge advice.
+
+### 4. Check the result
+
+Render a sample of the template before you save it. See [Preview a template](./preview-a-template.mdx).
+
+### 5. Save the template
+
+Select **Save**.
+
+## Expected Outcome
+
+- Care shows the message "Template saved".
+- Care opens the builder page of the new template, so that you can continue to edit it.
+
+## Related
+
+Concepts:
+
+- [Report Template](../../../concepts/platform/report-template.mdx)
+
+Flows:
+
+- [Preview a template](./preview-a-template.mdx)
+- [Edit a report template](./edit-a-report-template.mdx)
+- [View report templates](./view-report-templates.mdx)
+- [Generate and view a report](./generate-and-view-a-report.mdx)

versioned_docs/version-3.1/flows/platform/report-template/edit-a-report-template.mdx

@@ -0,0 +1,73 @@
+---
+sidebar_position: 3
+---
+
+# Edit a report template
+
+## Overview
+
+This flow describes how to change an existing [report template](../../../concepts/platform/report-template.mdx) in Care. Use the same flow to retire a template.
+
+## Pre-requisites
+
+- The facility has a report template that you want to change.
+- You are a member of that facility.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can Create Template on Facility | Lets you create and edit report templates. Facility Admin, Admin, Doctor, and Nurse have this permission. |
+
+## Steps
+
+### 1. Open the template
+
+Go to the **Templates** page of the facility. See [View report templates](./view-report-templates.mdx).
+
+Select the template that you want to change. Care opens the same builder that you use to create a template. The builder shows the current values of the template.
+
+### 2. Change the template
+
+Change any of the fields in the table below.
+
+| Components | What it captures |
+| --- | --- |
+| Name | The name of the template. |
+| Status | The state of the template: Draft, Active, or Retired. |
+| Template Type | The kind of document that the template produces: Discharge Summary, Patient Summary, or Account Report. |
+| Context | The set of data fields that the template can use. The context must match the template type. |
+| Default Format | The output format of the report: PDF or HTML. |
+| Description | A short text about the purpose of the template. |
+| Template Body | The content of the document. |
+
+Note: Only a template with Status set to Active can generate a report. A template with Status set to Draft or Retired does not appear as an option. See [Generate and view a report](./generate-and-view-a-report.mdx).
+
+### 3. Retire the template
+
+To stop staff from using the template for new reports, set Status to Retired.
+
+Note: Care has no delete action and no separate retire action for a report template. Use the Status field.
+
+### 4. Save the template
+
+Select **Save**.
+
+## Expected Outcome
+
+- Care saves your changes and shows the message "Template updated".
+- If you set Status to Retired, staff can no longer use the template to generate a new report.
+
+## Related
+
+Concepts:
+
+- [Report Template](../../../concepts/platform/report-template.mdx)
+
+Flows:
+
+- [Create a report template](./create-a-report-template.mdx)
+- [Preview a template](./preview-a-template.mdx)
+- [View report templates](./view-report-templates.mdx)
+- [Generate and view a report](./generate-and-view-a-report.mdx)