> 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/jira.md).

# Jira

This guide covers how Logilica imports issues, epics, sprints, and history from Jira, and the field and issue-type configuration that ensures your planning data is recognised and categorised correctly. Logilica supports both Jira Cloud and Jira Server (Data Center) 8.x and above.

## Authentication

Logilica connects to Jira in one of two ways, depending on your hosting:

* **Jira Cloud** — OAuth, or an API token. With OAuth, Logilica reads only the data it needs and never gains write access, and your password is never stored.
* **Jira Server / Data Center** — basic authentication or a personal API token.

See [Connecting Tools](/integration/connecting-tools.md) for the general installation and authentication flow.

## What's Imported

For each Jira project you connect, Logilica imports:

* **Issues** — summary, description, type, status, priority, labels, components, resolution, due date, created/updated/resolved dates, and time tracking (original estimate, remaining estimate, time spent)
* **Epics and the full parent hierarchy** — including epics and higher-level issues that sit outside the connected project (these are fetched separately so the hierarchy stays complete)
* **Subtasks** and parent/child relationships, including the complete ancestor chain
* **Sprints** — name, state, start, end, and completion dates, plus goal
* **Releases** (fix versions and affected versions)
* **Issue history** — status changes, assignments, resolution, and sprint changes
* **Story point estimates**
* **Custom fields** — every custom field present on an issue is imported alongside the built-in fields
* **Assignees, reporters, creators, and resolvers** — user identity, name, and email
* **Labels** and **components**
* **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.
{% endhint %}

## Issue State Mapping

Logilica categorises every issue into **To Do**, **In Progress**, or **Done**. For Jira, this categorisation is driven by the issue's **Status Category** — the grouping Jira assigns to every status — not the status name itself.

Jira's three status categories map directly onto Logilica's categories:

| Jira Status Category | Logilica Category |
| -------------------- | ----------------- |
| `To Do`              | **To Do**         |
| `In Progress`        | **In Progress**   |
| `Done`               | **Done**          |

Because Logilica reads the status category rather than the status name, custom statuses are handled automatically — a status named `In Review`, `QA`, or `Deployed` is categorised correctly as long as it is assigned to the right status category in Jira.

{% hint style="info" %}
Every Jira status belongs to one of the three categories above, and Jira sets this when you create a status. If a custom status is categorised incorrectly in Logilica, check that the status is assigned to the correct status category in your Jira workflow settings (**Project settings > Statuses**).
{% endhint %}

## Field & Type Configuration

Logilica detects the following fields by their **exact, case-sensitive Jira field name**. These are Jira's standard field names, so no action is needed unless your instance has renamed them:

| Jira Field Name | Used For                                           |
| --------------- | -------------------------------------------------- |
| `Sprint`        | Sprint membership and sprint-change history        |
| `Story Points`  | Story point estimates                              |
| `Epic Link`     | Parent epic on classic (company-managed) projects  |
| `Parent Link`   | Parent linkage on Jira Premium (advanced roadmaps) |

{% hint style="warning" %}
These names are matched exactly. If your Jira administrator has renamed the `Sprint`, `Story Points`, `Epic Link`, or `Parent Link` field, the corresponding data will not be imported until the original name is restored. Variations such as `Story Point`, `Sprints`, or `SP` are not recognised.
{% endhint %}

### Parent and epic detection

Logilica links each issue to its parent using the issue's **parent** field (team-managed / next-gen projects), `Epic Link` (classic projects), or `Parent Link` (Jira Premium with advanced roadmaps enabled). On plans without advanced roadmaps, `Parent Link` carries no value and is ignored.

### Issue-type hierarchy

Logilica organises issues into a hierarchy using Jira's own issue-type levels:

* Issue types **above Epic** (such as Initiative) are treated as initiatives at the top of the hierarchy.
* **Epics** are grouped as epics.
* Standard types such as `Story`, `Task`, and `Bug` are treated as regular issues.
* **Subtasks** are treated as subtasks.

An issue type named `Epic` is always treated as an epic.

{% hint style="info" %}
If your team uses custom issue types **above** the Epic level (for example a custom `Theme` or `Outcome` type) and they are not being treated as initiatives automatically, contact your Logilica administrator. These can be added to the connector's configuration so they are recognised as higher-than-epic types — this is not something you can change from the connector page.
{% endhint %}

## 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.
* **Epics are always fully imported.** Even when a parent epic was last updated more than 6 months ago, or lives outside the connected project, Logilica fetches it so the issue hierarchy remains complete.
* **Field names are case-sensitive.** Status *categories* are matched by Jira's own category, so custom status names are safe, but the `Sprint`, `Story Points`, `Epic Link`, and `Parent Link` field names must match exactly.
* **Comments, attachments, and individual work-log entries are not imported.** Aggregated time tracking (original estimate, remaining estimate, time spent) is imported, but individual time-log entries and comments are not.