Helpdesk overview

Enterprise feature (new in 1.19.0): requires the enterprise image and an Enterprise license. From 1.19.1 every valid Enterprise license includes the helpdesk (feature key helpdesk), including keys issued before 1.19. See Enterprise edition.

The helpdesk is a simple-to-run internal service desk for a small business. The people who ask for help are your own workspace’s users, so there are no customer accounts to manage: an IT, HR or Facilities team answers colleagues, with the same sign-in, the same directory and the same documents CompassDocs already has. From 1.19.1 you can also open a customer portal for people outside your organisation, who sign in with an email link and see only their own requests.

It has two halves, each in its own place:

• Get help (/help) is where everyone asks. It sits inside the normal CompassDocs app, in the sidebar after Handbooks. People search your guides first, pick a request type, fill in its form, and follow their requests and approvals. See Get help.
• The desk (/desk) is where agents work. It is a full-screen workspace of its own, with no CompassDocs sidebar, designed to stay open in its own browser tab beside CompassDocs, and it can be installed as an app with push notifications. See The desk.

Behind them sit teams with their own office hours and reply targets, request types with forms, workflows that route a request through approvals and tasks across several teams, assignment rules, an email channel, alert intake from monitoring tools, contact cards from the directory, automations, macros, a satisfaction survey and reports. From 1.19.2 they are joined by major incidents, status services for teams, skills and languages, checklists and canned responses, from 1.19.3 by assets from Snipe-IT on tickets, and from 1.19.4 by chat apps for Teams and Slack, API tokens and webhooks, a help centre in the customer portal, devices from Microsoft Intune, desk artwork, sharing and printing tickets and a recycle bin for deleted tickets. From 1.20.0 agents can work a ticket with Claude in the desk, a Claude chat docked beside it.

What’s where

You want to	Go to
Ask for something, follow your requests, decide an approval	Get help in the sidebar (/help, /help/requests, /help/approvals)
Work tickets	Desk in the sidebar, which opens /desk in a new tab
Set the helpdesk up	Desk → Settings, and the setup checklist at /desk/setup
Choose who may work tickets and what they may do	Desk settings → Agents and Roles (see Desk roles)
Change helpdesk emails	Desk settings → Email templates, or Settings → Notifications → Email templates (see Email templates)
Read the numbers	Reports in the desk’s icon rail (see Reports and dashboards)
Let people outside your organisation ask	Desk settings → Customer portal (see Customer portal)
Decide how long tickets are kept	Desk settings → Retention and privacy (see Retention and privacy)
Bring tickets from another helpdesk	Desk settings → Import (see Importing tickets)
Open tickets on a schedule	Desk settings → Recurring tickets (see Recurring tickets)
Work the helpdesk from Claude	Desk settings → Claude connector (see Claude connector: Helpdesk)
Let agents ask Claude beside the ticket, on the workspace’s API key	Desk settings → Claude in the desk (see Claude in the desk)
Handle an outage that affects many people	A ticket’s … menu → Declare a major incident… (see Major incidents)
Choose the Status page services each team follows	Desk settings → Teams (see Status services for teams)
Send tickets to agents who know the subject or speak the language	Desk settings → Skills and languages (see Skills and languages)
Keep reusable lists of steps	Desk settings → Checklists (see Checklists)
Save text agents insert in replies	Desk settings → Canned responses (see Canned responses)
Show the device a ticket is about, from Snipe-IT or Intune	Desk settings → Assets (see Assets, Snipe-IT and Intune)
Let people ask, follow and approve from Teams or Slack	Desk settings → Chat apps (see Chat apps)
Connect other tools with tokens and webhooks	Desk settings → API and webhooks (see API tokens and webhooks)
Let customers find answers before they ask	Desk settings → Customer portal → Help centre (see Customer portal help centre)
Put artwork behind the desk	Desk settings → Appearance (see Desk appearance)
Share a ticket with an agent, or print it	A ticket’s … menu (see Sharing and printing tickets)
Restore a deleted ticket	Recycle bin in the desk’s Views (see Recycle bin)

Who can use it

Five workspace permissions open the helpdesk (see Roles & permissions):

Permission	Key	What it opens	Held by
Get help	helpdesk.request	Raise requests and follow your own	Every built-in role
Work helpdesk tickets	helpdesk.agent	The desk, for the teams you belong to	Administrator, Helpdesk agent, Helpdesk manager
Work every team’s tickets	helpdesk.agent_all	Every team’s queue	Administrator, Helpdesk manager
Configure the helpdesk	helpdesk.admin	Desk settings and reports	Administrator, Helpdesk manager
Read helpdesk reports	helpdesk.reports	Reports	Administrator, Helpdesk manager

Inside the desk, each agent also has a desk role (Newbie, Agent, Team lead, Manager or Admin) that decides what they may do there, and team membership decides which queues they work. See Desk roles.

