> 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/routing-and-auto-assigning-tickets.md).

# Routing and Auto-Assigning Tickets

How Harmony routes each ticket to a desk, a team and an assignee, and how to configure auto-assignment for a whole desk or for a single team.

{% hint style="info" %}
**Paths:** Desk assignment: `/settings/desks/$deskId/automation` · Teams and routing: `/settings/desks/$deskId/members` · Team assignment: `/settings/desks/$deskId/teams/$teamId`
{% endhint %}

Every new ticket goes through three steps: Harmony picks a **desk**, then a **team** inside that desk, then an **assignee** inside that team. You can automate each step, and you can set auto-assignment for the whole desk or for each team on its own.

{% hint style="warning" %}
**Auto-assignment uses the settings of the team the ticket lands in.** The **Ticket assignment** card in the desk's **Automation** tab applies to the desk's **Unassigned Team** only. A ticket routed to any other team uses that team's own auto-assignment settings. If that team's auto-assignment is off, the ticket stays unassigned, even when the desk-level setting is on.
{% endhint %}

### Understanding Routing and Assignment

#### Key Terms

| Term                    | Meaning                                                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Desk**                | A service desk for one kind of work, such as IT, HR or Finance. Every ticket belongs to exactly one desk.                                                    |
| **Team (subdesk)**      | A group of desk members inside a desk, with its own time zone, working hours, SLA targets and auto-assignment. Every desk has a default **Unassigned Team**. |
| **Desk Admin**          | Has an Admin grant on the desk. Can change the desk's settings, teams and auto-assignment.                                                                   |
| **Desk Member**         | Can be assigned tickets, including by auto-assignment, and can be added to teams.                                                                            |
| **Desk Viewer**         | Has a Viewer grant on the desk. Can view its tickets but is never auto-assigned.                                                                             |
| **Team routing method** | The rule that picks a team for a new ticket: by time zone or by team description.                                                                            |
| **Assignment method**   | The rule that picks an assignee: Round-robin, Least-loaded, Least-loaded (throughput-balanced), Fixed, or First responding agent.                            |

#### How a Ticket Reaches a Desk

| Where the request starts                                       | How the desk is chosen                                                                    |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Slack channel linked to a desk**                             | Always that desk. The AI agent does not choose. A channel can be linked to only one desk. |
| **Conversation with the AI agent** (Slack, Teams, Portal)      | The AI agent picks the best desk from the request and each desk's description.            |
| **Email**                                                      | The desk whose email address received the message.                                        |
| **Created manually, by API, or by a workflow**                 | The desk chosen by the person or the workflow.                                            |
| **Imported from an ITSM tool** (Jira, JSM, ServiceNow, others) | Set by the import mapping. Imported tickets are not auto-assigned.                        |

To link a Slack channel, open the desk and use **Slack channels**. To guide the AI agent, write a clear desk description (up to 1,000 characters).

#### How a Ticket Reaches a Team

Each desk has a **team routing method**. Set it in **Members & Teams** → **Teams** → **Configure routing method for teams**.

{% hint style="info" %}
Team routing currently applies only to tickets created by the AI agent. Tickets created in other ways (manually, by email, by API or by a workflow) go to the team specified when the ticket is created, or to the **Unassigned Team** if none is specified.
{% endhint %}

| Routing method                          | How the team is chosen                                                                                                                  |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Route tickets by timezone** (default) | The team whose time zone is closest to the reporter's. If the reporter has no time zone, the ticket goes to the Unassigned Team.        |
| **Route tickets by team description**   | The AI agent picks the team whose description best matches the request. Use **How to write a description for AI routing** for guidance. |

Changing the routing method prompts a confirmation dialog first.

***

### Configuring Auto-Assignment

Auto-assignment picks an assignee when a ticket arrives without one. Changes save immediately. There is no Save button.

#### Assignment Methods

| Method                                 | Who gets the ticket                                                                                                                                                                                                                                                                              |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Round-robin** (default)              | The next agent in a fixed rotation, so each agent gets an equal turn.                                                                                                                                                                                                                            |
| **Least-loaded**                       | The agent with the fewest tickets in **Open** or **In Progress** status across the whole desk.                                                                                                                                                                                                   |
| **Least-loaded (throughput-balanced)** | The agent with the lowest score, where score = the agent's open tickets in this team + tickets auto-assigned to them today. Agents who reach the **Open tickets threshold** (default 6) are skipped. The daily count resets at the **Daily reset time** (default 00:00) in the team's time zone. |
| **Fixed**                              | Always the one agent you choose. If that agent can't take tickets, the ticket stays unassigned.                                                                                                                                                                                                  |
| **First responding agent**             | No one at creation. The first Desk Member who sends a public reply becomes the assignee. Harmony AI and the reporter are never picked.                                                                                                                                                           |

