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

# Routing Tickets to Gradial Workspaces

> Configure routes to control which tickets Gradial ingests from your ticketing system and how they are organized into workspaces.

## What is a Route?

A route is a filter configuration that tells Gradial:

* **Which tickets to ingest** — Based on project, status, labels, or custom queries
* **How to organize them** — Flat (all siblings) or hierarchical (preserving parent-child relationships)
* **Where to place them** — The destination folder in Gradial

## Creating a Route

1. Go to **Organization Settings → Integrations**
2. Select your integration (Jira, Wrike, Workfront, Asana, or monday.com)
3. Click **Add Route**
4. Configure your filters (see system-specific options below)
5. Choose your ingestion mode
6. Click **Save Route**

***

## Ingestion Modes

### Hierarchical Ingestion (Recommended)

Hierarchical ingestion preserves the organizational structure from your external system:

* Parent-child relationships are maintained
* Epics contain their stories, projects contain their tasks
* Context flows from parent to child threads
* Items are automatically classified as folders or tickets

**When to use:** Most production scenarios where organizational context matters.

### Flat Ingestion

Flat ingestion pulls tickets as a simple list:

* All tickets become siblings at the same level
* No parent-child relationships preserved
* Simpler but loses organizational context

**When to use:** Simple use cases where hierarchy doesn't matter, or when testing.

***

## How Hierarchical Classification Works

When using hierarchical ingestion, Gradial automatically determines whether each item is a **folder** (organizational container) or **ticket** (actionable work):

**Classification priority:**

1. **Has children** — Items with child items are always classified as folders
2. **System container types** — Known container types (Epics, Projects, Portfolios) become folders
3. **AI classification** — For ambiguous items, AI analyzes the title and description to determine intent

This means an Epic with Stories will always be a folder containing ticket children, while a standalone Bug will be a ticket.

***

## System-Specific Filter Options

### Jira Filters

| Filter         | Description                                 | Example                                     |
| :------------- | :------------------------------------------ | :------------------------------------------ |
| **Project**    | Limit to specific Jira projects             | `PROJ`, `TEAM`                              |
| **Issue Type** | Filter by issue type                        | Epic, Story, Task, Bug                      |
| **JQL Query**  | Advanced filtering with Jira Query Language | `project = PROJ AND status = "In Progress"` |
| **Labels**     | Filter by Jira labels                       | `gradial`, `ai-process`                     |

**JQL Examples:**

* All open bugs: `project = PROJ AND type = Bug AND status != Done`
* Recently updated: `project = PROJ AND updated >= -7d`
* Specific epic's children: `"Epic Link" = PROJ-123`

### Wrike Filters

| Filter     | Description                    | Example                |
| :--------- | :----------------------------- | :--------------------- |
| **Space**  | Limit to specific Wrike spaces | Marketing, Engineering |
| **Folder** | Filter to specific folders     | Q4 Campaigns           |
| **Status** | Filter by task status          | Active, Completed      |

### monday.com Filters

| Filter          | Description                                       | Example       |
| :-------------- | :------------------------------------------------ | :------------ |
| **Board ID**    | The single monday.com board the route syncs from  | `18421333785` |
| **Search Term** | Keyword filter — only matching items are ingested | `homepage`    |

Each monday.com route targets exactly one board. To sync multiple boards, create one route per board.

### Workfront Filters

| Filter        | Description                  | Example           |
| :------------ | :--------------------------- | :---------------- |
| **Portfolio** | Limit to specific portfolios | 2024 Initiatives  |
| **Program**   | Filter by program            | Product Launch    |
| **Project**   | Filter by project            | Website Redesign  |
| **Status**    | Filter by task status        | Current, Planning |

***

## Route Best Practices

**Start small, expand gradually**

* Begin with a single project or folder
* Verify the ingestion looks correct
* Gradually expand your filter scope

**Use specific filters**

* Avoid overly broad filters that pull in thousands of tickets
* Use labels or status filters to limit scope
* Review the preview before confirming ingestion

**Consider your hierarchy**

* If you use hierarchical ingestion, understand what parent items will be pulled in
* Ancestors of matching items may be fetched to provide context

**Monitor thread counts**

* After initial ingestion, verify you got the expected number of threads
* Check that folders and tickets are classified correctly

***

## Previewing Before Ingestion

Before running an ingestion, Gradial shows a preview of what will be created:

1. **Total item count** — How many threads will be created
2. **Folder vs ticket breakdown** — How items will be classified
3. **Hierarchy tree** — Visual representation of parent-child relationships

Review this preview carefully, especially for hierarchical ingestion. If you see unexpected items or counts, refine your filters before proceeding.

***

## Sync Behavior

Once a route is configured:

* **Initial ingestion** — All matching tickets are pulled into Gradial
* **Ongoing sync** — New and updated tickets are synced automatically (every 5 minutes)
* **Bidirectional updates** — Comments and attachments sync both directions

## Troubleshooting Routes

**Too many tickets ingested**

* Review and narrow your filters
* Add status or label filters to reduce scope

**Missing tickets**

* Check that tickets match your filter criteria
* Verify your service account has access to those tickets

**Wrong classification (folder vs ticket)**

* Tickets with children are always folders
* Check if items have subtasks or child issues