Without the license, Get help and Desk are not in the sidebar or the command palette, /help and /desk show the license page, and the helpdesk API answers 402.

The setup checklist

The first time someone with Configure the helpdesk opens the desk, it offers the setup checklist (/desk/setup, also Setup at the top of Desk settings). Five steps, each with sensible defaults:

1. Teams. IT, HR and Facilities, with who answers for each. See Teams, hours and reply targets.
2. Hours and reply targets. Monday to Friday, 9:00 to 17:30. Urgent: reply in 1 hour. Everything else: reply in 4 business hours, resolve in 2 business days.
3. Email. Forward your help address to the desk, and replies thread back into the ticket. See Email channel.
4. Request form. The request types people pick in Get help, and any extra questions for each. See Request types.
5. Satisfaction. One question when a ticket is solved: how did we do? See Satisfaction survey.

Use the starter set adds, in one click: the teams IT, HR and Facilities; the starter reply targets; six request types with their workflows (New laptop or device, Access to a space or app, Report a problem, New starter, Ask HR and Facilities repair); three macros; and an example rule (“VPN and network”). Anything you already have is kept, and you can change or remove every part later. Nothing is created until someone chooses it: an upgraded workspace has an empty helpdesk.

A sensible first week

1. Run the checklist with the starter set.
2. Put your agents in their teams (Desk settings → Teams) and give them desk roles (Desk settings → Agents). Give the workspace role Helpdesk agent to people who will work tickets.
3. Set each team’s office hours and holidays.
4. Point your help address at the email channel.
5. Ask agents to install the desk and turn on push notifications.
6. Choose how tickets are assigned.
7. After a week, read the Overview dashboard in Reports.

How a request travels

1. Someone asks in Get help, by email, from a document’s Report a problem with this page, in the customer portal or through Claude, a monitoring tool raises an alert, or a schedule opens one.
2. The request becomes a ticket, numbered from #1001, in a team’s queue. Assignment picks an agent or leaves it in the queue, then automations run.
3. If its request type has a workflow, the workflow starts: approvals, tasks for other teams, waits and messages.
4. Agents reply, add internal notes and change its status. The reply target’s clock runs in the team’s business hours and pauses while the ticket is Waiting on requester or On hold.
5. When it is solved, the requester gets the solved email with the one-question survey, and can reply to reopen it.

Requesters never see internal notes, internal fields or other people’s requests. Agents see their teams’ tickets and tickets assigned to them, unless they may work every team. Approvers see the answers they are asked to approve, not the internal notes.

Statuses and priorities

Status	Agents see	Requesters see
new	New	New
open	Open	Open
pending	Waiting on requester	Waiting on you
on_hold	On hold	On hold
solved	Solved	Solved
closed	Closed	Closed

A ticket whose workflow is still running also shows an In workflow chip. Priorities are Low, Normal, High and Urgent.

Background work

Every minute, each app instance runs the helpdesk’s sweeps: reply target warnings and breaches, workflow waits, task due dates and approval reminders, assignment retries and reassignment, scheduled report emails, and the clean-up of attachments that were uploaded but never sent. From 1.19.1 they also open recurring tickets, run imports, tidy the customer portal’s expired links and sessions, and once a night apply retention when it is on. From 1.19.2 they also run import dry runs in the background, follow the Status page for teams’ services, and tidy old canned response use counts. From 1.19.3, once Snipe-IT is connected, they also sync its assets every 30 minutes. From 1.19.4 they also sync Intune’s devices every 30 minutes while Intune is on, send and retry webhook deliveries, and once a day empty the recycle bin of tickets binned more than 30 days ago. From 1.20.0 they also delete Claude in the desk chats that have no ticket once they have been idle for 90 days. Each sweep claims its own rows, so several instances never do the same work twice. Without the license the sweeps do nothing.

Upgrading to 1.19.0

• Nothing to run. The schema is additive and applied on start: 37 new hd_* tables, plus the tables for email template parts and notification preferences that every edition gets. No existing table changes. The helpdesk stays empty until someone runs the setup checklist.
• License. Add the helpdesk feature to your license and run the enterprise image. See Applying an Enterprise License.
• Permissions. Every built-in role gains Get help (helpdesk.request); the Administrator role gains all five helpdesk permissions. Custom roles gain nothing: add Get help to a custom role whose people should raise requests. Two new built-in roles, Helpdesk agent and Helpdesk manager, are ready to grant. See Roles & permissions. A custom role you had already named “Helpdesk agent” or “Helpdesk manager” keeps its people and permissions; its key moves to helpdesk-agent-custom (or helpdesk-manager-custom), and the move is in the audit log.
• Inbound mail. Mail is linked to a colleague’s account only when your mail provider reports SPF, DKIM or DMARC results that pass. Check that yours does before you point your help address at the desk (see Sender authentication).
• Emails. Every email CompassDocs sends gains the Standard header and Standard footer on upgrade, unless an admin already chose a header or footer of their own. See Email templates.
• Network. Push notifications need HTTPS and outbound access to the browsers’ push services, and your mail provider and monitoring tools must reach the desk’s inbound endpoints. See Helpdesk: network and environment. DATABASE_POOL_WAIT_MS (new, optional) sets how long a request waits for a free database connection before failing: 30 seconds by default, where before it waited forever.
• Rolling back to 1.18.4 is safe: it ignores the new tables. See Updating.