When two agents tie, the rotation order breaks the tie.

#### Choosing Who Can Be Assigned

* **Scope** limits auto-assignment to the agents you select. Leave it empty to include every Desk Member in the desk or team.
* Desk Viewers and Harmony AI are never auto-assigned.
* Agents who leave the team or are terminated drop out automatically. Scope members who are terminated or no longer on the desk are shown in red.

#### Assigning Only to Members on Shift (Google Calendar)

Available for Round-robin and both Least-loaded methods. Harmony reads a shared Google Calendar that holds your shift schedule.

1. Share the shift calendar with the Google account that connected the Google Workspace integration.
2. Select **Only assign to members on shift (Google Calendar)**.
3. Enter the **Shift calendar ID** (in Google Calendar: **Settings** → **Integrate calendar** → **Calendar ID**), then select **Check calendar**.
4. Under **When nobody is on shift**, choose what happens if no one is on shift or the calendar can't be read: assign across all agents (Least-loaded, Least-loaded throughput-balanced, or Round-robin), or **Leave unassigned**.

An agent is on shift while a shift event is running and the agent is a guest on it, or the agent's work email is in the event title. Names alone are not matched.

#### Assigning Only During Working Hours

Select **Only assign during the team's working hours** to use the team's working hours and holidays from its SLA settings. Tickets that arrive outside those hours stay unassigned and are not assigned automatically later. A team without its own hours counts as always open.

#### Skipping Members Who Are Out of Office

Available for Round-robin and both Least-loaded methods. Select **Skip members who are currently out of office** to skip agents with out-of-office time today.

