> For the complete documentation index, see [llms.txt](https://docs.siit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.siit.io/integrations/ticketing/jira.md).

# Jira

Connect Jira to Siit to escalate requests into Jira issues with one click, keep statuses in sync between both tools, and automate Jira issue creation from any workflow or AI Agent playbook.

<figure><img src="https://451675063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz9xmM8V3atukfr2XaElR%2Fuploads%2FiKONUN4hiHzu72ua6VZ7%2FSiit_Jira.jpg?alt=media&amp;token=be8680a8-fe6c-4310-9c8b-2f5021c21d25" alt=""><figcaption></figcaption></figure>

## Jira

#### What you get

* **One-click escalation from any request.** Click **Escalate ticket** in the request side panel, pick a Jira project and issue type, and a linked issue is created with the Siit context pre-filled.
* **Configurable two-way sync.** Choose exactly what cascades between a Siit request and its linked Jira issue: resolution, assignee, notes, and messages, each opt-in per direction.
* **Escalation defaults per board.** Set the default request type, status, and assignee behavior Siit applies when escalating, and let agents override them at escalation time.
* **Workflow-driven issue creation.** Use **Create Jira issue** as a workflow step, with field mapping and approval gating where needed.
* **IT Agent native support.** `/jira create issue` is available inside IT Agent playbooks, with optional approval.
* **Custom field mapping.** Map Siit form fields and request attributes to your Jira custom fields, so escalated tickets land with the right context every time.
* **Audit trail.** Every Jira action triggered from Siit is recorded on the request timeline.

#### How it works

When a Siit request needs engineering or specialist work, you escalate it to Jira:

1. From the request side panel, click **Escalate ticket** and pick **Jira**.
2. Choose the project, issue type, and any required fields. Escalation defaults and custom fields configured in **Settings → Workspace → Integration library → Jira** pre-fill automatically, and you can adjust them before creating the issue.
3. Submit. Siit creates the Jira issue, links it back to the Siit request, and posts the link on both sides.
4. From there, updates flow between the two according to your sync configuration (see below).

The same flow is available in workflows (as a **Create Jira issue** action) and in IT Agent playbooks.

#### Sync configuration

Sync is set at the integration level and is fully bi-directional. In **Settings → Workspace → Integration library → Jira → Settings**, you get one table per direction. Each row is an event, and you choose how Siit reacts to it.

**From Siit to Jira** controls what happens on the Jira issue when the linked Siit request changes:

* **When marked as resolved** — resolve the Jira issue, or do nothing.
* **When assignee changes** — match the assignee on Jira where possible, or do nothing.
* **When a note is added** — push it to Jira, or do nothing.
* **When a new message is posted** — push it to Jira, or do nothing.

**From Jira to Siit** controls what flows back to the Siit request when the Jira issue changes:

* **When marked as resolved** — resolve the Siit request, or do nothing.
* **When assignee changes** — match the assignee on Siit, or do nothing.
* **When a note is added** — import it into the request, or do nothing.
* **When a new message is posted** — import it into the request, or do nothing.

Each option is opt-in, so nothing cascades unless you turn it on. Defaults are capability-aware: Siit only exposes the behaviors Jira can actually honor, which means you never configure something the tool cannot do.

#### Escalation defaults

Escalation defaults are the values Siit pre-fills when escalating a request to a given Jira board. Agents can override them at escalation time. Configure them per project under **Settings → Workspace → Integration library → Jira**:

* **Request type** — the default issue type created on escalation.
* **Status** — the default status. Available statuses depend on the selected request type.
* **Match assignee** — when enabled, Siit maps the Siit assignee to the Jira assignee where a match exists.

#### Custom field mapping

Map Siit data to Jira custom fields so escalated issues arrive with the right metadata: request ID, requester, service, priority, anything you need. Set this up in **Settings → Workspace → Integration library → Jira → Custom mapping**. For the full setup guide, see [Custom field mapping](https://help.siit.io/custom-field-mapping).

Field options now include fields on the board's edit screen, not just the create screen. When Jira rejects a specific field on write, Siit still submits the fields the board accepts instead of failing the whole escalation.

#### Before you connect

* A Jira admin account whose login email and an API token (generated at `id.atlassian.com`) will be used for the connection.
* A clear idea of which Jira project(s) you want to escalate to. Start with one, then expand.
* Optional: a dedicated "Siit Integration" Jira user, so the integration survives admin turnover.

#### Connect Jira

1. In Siit, go to **Settings → Workspace → Integration library**, find **Jira** in the Ticketing section, and click **Connect**.
2. In the connection window, enter your Jira site URL (e.g., `yourcompany.atlassian.net`), the login email of the admin account, and an API token generated at `id.atlassian.com`.
3. Pick the Jira project(s) you want available for escalation.
4. Set escalation defaults, sync configuration, and field mapping.
5. Test by escalating a sample request from Siit to Jira.

For the detailed walkthrough, see our Help Center guide: [Jira integration setup](https://help.siit.io/jira-integration).

#### After the connection

* **Try the side panel.** From any request, click **Escalate ticket → Jira** and create a test issue.
* **Set your sync rules.** In **Settings → Workspace → Integration library → Jira → Settings**, decide what cascades in each direction (resolution, assignee, notes, messages).
* **Set escalation defaults.** Pick the default request type, status, and assignee behavior for each board.
* **Configure field mapping.** Map your Siit fields to the Jira custom fields you care about.
* **Build your first workflow.** A common starter: "when service = 'Bug report', auto-create a Jira issue in the ENG project and notify the requester."

#### Common workflows

**Bug report auto-escalation.** *Trigger: Service = "App bug report". Actions: Create Jira issue in ENG project → Set Siit status to Waiting → Notify requester with the Jira link.*

**Approval-gated engineering request.** *Trigger: Service = "New integration". Actions: Manager approval → Create Jira issue in PLATFORM project → DM requester with the Jira link.*

**Auto-resolve on Jira completion.** *Trigger: Linked Jira issue resolved. Actions: Set Siit request to Resolved → Notify requester.* (Enable "When marked as resolved → Resolve" on the From Jira to Siit direction.)

#### IT Agent integration

Inside an IT Agent playbook, use `/jira create issue` to let the agent escalate autonomously, with approval gating on the action when you want a human in the loop.

A common playbook: an employee reports a broken integration in Slack → IT Agent gathers context → requests manager approval → creates a Jira issue → posts the link back to the employee.

See IT Agent for playbook examples.

#### Tips

* **Use a dedicated service account** for the Jira connection so it survives individual admin turnover.
* **Start with one project.** Mapping fields, defaults, and sync rules for one well-used project first is faster and lower-risk than connecting everything at once.
* **Keep Siit as the employee surface.** Employees shouldn't need a Jira account to track their request. The Siit request stays their canonical view; the linked Jira issue is internal.
* **Turn on only the sync you need.** Since every cascade is opt-in, enable the events your team relies on and leave the rest off to avoid noise.

#### Help Center guides

* [Jira integration setup](https://help.siit.io/jira-integration) — step-by-step setup with screenshots
* [Two-way sync configuration](https://help.siit.io/jira-sync-configuration) — how each sync event behaves
* [Jira guide](https://help.siit.io/jira-guide) — day-to-day usage and best practices
* [Custom field mapping](https://help.siit.io/custom-field-mapping) — map Siit data to Jira custom fields

#### Troubleshooting

**"Authorization failed" on connect.** The API token is wrong or revoked, or the email does not match the account that generated it. Generate a fresh token at `id.atlassian.com` and retry with a site admin account.

**Project missing from the destination picker.** The Siit Jira user lacks Browse Projects permission for that project. Update permissions in Jira and re-sync.

**A board shows as unreachable.** The Jira board was deleted or archived. Siit flags it as unreachable in the collections list so escalations don't fail silently. Remove it or point the escalation at a live board.

**Custom field not appearing in mapping.** The field may be tied to a specific issue type or screen scheme. Confirm the field is on the issue type's create or edit screen, then re-run the mapping step.

**A sync event isn't cascading.** Check the sync table in **Settings → Workspace → Integration library → Jira → Settings**. If the event is set to "Do nothing" in that direction, it won't cascade. Note that some behaviors are unavailable on Jira by design and won't appear as options.

**"Issue created" but no link in Siit.** The Jira issue was created but the back-link save failed. Open the request timeline: the Jira issue key is logged. Manually re-link if needed, then check Siit's connection token validity.


---

# 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.siit.io/integrations/ticketing/jira.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.