> ## 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.

# IT Tickets

> View and manage all IT support tickets across the organization — browse, filter, view details, add comments, and create new tickets.

The IT Tickets page (`/it/tickets`) displays the full organizational queue of IT support requests. It supports filtering, pagination, and live updates via a real-time subscription to the `it_tickets` table.

## Overview

The page loads tickets via `useTickets` with support for `TicketFilters` and pagination (page size 20). A realtime subscription listens for INSERT, UPDATE, and DELETE events on `it_tickets` and automatically invalidates the `it-tickets` query cache, showing toast notifications for new and removed tickets. A `RealtimeConnectionBadge` indicates live connection status.

## Who it's for

Users with permission `it.view` (outer `ITViewGuard` → `RequirePermission permission={IT_PERMISSIONS.VIEW}`). Creating a new ticket uses `it.tickets.create`.

## Before you start

* Ensure you have the IT module permission (`it.view`) in your role.
* For real-time updates to work, your browser must maintain an active connection to the platform.

## Steps

<Steps>
  <Step title="Open the ticket queue">
    Navigate to `/it/tickets`. The table loads the first page of tickets across your organization.
  </Step>

  <Step title="Filter tickets">
    Use the filter bar to narrow results by status, priority, or other available criteria. Filters update the table immediately.
  </Step>

  <Step title="Navigate pages">
    Use the Previous/Next buttons at the bottom of the page when more than 20 tickets exist.
  </Step>

  <Step title="Open a ticket">
    Click a ticket row to navigate to its detail page at `/it/tickets/:id`.
  </Step>

  <Step title="Create a new ticket">
    Click **New Ticket** (or press Cmd+N from the IT overview page) to navigate to `/it/tickets/new`.
  </Step>
</Steps>

## Key concepts

| Concept                | Description                                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Real-time subscription | `useRealtimeSubscription` watches `it_tickets` for live changes; toast notifications appear on insert or delete events |
| `TicketFilters`        | Filter shape accepted by `useTickets`; fields include status, priority, and search                                     |
| Pagination             | Page size fixed at 20; total pages computed from `totalCount`                                                          |

## Viewing a ticket

The Ticket Details page (`/it/tickets/:id`) has three tabs: **Details** (ticket metadata, description, SLA tracking card, linked asset card), **Comments** (add and view comments), and **Security** (linked security incidents and escalation). Header actions include Assign/Reassign, Change Status, and Link Asset. A compact SLA indicator shows in the ticket header alongside the ticket number.

Permission required: `IT_PERMISSIONS.VIEW` (`it.view`) via the module-level `ITViewGuard`. No additional per-route permission gate.

1. Navigate to **IT > Tickets** and click a ticket row, or navigate directly to `/it/tickets/:id`.
2. Review the **Details** tab: subject, priority, status, description, linked asset, and SLA status.
3. Click **Assign** (or **Reassign**) to assign the ticket to a team member.
4. Click **Change Status** to update the ticket lifecycle status.
5. Click **Link Asset** (visible when no asset is linked) to associate an IT asset.
6. Switch to the **Comments** tab to add or read comments.
7. Switch to the **Security** tab to view linked security incidents or create a new one from this ticket.

**Key fields:**

* **ticket\_number** — system-assigned identifier displayed in monospace in the header.
* **TicketPriority** — priority level of the ticket.
* **TicketStatus** — lifecycle status of the ticket.
* **SLA** — service-level tracking shown via `SLAIndicator` (compact) and `SLATrackingCard` (sidebar).
* **linked\_asset\_id** — optional reference to an IT asset associated with this ticket.
* **Security escalation** — a ticket can be used to create a linked security incident via the Security tab.

## Creating a ticket

The New Ticket page (`/it/tickets/new`) renders a `TicketForm` alongside a `SuggestedArticlesCard` that shows matching knowledge base articles as the user types the ticket subject (debounced at 300 ms). The suggestion limit is read from IT module settings (`kb_suggestion_limit`, default 5). On success the user is redirected to the new ticket's detail page at `/it/tickets/:id`.

Permission required: `IT_PERMISSIONS.VIEW` (`it.view`) via the module-level `ITViewGuard`. No additional per-route gate.

1. Navigate to **IT > Tickets** and click **New Ticket**, or go directly to `/it/tickets/new`.
2. Enter the **Subject** — knowledge base article suggestions will appear as you type.
3. Select the **Category** and **Ticket Type**.
4. Set the **Priority**.
5. Optionally link an **Asset** and select the **Site**.
6. Enter a **Description**.
7. Review any suggested knowledge base articles in the sidebar panel — they may resolve the issue without creating a ticket.
8. Click the submit action. On success you are redirected to the ticket detail page.

**Key fields:**

* **Ticket type** — classification of the request (e.g., incident, service request).
* **Category** — domain grouping within the ticket type.
* **Linked asset** — an IT asset associated with the ticket, stored as `linked_asset_id`.
* **KB suggestions** — real-time article matches from `useSuggestedKnowledgeBaseArticles` based on the ticket subject and category.

## Related

<Columns cols={2}>
  <Card title="IT Service Management" icon="headset" href="/it/overview">
    IT Service Management overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</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/it.tsx
  * src/cores/it/pages/tickets/TicketListPage.tsx
  * src/cores/it/pages/tickets/TicketDetailPage.tsx
  * src/cores/it/pages/tickets/NewTicketPage.tsx
  * src/cores/it/hooks/useTickets.ts
  * src/cores/it/hooks/useTicket.ts
  * src/cores/it/hooks/useTicketComments.ts
  * src/cores/it/hooks/useTicketMutations.ts
  * src/cores/it/hooks/useSuggestedKnowledgeBaseArticles.ts
  * src/cores/it/components/tickets/TicketForm.tsx
  * src/cores/it/components/tickets/index.ts
</Accordion>