> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# In-Basket

> Filterable list of clinical notifications, tasks, and messages; view item detail with status management, escalation, chart deep-link, and activity timeline.

The In-Basket screen is a work-queue at `/cl/in-basket` that lists all clinical notifications and tasks for the current organisation, filterable by item type, classification, and status.

## Overview

The screen loads all `cl_inbasket_items` for the current organisation ordered by creation date descending. Three filter dropdowns — item type, classification, and status — can be combined in any combination; selecting "all" in a dropdown removes that filter. Items are displayed in a table with columns: Type (linked to the detail page), Classification, Priority (badged), Status (badged), Due date, and Created date. Clicking the linked type value navigates to `/cl/in-basket/:id` for the item detail. When the list is empty the screen shows "You're all caught up!"

## Who it's for

Requires the `cl.inbasket.view` permission.

## Before you start

* The `cl.inbasket.view` permission must be assigned to your role.
* In-basket items must exist in `cl_inbasket_items` for the current organisation; otherwise the empty state is shown.

## Steps

<Steps>
  <Step title="Open the In-Basket">Navigate to `/cl/in-basket`. The table loads all items for your organisation, most recently created first.</Step>
  <Step title="Filter by type (optional)">Use the "All Types" dropdown to narrow results to a specific item type: Co-Sign Request, Lab Review, Refill Request, Chart Message, Referral Response, or CDS Alert.</Step>
  <Step title="Filter by classification (optional)">Use the "All Classifications" dropdown to show only Action Required or Informational items.</Step>
  <Step title="Filter by status (optional)">Use the "All Statuses" dropdown to show only items in a specific state: New, Read, In Progress, Completed, Deferred, or Escalated.</Step>
  <Step title="Open an item">Click the linked item type in the Type column to navigate to the item detail page at `/cl/in-basket/:id`.</Step>
</Steps>

## Key concepts

<Tooltip tip="In-Basket — a clinician work-queue aggregating different types of clinical notifications and tasks from cl_inbasket_items.">In-basket</Tooltip> item types and their display labels as defined in code:

| Type code           | Display label     |
| ------------------- | ----------------- |
| `cosign_request`    | Co-Sign Request   |
| `lab_review`        | Lab Review        |
| `refill_request`    | Refill Request    |
| `chart_message`     | Chart Message     |
| `referral_response` | Referral Response |
| `cds_alert`         | CDS Alert         |

Priority levels rendered as badges: `urgent` (destructive), `high` (secondary), `normal` (default), `low` (outline).

Status values: `new`, `read`, `in_progress`, `completed`, `deferred`, `escalated` (escalated renders as destructive badge).

<AccordionGroup>
  <Accordion title="Empty state">
    When no items match the current filters the screen shows "No in-basket items — You're all caught up!" with an inbox icon.
  </Accordion>

  <Accordion title="Error state">
    If the query fails, a destructive alert is shown with the sanitised error message.
  </Accordion>

  <Accordion title="Loading state">
    While fetching, a header skeleton and five row skeletons are displayed.
  </Accordion>
</AccordionGroup>

## Viewing an item

The Item Detail screen shows a single in-basket item with its full metadata and activity history at `/cl/in-basket/:itemId` (permission: `cl.inbasket.view`). Additional actions require:

* `cl.inbasket.manage` — update item status
* `cl.inbasket.escalate` — escalate item priority and status

The page loads a single in-basket item via `useInbasketItemDetail`, which returns both the item record and its activity log. A main detail card (spanning 2 of 3 columns) shows item type (human-readable label from `TYPE_LABELS`), classification, priority badge, status badge, creation date, optional due date, and optional assignee. If the item type is `chart_message` and the payload contains a `conversation_id`, an **Open Message Thread** button deep-links to `/pm/messaging/:conversationId`. If `chart_id` is set, a **View Patient Chart** link navigates to `/cl/charts/:chartId`. Users with `cl.inbasket.manage` see a status select dropdown. Users with `cl.inbasket.escalate` additionally see an **Escalate** button that sets `priority` to `urgent`, records `escalated_at`, and transitions status to `escalated`. An Activity timeline card (1 column) shows each logged `cl_inbasket_item_activity` entry in chronological order.

<Steps>
  <Step title="Open the item">
    Navigate to `/cl/in-basket`, then click an item row. The detail page loads the item and activity timeline.
  </Step>

  <Step title="Review item metadata">
    The main card shows item type, classification, priority badge, status badge, creation date, optional due date, and optional assignee.
  </Step>

  <Step title="Open the linked patient chart (if available)">
    If `chart_id` is set, click **View Patient Chart** to navigate to `/cl/charts/:chartId`.
  </Step>

  <Step title="Open the linked message thread (chart_message type only)">
    If the item type is `chart_message` and a `conversation_id` is present in the payload, click **Open Message Thread** to navigate to `/pm/messaging/:conversationId`.
  </Step>

  <Step title="Update status (manage permission required)">
    Use the status dropdown (requires `cl.inbasket.manage`) to transition the item through `new` → `read` → `in_progress` → `completed` / `deferred` / `escalated`. Setting `completed` also records `completed_at`.
  </Step>

  <Step title="Escalate the item (escalate permission required)">
    Click **Escalate** (visible when `cl.inbasket.escalate` is held and status is not already `escalated`) to set priority to `urgent`, record `escalated_at`, and transition status to `escalated`.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Priority levels">
    `low`, `normal`, `high`, `urgent`, `stat`. Priority `stat` renders a destructive badge; `urgent` renders a secondary badge; others render outline.
  </Accordion>

  <Accordion title="Activity timeline">
    Each entry in `cl_inbasket_item_activity` is displayed with `activity_type` (formatted: underscores replaced with spaces) and `activity_at` timestamp. Activity is created automatically on status changes and escalations via `useUpdateInbasketItem`.
  </Accordion>

  <Accordion title="Empty and error states (detail)">
    * Load error: destructive `Alert` with sanitized error message and a back link to `/cl/in-basket`.
    * Item not found: centered `Inbox` icon with "Item not found" heading and back link.
    * No activity: "No activity recorded yet."
    * Loading: skeleton for the header and two-column grid.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Clinical" icon="stethoscope" href="/cl/overview">
    Overview of the Clinical core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/cl.tsx
  * src/cores/cl/pages/InBasketListPage.tsx
  * src/cores/cl/hooks/useInbasketItemList.ts
  * src/cores/cl/types/inbasket.ts
  * src/cores/cl/pages/InBasketItemDetailPage.tsx
  * src/cores/cl/hooks/useInbasketItemDetail.ts
  * src/cores/cl/hooks/useInbasketItemMutation.ts
</Accordion>