> 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 permanent token needs the `YouTrack` scope.

Along with the token, enter your YouTrack **service URL**, in one of these forms: `example.youtrack.cloud` or `example.myjetbrains.com/youtrack`. Do not include a protocol prefix such as `https://`, or any trailing path beyond `/youtrack`.

{% hint style="info" %}
**Logilica sees only what the token's account can see.** Use an account with read access to every project you want imported. A service account is the most stable choice, because a personal token stops working when that person leaves.
{% endhint %}

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, state changes, assignee changes, resolution, sprint changes, and changes to any other custom field
* **Sprints** — name, start/end dates, and goal. If one of your issues is moved into a sprint that belongs to another board, that sprint is imported alongside it.
* **Parent/child relationships** — subtasks, parent issues, and the full ancestor chain
* **Story point estimates** — taken from a custom field (see Field & Type Configuration 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 Field & Type Configuration below)
* **Linked pull requests** — see [Linking Pull Requests and Tickets](/integration/linking-pull-requests-and-tickets.md)

{% 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. The setting applies from the next scan onwards, and existing descriptions clear as each issue is next updated in YouTrack. Contact <support@logilica.com> for help if they need to be removed immediately.
{% endhint %}

## Issue State Mapping

Logilica sorts every issue state into **To Do**, **In Progress**, or **Done**. Most workflows need no setup, because common state names are recognised automatically. Capitalisation and spacing do not need to match.

| Category        | Recognised State Names                                                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Done**        | `Fixed`, `Closed`, `Done`, `Complete`, `Released`, `Deployed`, `Merged`, `Duplicate`, `Won't Fix`, `Rejected`, `Cancelled`, and similar   |
| **In Progress** | `In Progress`, `Started`, `Active`, `In Development`, `In Review`, `Code Review`, `Testing`, `In QA`, `Verified`, `Reopened`, and similar |
| **To Do**       | `Open`, `To Do`, `New`, `Backlog`, `Planned`, `Draft`, `On Hold`, `Waiting`, `Blocked`, and anything not recognised                       |

There are two ways to correct a state that lands in the wrong category.

### Use YouTrack's Resolved flag

Any state flagged as Resolved counts as **Done**, whatever it is called:

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

### Ask for a state mapping

Where the Resolved flag is not the right fit, for example a `Deferred` state that should count as Done or an `Awaiting Client` state that should count as In Progress, your state names can be mapped to categories for your whole organisation. A mapping overrides everything else, so it also covers a state you want moved out of the category above.

Contact <support@logilica.com> for help.

## Field & Type Configuration

Logilica reads these YouTrack fields by their exact name. If you've renamed any of them (for example `Status` instead of `State`), they won't be recognised:

| 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                             |

### Story points

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.

### Issue-type hierarchy

Logilica builds your work hierarchy from the issue type name:

| Issue Type Name                                   | Hierarchy Level |
| ------------------------------------------------- | --------------- |
| `Feature`, `Initiative`                           | Above Epic      |
| `Epic`                                            | Epic            |
| `Subtask`                                         | Below Task      |
| Anything else (`Bug`, `Task`, `Story`, and so on) | Task            |

Type names that include one of these words work too, so `Product Epic` and `Epic - Platform` both sit at Epic level. Capitalisation does not matter, and an issue with no type is treated as a Task.

If your types carry a hierarchy meaning Logilica cannot infer, such as `Theme`, `Capability`, or `Deliverable`, the level for each type name can be set for your organisation. Contact <support@logilica.com> for help.

### 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.

## 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. The window can be widened, so contact <support@logilica.com> for help if you need more history.
* **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.
* **Only state changes count as status changes.** Editing other fields, such as `Priority` or `Type`, does not affect how long an issue is reported as sitting in each status.
* **Use an uppercase project short name.** A short name that is lowercase or mixed case, such as `demo`, will not match the ticket IDs in your pull requests, so those issues show no linked code activity.
* **Avoid renaming a project's short name.** Issue IDs are built from it, so renaming it after onboarding breaks continuity with data already imported.