Upgrading to 1.19.1

• Nothing to run. The schema is additive and applied on start: 13 new hd_* tables (CCs, followers, presence, saved views, reply drafts, recurring schedules and their runs, time entries and timers, the customer portal’s contacts, links and sessions, and import jobs), and new columns on hd_tickets, hd_messages and hd_teams. There is no new environment variable.
• Nothing destructive happens on upgrade. Closing solved tickets automatically and anonymising or deleting old tickets are both off until an admin turns them on in Desk settings → Retention and privacy. The customer portal is off too. Removing an account now anonymises that person’s tickets, except tickets on legal hold (see When an account is removed).
• Admins’ replies are no longer held. In 1.19.0 a desk Admin’s public replies waited for review by mistake. From 1.19.1 they are sent straight away. Any still waiting from 1.19.0 are under Reviews: approve and send them there.
• License. Every valid Enterprise license now includes the helpdesk, including keys issued before 1.19, so there is nothing to add to your key. You still need the enterprise image.
• Desk roles. Merge tickets and Bulk edit return to the Roles page, on for Agent and above. A role customised in 1.19.0 gets Merge tickets only if it can change status, and Bulk edit only if it holds a capability that changes a field (see Changing what a role can do).
• Workflows. Waits, task due dates and reminders keep counting calendar time. Business time is a new choice per step.
• Rolling back to 1.19.0 is safe: it ignores the new tables and columns. Tickets anonymised or deleted by retention stay that way. See Updating.

Upgrading to 1.19.2

• Nothing to run. The schema is additive and applied on start: 20 new hd_* tables for canned responses, skills and languages, checklists, major incidents, status services for teams and the desk’s “New” badges, plus hd_tickets.language and language_source and four columns on hd_import_jobs for the background dry run. No existing data changes. There is no new environment variable.
• Nothing destructive happens on upgrade. The new features start empty: no skills, checklists or canned responses, no incidents, and no team follows a Status page service. Assignment works as before until a rule uses skills or the ticket language. New tickets get a language from now on; existing tickets stay Unknown.
• Desk roles. Link tickets to a major incident (Agent and up) and Run major incidents (Team lead and up) are new. A role customised before 1.19.2 gets the first only if it can change status, and the second only if it can also reply to requesters (see Changing what a role can do). The macro capabilities now cover canned responses too.
• Notifications. Three new events: Major incident updates, A service your team uses is down and Import checks (see Notification policies).
• Import API. POST /api/helpdesk/admin/import/<id>/dry-run answers 202 and runs in the background; poll the job until it is ready (see The import API).
• Desk settings show a New badge on Skills and languages, Canned responses and Checklists until each person opens them.
• Rolling back to 1.19.1 is safe: it ignores the new tables and columns. See Updating.

Upgrading to 1.19.3

• Nothing to run. The schema is additive and applied on start: three new tables, hd_assets (the copy of Snipe-IT’s assets), hd_ticket_assets (assets linked to tickets) and hd_asset_maintenance_log (maintenance records logged on a solve). No existing data changes. There is no new environment variable.
• Nothing reaches Snipe-IT until an admin connects it in Desk settings → Assets. The sync runs with the other sweeps, only with the helpdesk licensed and Snipe-IT connected. See Assets and Snipe-IT.
• A Snipe-IT server on a private network needs COMPASSDOCS_FETCH_ALLOW_PRIVATE=1, like other outbound connections (see A Snipe-IT server on a private network).
• Desk roles. No new capability. Connecting Snipe-IT needs Helpdesk settings; linking an asset needs only to work the ticket; logging a maintenance record needs Change status.
• Agents can search all assets is on by default. Turn it off in Desk settings → Assets if agents should see only the assets of people whose tickets they work.
• Desk settings show a New badge on Assets until each person opens it.
• Rolling back to 1.19.2 is safe: it ignores the new tables. See Updating.

Upgrading to 1.19.4