* Under **Consider OOO from these sources**, choose which sources count. Leave it empty to use all sources. Sources include **Manual**, Google Calendar out-of-office events, Outlook calendar, HiBob, and HRIS tools such as SAP SuccessFactors. See [Syncing Out-of-Office Status from HRIS and Google Workspace](https://docs.harmony.io/people-management/syncing-out-of-office-status-from-hris-and-google-workspace.md).
* If every agent in scope is out of office, Harmony still assigns the ticket rather than leaving it unassigned.
* To keep certain tickets with their current assignee, create a **Dispatching rule** with **Exclude ticket from OOO logic reassignment** in the desk's **Automation** tab.

#### When Auto-Assignment Runs

| Event                                        | Auto-assignment runs?                                                                                                |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| New ticket with no assignee                  | Yes                                                                                                                  |
| Harmony AI hands the ticket to a human       | Yes                                                                                                                  |
| Ticket moved to another desk or team         | Yes, unless the current assignee is in the new team (they keep it) or you choose an assignee while moving the ticket |
| Ticket moved by a workflow or the AI agent   | Yes, even if the current assignee is in the new team                                                                 |
| New ticket created with an assignee          | No                                                                                                                   |
| Ticket reopened, or assignee removed by hand | No                                                                                                                   |
| Ticket imported from an ITSM tool            | No                                                                                                                   |

***

### Desk-Level vs. Team-Level Assignment

Each team has its own auto-assignment settings, with the same methods, scope and filters as the desk. You can turn on auto-assignment for one team without turning it on for the whole desk.

| Ticket lands in     | Settings used                                 | If auto-assignment is off there                                         |
| ------------------- | --------------------------------------------- | ----------------------------------------------------------------------- |
| **Unassigned Team** | Desk → **Automation** → **Ticket assignment** | The ticket stays unassigned                                             |
| **Any other team**  | Team → **Settings** → **Auto-assignment**     | The ticket stays unassigned, even if the desk's Ticket assignment is on |

{% hint style="warning" %}
New teams start with auto-assignment off. If you route tickets to teams (for example by time zone), turn on auto-assignment in every team that should assign tickets.
{% endhint %}

**Common setups**

* **Only one team auto-assigns** - Turn it on for that team only. Tickets in the other teams wait for someone to pick them up.
* **Each team uses its own method** - For example, Tier 1 uses Round-robin and Tier 2 uses Least-loaded. Set each team's method separately.
* **One rotation across the whole desk** - Keep all agents in the Unassigned Team and route all tickets there.

The **Auto-assignment** column in **Members & Teams** → **Teams** shows each team's status and method at a glance.

***

### Setting Up Auto-Assignment

#### Setting Up Desk-Level (Unassigned Team) Assignment

1. Go to **Settings** → **Desks** and select the desk.
2. Under **Configurations**, select **Automation**.
3. In **Ticket assignment**, turn on **Auto-assign tickets among desk operators**.
4. Choose an **Assignment method**.
5. Optional: in **Scope**, select the agents who can receive tickets. Leave it empty for all Desk Members.
6. Optional: turn on the shift, working-hours and out-of-office options.

#### Setting Up Assignment for a Team

1. Go to **Settings** → **Desks**, select the desk, then select **Members & Teams**.
2. Open the **Teams** tab and select the team. To create one, select **Create team**. You can turn on **Auto-assign new tickets to team agents** in the create dialog.
3. Open the team's **Settings** tab.
4. In **Auto-assignment**, turn on **Auto-assign tickets among team operators**.
5. Choose an **Assignment method** and, optionally, a **Scope** of team members.
6. Optional: turn on the shift, working-hours and out-of-office options.
7. Repeat for every team that should auto-assign.

{% hint style="info" %}
**Fixed** needs at least one team member. Agents must be desk members before you can add them to a team.
{% endhint %}

#### Checking the Routing Method

1. In **Members & Teams** → **Teams**, review **Configure routing method for teams**.
2. Make sure tickets reach the teams you configured. With **Route tickets by timezone**, give every team a time zone. With **Route tickets by team description**, write a clear description for each team.

***

### Troubleshooting

| Symptom                                                 | Likely cause                                                                                                | What to do                                                                                                                                          |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Desk auto-assignment is on, but tickets stay unassigned | The tickets were routed to a team whose own auto-assignment is off                                          | Turn on auto-assignment in that team's **Settings** tab                                                                                             |
| Tickets stay unassigned outside business hours          | **Only assign during the team's working hours** is on                                                       | Expected. Assign these tickets manually, or turn the option off                                                                                     |
| An agent never receives tickets                         | They are not in scope, they are a Desk Viewer, they are not in the ticket's team, or they are out of office | Check the scope, the agent's role and team membership, and their availability                                                                       |
| An out-of-office agent still received a ticket          | Everyone in scope was out of office, or a dispatching rule excludes the ticket from OOO logic               | Check the other agents' availability and the desk's dispatching rules                                                                               |
| Shift assignment falls back to all agents               | No one was on shift, or the calendar couldn't be read                                                       | Select **Check calendar**. Make sure the calendar is shared with the integration account and agents are event guests or named by email in the title |
| The Fixed method assigns no one                         | The fixed agent left the team or was terminated                                                             | Choose a new agent                                                                                                                                  |
| Imported Jira or ServiceNow tickets are not assigned    | Imported tickets skip auto-assignment                                                                       | Assign them in the source tool or manually                                                                                                          |
| A ticket kept its assignee after moving desks           | The assignee is also a member of the new team                                                               | Expected. Choose a new assignee while moving the ticket                                                                                             |

***

### Related Resources

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Service Desks &#x26; Teams</strong></td><td>Desk structure, teams, members, and working hours</td><td><a href="https://docs.harmony.io/settings/managing-service-desks-and-teams.md">Managing Service Desks and Teams</a></td></tr><tr><td><strong>Automation &#x26; SLA</strong></td><td>Status management, auto-close, surveys, and SLA policies</td><td><a href="https://docs.harmony.io/settings/configuring-automation-and-sla.md">Configuring Automation and SLA</a></td></tr><tr><td><strong>Out-of-Office Sync</strong></td><td>Sync time off from your HRIS and Google Workspace</td><td><a href="https://docs.harmony.io/people-management/syncing-out-of-office-status-from-hris-and-google-workspace.md">Syncing Out-of-Office Status from HRIS and Google Workspace</a></td></tr><tr><td><strong>Service Desk &#x26; Tickets</strong></td><td>Work with tickets once they are assigned</td><td><a href="https://docs.harmony.io/service-desk-and-tickets/understanding-service-desk-and-managing-tickets.md">Understanding Service Desk and Managing Tickets</a></td></tr></tbody></table>

***

## Where to find in the UI

Only desk admins can open these settings.

1. Open **Settings** in the sidebar, at `/settings`.
2. Select **Desks**, at `/settings/desks`, then choose a desk.
3. For desk-level (Unassigned Team) assignment, open **Automation**, at `/settings/desks/{deskId}/automation`.
4. For the team routing method, open **Members & Teams** → **Teams**, at `/settings/desks/{deskId}/members`.
5. For a team's assignment, select the team and open its **Settings** tab, at `/settings/desks/{deskId}/teams/{teamId}`.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/service-desk-and-tickets/routing-and-auto-assigning-tickets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
