> For the complete documentation index, see [llms.txt](https://docs.logilica.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.logilica.com/integration/connecting-tools/youtrack.md).

# YouTrack

This guide covers how Logilica imports issues, states, types, sprints, and history from YouTrack, and how to prepare your YouTrack instance so all your data is categorised correctly. YouTrack's flexible field system requires specific naming and configuration to ensure Logilica can recognise and categorise your data.

## Authentication

Logilica connects to your YouTrack instance using a **permanent token** issued from your YouTrack account. The token is sent as a bearer token on every request and grants read access to the projects you import. The permanent token needs the `YouTrack` scope. You also provide your YouTrack instance address so Logilica knows which server to call. See [Connecting Tools](/integration/connecting-tools.md) for the general installation flow.

## What's Imported

For each YouTrack project you connect, Logilica imports:

* **Issues** — summary, description, type, state, priority, labels/tags, and created/updated/resolved dates
* **Assignees and reporters** — user identity, name, and email
* **Issue history** — created, assignee changes, state changes, resolution, and sprint-change events
* **Sprints** — name, start/end dates, and goal
* **Parent/child relationships** — subtasks, parent issues, and the full ancestor chain
* **Story point estimates** — taken from a custom field (see Name Your Story Points Field Correctly below)
* **Custom fields** — all other custom fields and their values are imported alongside the built-in fields
* **Optional tracking fields** — developer, reviewer, and tester assignment events when those custom fields are present (see Add Optional Tracking Fields below)

{% hint style="info" %}
If your issue descriptions contain sensitive content, you can exclude them after installation with the **Ignore Ticket Description** toggle under **Import Configuration** on the connector page.
{% endhint %}

The sections below cover the fields and settings that need specific naming or configuration to import correctly.

## Mark Completion States as Resolved

Logilica categorises every issue state as **To Do**, **In Progress**, or **Done**. The most reliable way to get accurate Done classification is to use YouTrack's built-in Resolved flag:

1. Go to **Administration > Custom Fields** (or your project's field settings)
2. Open your **State** field's bundle
3. For each state that represents completion, check the **Resolved** checkbox

Any state marked as Resolved will always appear as **Done** in Logilica, regardless of its name.

Without the Resolved flag, Logilica falls back to matching by name. Only these specific names are recognised:

| Category        | Recognised State Names                                                                               |
| --------------- | ---------------------------------------------------------------------------------------------------- |
| **Done**        | `Fixed`, `Submitted`, `Won't fix`, `Obsolete`, `Can't Reproduce`, `Closed`, `Duplicate`, `No Action` |
| **In Progress** | `In Progress`, `Verified`                                                                            |
| **To Do**       | Everything else                                                                                      |

Custom state names like `In Review`, `QA`, or `Deployed` will default to **To Do** unless marked as Resolved.

## Keep Default Field Names

Logilica reads these YouTrack fields by their exact name:

| Field Name   | Used For                                     |
| ------------ | -------------------------------------------- |
| `Type`       | Issue type (Bug, Task, Epic, etc.)           |
| `State`      | Status category (To Do / In Progress / Done) |
| `Priority`   | Issue priority                               |
| `Estimation` | Due date calculation                         |
| `Assignee`   | Current assignee                             |

If you've renamed any of these (e.g., `Status` instead of `State`), they won't be recognised.

## Name Your Story Points Field Correctly

To import story point estimates, your YouTrack project needs a custom field named exactly **`story points`** — lowercase, with a space.

`Story Points`, `SP`, `Points`, or any other variation won't be picked up.

## Use Standard Issue Type Names

Logilica recognises common issue type names to build the correct work hierarchy. Types such as `Epic`, `Story`, `Bug`, and `Task` are categorised automatically, with higher-level types (like `Epic`) grouped as epics and the rest treated as standard issues. Issues with no type default to `Task`.

If your project uses custom type names that don't match the standard ones, contact your Logilica administrator — this mapping requires a direct configuration change and is not available in the UI.

## Add Optional Tracking Fields

If your team tracks who developed, reviewed, or tested an issue beyond the assignee, create these custom fields in YouTrack:

| Custom Field Name | What Logilica Tracks        |
| ----------------- | --------------------------- |
| `Developed By`    | Developer assignment events |
| `Reviewed By`     | Reviewer assignment events  |
| `Tested By`       | Tester assignment events    |

These are optional. If present, changes to these fields appear as distinct events in Logilica's activity timeline. The names are matched case-insensitively.

## Skip Descriptions (Optional)

If your issue descriptions contain sensitive content, you can exclude them after installation with the **Ignore Ticket Description** toggle under **Import Configuration** on the connector page.

## Good to Know

* **Kept in sync automatically.** After the initial import, Logilica refreshes this connection on a regular schedule — you don't need to re-trigger imports.
* **First import covers the last 6 months.** Only issues updated within the last 6 months are imported on the first scan. Older issues that haven't been touched won't appear. Importing data older than 6 months requires a configuration change by Logilica — contact support.
* **Empty sprints won't appear.** A sprint that has never had an issue assigned to it won't show up in Logilica.
* **Comments, attachments, and work logs are not imported.** The `Spent time` field value is captured as a custom field, but individual time tracking entries are not imported separately.