• Nothing to run. The schema is additive and applied on start: 11 new tables, for chat apps (hd_chat_people, hd_chat_threads, hd_chat_drafts, hd_chat_seen), API tokens and webhooks (hd_api_tokens, hd_webhooks, hd_webhook_deliveries), the help centre’s stats (hd_hc_searches, hd_hc_journeys) and desk artwork (hd_desk_art, hd_desk_look), plus new columns: hd_tickets.deleted_at, deleted_by and deleted_by_name (the recycle bin), hd_messages.event (share lines), hd_assets.assigned_upn (Intune) and hd_portal_links.hc_journey. No existing data changes. There is no new environment variable.
• Deleting a ticket now moves it to the recycle bin, where it can be restored for 30 days, and a daily sweep deletes it for good after that. This includes retention’s Delete.
• Desk roles. Delete tickets now means moving tickets to the bin and restoring them. Delete for good is new, Admin only by default. Anyone who could delete for good before now moves tickets to the bin; a role you customised keeps Delete tickets as you set it and never gains Delete for good (see Recycle bin (1.19.4)).
• Nothing new starts on its own. Teams, Slack and Intune stay off until an admin connects them, there are no API tokens or webhooks until someone makes them, the help centre is off, and the desk has no artwork, so it looks as before. Let agents choose their own desk background is off too, so agents get no Desk background… menu row and can’t upload pictures until an admin turns it on.
• Intune needs the directory sync’s app registration to have the DeviceManagementManagedDevices.Read.All application permission, with admin consent (see Microsoft Intune).
• A webhook receiver on a private network needs COMPASSDOCS_FETCH_ALLOW_PRIVATE=1, like other outbound connections (see A receiver on a private network).
• Assets. Disconnecting Snipe-IT (or turning Intune off) now deletes that source’s assets no ticket links; linked ones stay as history. Linking an asset that is gone from its source, came from a replaced source, or whose source is off is refused with the reason (see Linking an asset).
• Checklists. A merge may leave a ticket with more than 10 checklists; adding one is refused at 10, and every one counts for solving (see Checklists).
• Notifications. Two new events: Shared with you (bell, email and push) and Webhook turned off (bell, to the desk’s admins), and a new email template, Helpdesk: ticket shared with you (see Notification policies).
• Desk settings show a New badge on Appearance, Chat apps, and API and webhooks until each person opens them. Customer portal is now three pages: Settings, Help centre and Customers.
• Rolling back to 1.19.3 ignores the new tables and columns, with two things to know first. Tickets in the recycle bin show again as ordinary tickets, since 1.19.3 doesn’t know the bin, and nothing purges them: restore or delete for good what is in the bin before you roll back. The service accounts behind API tokens appear in Settings → Users under their Shown as names. See Updating.

Upgrading to 1.20.0

• Nothing to run. The schema is additive and applied on start: five new tables for Claude in the desk (hd_claude_chats, hd_claude_chat_tickets, hd_claude_messages, hd_claude_cards and hd_claude_usage), and its settings in the settings table (hd_claude_desk). No existing table gains a column and no existing data changes. There is no new environment variable to set (COMPASSDOCS_ANTHROPIC_BASE_URL is for testing only).
• Claude in the desk is off until an admin turns it on in Desk settings → Claude in the desk, and nothing is sent to Anthropic for it until then. Once it is on, the defaults are: every team on, reading, searching, suggesting changes and drafting on, web search off with no sites listed (3 searches per answer once you list some), and no monthly spending limit. Set the limits before you turn it on if you want them (see Spending).
• It needs the Anthropic provider in Settings → AI, with an API key, and the helpdesk licence. It uses the workspace’s key and model, and is billed per use to that key.
• Settings → AI’s model list now offers Claude Opus 5.5 (the default), Claude Sonnet 5.5 and Claude Haiku 5.5. A model you saved before is kept and called as before. A workspace that never saved a model moves to Claude Opus 5.5, unless COMPASSDOCS_AI_MODEL says otherwise (see Choosing a model).
• Proofreading, writing help and Ask say plainly when Claude declines, instead of reporting an error (see When Claude declines).
• The Anthropic SDK (@anthropic-ai/sdk) moves from 0.68 to 1.6.0, which is under the Apache-2.0 licence (0.68 was MIT). That matters only if you track the licences of dependencies.
• A new sweep, with the other helpdesk sweeps: chats with no ticket are deleted after 90 idle days. Chats on a ticket go when the ticket is anonymised or deleted for good.
• Privacy: retention, anonymising, deleting a ticket for good, removing an account and the personal data export all cover the new chats.
• Audit log: new actions helpdesk.claude.chat and helpdesk.claude.card, and changes applied from Claude’s suggestions are marked via: "claude_desk" (see In the audit log).
• Desk settings show a New badge on Claude in the desk until each person opens it.
• Rolling back to 1.19.4 is safe: it ignores the new tables and the new setting, and the Claude button goes. If you saved one of the 1.20.0 models in Settings → AI, 1.19.4 lists it as “(custom)” and calls it the pre-1.20.0 way; choose one of 1.19.4’s own models after rolling back. See Updating.