> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/service-desk-and-tickets/understanding-service-desk-and-managing-tickets.md). # Understanding Service Desk and Managing Tickets {% hint style="info" %} **Path:** `/tickets/desk/$deskId` (or `/tickets/desk/all` for all desks) {% endhint %} ### Understanding the Service Desk The Service Desk is where you create, triage, and resolve IT support tickets. Tickets can be submitted via Slack, Microsoft Teams, email, or the web portal. The Harmony AI agent handles many requests automatically; human agents handle escalations and complex cases. #### Understanding Desks A **desk** is a service desk that groups teams and tickets. You may have access to one or more desks based on your roles. Each desk has its own teams, custom fields, tags, and canned responses. #### Navigating the Tickets View Open **Tickets** from the sidebar. Routes: * **`/tickets/desk/$deskId`** - Tickets for a specific desk * **`/tickets/desk/all`** - All tickets across desks (when you have access to multiple desks) The main view shows a table of tickets with columns for subject, status, priority, assignee, desk, SLA, and more. Use the toolbar filters and search to find specific tickets. #### Switching Between Different Desks Use the desk selector (sidebar or page header) to switch desks. Select a desk to see only its tickets. #### Viewing All Tickets Across Desks When you have access to multiple desks, choose **All desks** to see tickets from every desk you can access. ![Ticket table with desk selector](/files/ANVkJumqywNtER5mrMft) *** ### Creating and Managing Tickets #### Creating a New Ticket ![Create Ticket dialog with form fields](/files/0uRfwdIahZNDrTrZto2j) Click **Create Ticket** to open the creation dialog. Fill in the form and click **Create**. You can also ask the **IT Copilot** to create a ticket on your behalf. Describe what you need in a conversation and the Copilot will collect all required details - title, ticket type, priority, and service desk - before asking for your confirmation. Nothing is created until you confirm. #### Understanding Ticket Properties | Property | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Title** | Required. Up to 255 characters. | | **Description** | Required. Rich text (markdown). Up to 5000 characters. You can paste images from the clipboard or attach files from the editor. | | **Ticket Type** | Request, Incident, Question, Task, or Change. | | **Priority** | Low, Medium, High, or Urgent. | | **Desk** | Which desk the ticket belongs to. Required. | | **Assignee** | Team member or Harmony AI. Optional; defaults to Unassigned. | | **Reporter** | (Service desk variant) Who reported the ticket. The reporter's office location is displayed next to their name for workload context. | | **Triggered Agent** | A clickable link to the specific AI agent run that was triggered on this ticket, if any. | The Properties section uses a clean horizontal layout with one property per line. The reporter row is fully clickable - selecting the name, location, or dropdown chevron all open the reporter selector. #### Setting Ticket Priority and Status **Priority** is set when creating a ticket. **Status** is changed in the ticket preview panel: use the status selector in the Properties section. Statuses include Open, In Progress, Pending (Reporter, Approval, Internal Team, Third Party), **Pending - On Hold**, Resolved, Closed, Canceled. **Pending - On Hold Status** The **Pending - On Hold** status gives your team a dedicated way to mark tickets that are paused and waiting, without conflating them with other pending states: * **SLA timers pause** automatically while a ticket is on hold, so your metrics accurately reflect active work time. * **All status transitions** are available to and from Pending - On Hold, so agents can move tickets freely without restrictions. * Notifications fire as expected when a ticket enters or leaves this status. #### Attaching Files to Tickets * **Create form:** Use the Attachments dropzone. Drag and drop files or paste images from the clipboard. Files upload before the ticket is created. * **Description editor:** Use the file picker in the Tiptap editor to attach files inline. #### Using Custom Fields in Tickets Custom fields are configured per desk and appear when you select that desk. Supported types: | Type | Control | | ----------------- | ------------------------------------ | | **Text** | Text input | | **Number** | Number input | | **Checkbox** | Yes/No | | **Single Select** | Dropdown with predefined options | | **Multi Select** | Multi-select with predefined options | Mandatory custom fields are marked with an asterisk. Custom fields reset when you change desks. #### Asset Fields for Desk Members When a catalog item includes an asset selector field configured for desk member completion, agents see a searchable asset combobox in the ticket properties panel after the ticket is created. The selected asset is saved automatically. This field is only visible to desk members - portal users do not see or interact with it. #### Creating and Linking Related Tickets When creating a ticket (service desk variant), you can link it to an existing ticket: 1. In the **Linked ticket from your desk** section, choose a **Relationship type**: Relates to, Blocks, Blocked by, Duplicate of, Duplicated by, Depends on, Used by. 2. Use the **Ticket** combobox to search and select the ticket to link. The new ticket is created and linked in one action. #### Viewing Linked External ITSM Tickets If your organization uses external ITSM tools such as ServiceNow or Jira, all active sync mappings for a ticket are available via the API. Pass `include_linked_tickets=true` as a query parameter when fetching a ticket to receive a `linked_tickets` field in the response. Each entry includes the provider name, ticket ID, display ID, and a direct URL so you can navigate straight to the corresponding record. Multiple mappings are fully supported - if a ticket has been exported to more than one tool, all links are returned in a single call. #### Changing Ticket Type with the AI Agent Harmony's AI Service Desk Agent can reclassify the type of an existing ticket without manual intervention. You can ask the agent to change a ticket to any of the following types: * **Request** - a standard service request * **Incident** - an unplanned disruption or service degradation * **Task** - an actionable work item (note: converting away from Task discards its checklist) * **Change** - a planned modification to your environment The agent will confirm the reclassification with you before applying it, following the same confirmation flow as any other field update. #### Creating Tickets from Catalog Forms When an employee submits a catalog item form from the portal or Slack, the ticket is created directly from the saved form values. You receive your ticket confirmation immediately after submitting the form, with no additional processing steps or delays. *** ### Working with Ticket Conversations #### Viewing Ticket Details Click a ticket row to open the **ticket preview panel** on the right. It shows description, properties, SLA, approvals, linked tickets, related assets/software, and chat. ![Ticket preview panel with chat and properties](/files/6Z5kYFIagzHfXgumx10U) #### Understanding the Ticket Preview Panel The preview panel has configurable sections: SLA, Approvals, Properties, Linked tickets, Assigned assets, Assigned software, and Chat. Use the header settings to show, hide, or reorder sections. Some sections (e.g. Approvals, Linked tickets) can be set to "If exist" so they only appear when there is data. #### Seeing Which Agent Was Triggered A **Triggered Agent** field appears in the Properties section of the ticket preview panel as a clickable link, taking you directly to the specific agent run. In the ticket table view, a **Triggered Agent** column is also available - it is shown by default but can be hidden via column settings. #### Resizing the Ticket Chat Panel The chat section has a drag handle at the top. Drag it to resize the chat area. The entire preview panel can also be resized horizontally by dragging the left edge. #### Adding Messages to Tickets Type in the chat input at the bottom and send. You can mark messages as **internal** (visible only to agents) or **external** (visible to the reporter). #### Ticket Status Updates in Conversation Threads Key ticket events are automatically posted as system messages in the relevant conversation thread - whether you are working in Slack, Microsoft Teams, or the Harmony portal. The following events appear as thread messages: * **Ticket created** - a message appears when a new ticket is opened * **Status changed** - updates are shown whenever a ticket's status changes * **Priority changed** - the thread reflects any changes to ticket priority * **Assignee changed** - the thread shows reassignment events This keeps your team fully informed without switching views. #### Using @Mentions in Messages Type `@` to open a list of participants (reporter, assignee, watchers, others in the conversation). Select a person to insert a mention. Mentioned users receive notifications. Mentions use the format `<@employeeId|DisplayName>` and render as clickable badges that link to the person's profile. #### Message Editing During Active Approvals When a ticket is undergoing an active approval process, the edit and delete controls on all conversation messages are automatically hidden. This ensures that content being reviewed cannot be changed mid-decision. Once the approval is completed or overridden, the controls reappear automatically within a few seconds. #### Replying to Ticket Conversations Send messages in the chat. Replies appear in chronological order. You can attach files to messages. #### Viewing Ticket Activity History Activity (status changes, assignments, workflow events, approval actions, etc.) appears in the chat timeline and in the ticket's activity log. The activity timeline now captures all key stages of the workflow and approval lifecycle - see [Workflow Activity in the Timeline](#workflow-activity-in-the-timeline) and [Approval Activity in the Audit Log](#approval-activity-now-visible-in-ticket-audit-log) below for details. #### Workflow Activity in the Timeline Workflow lifecycle events are recorded directly in the ticket activity log. When a workflow starts, progresses through approval steps, or is cancelled, these events appear in the ticket's activity timeline - giving agents and managers a clear picture of what happened and when. This makes it easier to audit workflow execution and understand how automated processes have interacted with a given ticket. *** ### Assigning and Reassigning Tickets #### Assigning Tickets to Team Members Use the **Assignee** selector in the ticket Properties section. You can assign to any employee on the desk (or on the ticket's team when a team is set). #### Assigning Tickets to Teams Use the **Team** selector in Properties to assign the ticket to a team. Team membership filters the assignee list to that team's members. #### Assigning Tickets to AI Agents The assignee selector includes **Harmony AI** as an option. Assigning to Harmony AI routes the ticket to the AI agent for triage and resolution. #### Moving Tickets Between Desks Use **Move to another desk** in Properties. Select the target desk and confirm. The ticket's desk changes; custom fields may reset for the new desk. #### Moving Tickets Between Teams Use **Move to team** in Properties. Select the target team on the same desk. Assignee options update to the new team's members. #### Reassigning Your Tickets Change the assignee in Properties. The previous assignee is replaced by the new one. *** ### Watching Tickets #### Adding Watchers to Tickets You can add any active employee in your organization as a watcher on a ticket - not just desk members or platform admins. The **Add Watcher** picker lists all active employees alphabetically, so you can notify the right people regardless of their role or team membership. #### Automatic Watcher on Comment Any user who posts a comment on a ticket is automatically added as a watcher, keeping them informed of all subsequent activity. This applies to all commenters, not only those who are explicitly mentioned or tagged. Watcher status persists if the ticket is moved to a different desk. AI agent responses do not trigger auto-watching. #### Email CC Recipients as Watchers When a ticket is created via email, anyone CC'd on that email is automatically added as a watcher. This ensures that all relevant parties receive ongoing updates without needing to be added manually. *** ### Using Email as a Service Desk Channel #### Automatic Reply Threading When a user replies directly to an original inbound email, their reply is added as a new message within the existing ticket rather than creating a duplicate ticket. This applies to CC'd users and any other recipients replying to the original email. #### CC Recipients Added as Watchers When a ticket is created via email, anyone CC'd on that email is automatically added as a watcher so they receive updates throughout the ticket's lifecycle. *** ### Using Canned Responses #### What are Canned Responses? Canned responses are reusable templates for common replies. Insert them into ticket messages to save time and keep responses consistent. #### Creating Canned Response Templates Canned responses are created in desk settings (Settings → Tickets → Canned Responses). Each template has a name, content, availability (Personal or Shared), and optional attachments. #### Searching and Inserting Canned Responses In the ticket chat, use the canned response action to open the **Search canned responses** dialog. Search by name, preview the content, and click to insert. Variables in the template are replaced with current ticket data before insertion. ![Search canned responses dialog](/files/BnNBGY5kW14gUFsLKcnE) #### Using Variables in Canned Responses Insert variables into templates. They are replaced when the template is used: | Variable | Replaced with | | ------------------------ | ------------------- | | `{{ticket.subject}}` | Ticket title | | `{{ticket.id}}` | Ticket ID | | `{{ticket.description}}` | Ticket description | | `{{ticket.reporter}}` | Reporter name | | `{{ticket.agent}}` | Assignee/agent name | | `{{ticket.status}}` | Status | | `{{ticket.priority}}` | Priority | | `{{ticket.source}}` | Source | | `{{ticket.ticket_type}}` | Type | | `{{desk_name}}` | Desk name | | `{{currentUser}}` | Current user name | | `{{portalUrl}}` | Portal URL | #### Creating Personal vs Shared Canned Responses When creating a template, set **availability** to Personal (only you) or Shared (all desk members). #### Managing Canned Response Attachments Templates can include attachments. Upload them when creating or editing the template. Attachments are included when the template is inserted. *** ### Working with Knowledge Base Solutions #### Inserting KB Solutions into Tickets When a ticket has a **KB resolution** (AI-suggested solution from the knowledge base), you can use **Respond with knowledge base solution**. A modal shows the answer summary. Use **Add as comment** to insert it as a message (from Harmony AI) into the ticket. {/\* IMAGE: Respond with knowledge base solution modal → /guides/understanding-service-desk-and-managing-tickets/screenshots/kb-solution-modal.png | UI: frontend-app/src/features/service-desk/components/kb-solution-modal.tsx | Route: /tickets/desk/$deskId \*/} #### Using the KB Solution Search The KB solution is surfaced when the AI finds a matching article. The modal displays the summary and sources. You can copy the answer or add it as a comment. *** ### Understanding AI Insights and Classification #### How AI Insights Work Harmony's AI automatically classifies tickets to suggest category, priority, summary, and desk routing. AI Insights use the ticket's title, description, and conversation history as primary inputs - so the most informative fields on a ticket directly shape routing and priority suggestions. #### AI Re-classification on Title and Description Changes When you update a ticket's title or description, AI Insights automatically re-classify the ticket. This ensures that category, priority suggestion, summary, and desk routing always reflect the current state of the ticket rather than only its comment history. Previously, changes to these key fields could leave triage results stale; now they are included as first-class inputs alongside comments. *** ### Triggering Custom Agents from Tickets #### Using Custom Agents on a Ticket A **Custom Agents** section in the ticket sidebar lists all your manually-triggerable agents. You can trigger any of them directly from the ticket view without leaving the conversation: * **Search agents by name** to quickly find the right one. * A **confirmation step** ensures agents are never triggered accidentally. * **Ticket context is automatically injected** - the current ticket, desk, and requester are passed into the agent so you do not need to fill them in manually. *** ### Using the IT Copilot for Tickets #### Creating Tickets with the Copilot Ask the IT Copilot to create a new support ticket by describing what you need. The Copilot collects all required fields - title, type, priority, and service desk - through a natural conversation, then asks for your confirmation before submitting. Nothing is created without your explicit approval. #### Updating Tickets with the Copilot The Copilot can update ticket fields on behalf of agents during a conversation. It can modify priority, status, assignee, and other ticket fields in real time through tool calls, keeping tickets accurate as conversations progress. *** ### Managing Ticket Approvals #### Understanding Ticket Approvals Some tickets require approval before they can proceed. Approvals are configured in workflows and appear in the ticket's Approvals section when present. #### Viewing Ticket Approval Status The **Approvals** section in the ticket preview shows each approval step with status: Requested, Pending, Approved, Rejected, or Removed (cancelled). Approvers are displayed with avatars. {/\* IMAGE: Approvals section in ticket preview → /guides/understanding-service-desk-and-managing-tickets/screenshots/ticket-approvals-section.png | UI: frontend-app/src/features/service-desk/components/ticket-preview/ticket-approvals-section.tsx | Route: /tickets/desk/$deskId \*/} #### Approving and Denying Ticket Requests Approval actions (approve/deny) are available from the Approvals section or workflow actions when the ticket is in an approval state. Exact UI depends on workflow configuration. #### Approval Outcomes Posted to the Ticket Thread When a workflow approval resolves, an internal note is automatically posted to the ticket thread summarising the outcome. The note includes whether the request was approved or denied, who made the decision, and any reason provided for a denial. This gives agents full visibility into what happened without leaving the ticket view. #### Cancelling a Ticket Approval Desk managers can cancel an approval requirement on a ticket at any point before a decision is made, without it counting as an approval or denial: * The cancelled approval is shown as **removed** in the Approvals card - not approved and not rejected. * Pending approvers are automatically notified via Slack or Teams that their approval is no longer needed, and any scheduled reminders are stopped. * The cancellation is recorded in the ticket's activity log for full auditability. #### Understanding Approval Chains Multiple approval steps are shown in order. A connector indicates flow: once a step is approved, the next can proceed. Rejected steps halt the chain. #### Approval Activity Now Visible in Ticket Audit Log The activity timeline captures all key stages of the approval lifecycle: * **Approval requested** - logged each time an approval request is sent to an approver * **Approved** - logged when an approver accepts the request * **Rejected** - logged when an approver declines the request * **Overridden** - logged when an admin overrides the approval decision * **Cancelled** - logged when an approval requirement is removed before a decision Each event appears in the timeline with the relevant user and a description, giving you a complete audit trail without leaving the ticket view. *** ### Closing Tickets #### Closing Tickets with Comments To close a ticket, change the status to Resolved or Closed. If **mandatory close comment** is enabled for the desk, a dialog prompts for an internal comment (min 3 characters) before closing. Enter the comment and confirm. {/\* IMAGE: Mandatory close comment dialog → /guides/understanding-service-desk-and-managing-tickets/screenshots/close-ticket-comment-dialog.png | UI: frontend-app/src/features/service-desk/components/close-ticket-comment-dialog.tsx | Route: /tickets/desk/$deskId \*/} #### Understanding Ticket Closure Workflow Closing moves the ticket to Resolved or Closed. The ticket remains in the list but is excluded from "open" filters by default. #### Ticket Status After Closure Resolved and Closed are terminal states. Reopening requires changing status back to Open or In Progress, if your workflow allows it. *** ### Understanding and Tracking SLA #### Understanding SLA Policies SLA policies define response and resolution targets per desk. They are configured in desk settings. #### Understanding SLA Timers Each ticket can have SLA timers: **Response** (time to first reply) and **Resolution** (time to resolve). Timers start when the ticket is created and may pause based on status or business hours. SLA timers also pause automatically when a ticket is set to **Pending - On Hold**. #### Viewing Ticket SLA Status The **SLA** section in the ticket preview shows each timer with deadline, hours remaining, and status (e.g. in progress, completed, breached). Expand to see details. ![SLA section in ticket preview](/files/Z6wzJqH3M5WNfLpEE0oC) #### Track --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.harmony.io/service-desk-and-tickets/understanding-service-desk-and-managing-tickets.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.