# Jira

<figure><img src="/files/dB3DxBwR4WhVIZYDDjS2" alt=""><figcaption></figcaption></figure>

### 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.
* **Bi-directional status sync.** Status changes on the Jira issue update the Siit request's external status field automatically — and the link stays visible on both sides.
* **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. Custom fields configured in **Settings → Integrations → Jira** appear automatically.
3. Submit. Siit creates the Jira issue, links it back to the Siit request, and posts the link on both sides.
4. As the Jira issue progresses, status updates flow back to Siit. You can use these as workflow conditions — for example, "when the linked Jira issue is Done, set the Siit request to Resolved."

The same flow is available in workflows (as a **Create Jira issue** action) and in IT Agent playbooks (via the `/jira create issue` slash command).

### What syncs from Jira

* **Issues created from Siit** — every escalated ticket is tracked with its Jira key, project, type, and current status.
* **Status changes** — Jira status transitions update the Siit request's external ticket status.
* **Links** — bidirectional links between the Siit request and the Jira issue, visible on both sides.

For the full list of fields Siit reads from and writes to Jira, see [Jira fields consumed](https://help.siit.io/jira-fields-consumed) in the Help Center.

### 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 → Integrations → Jira → Field mapping**. For the full setup guide, see [Custom field mapping](https://help.siit.io/custom-field-mapping).

### Before you connect

* A Jira admin (or Jira site admin) to authorize 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 → Integrations**, find **Jira** in the Ticketing section, and click **Connect**.
2. Sign in to your Jira site as an admin and approve the requested scopes.
3. Pick the Jira project(s) you want available for escalation.
4. Configure default issue type, priority, 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 up status sync rules.** In **Settings → Integrations → Jira**, map Jira statuses to Siit's external ticket statuses (e.g., Jira "Done" → Siit "Resolved").
* **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 status = Done. Actions: Set Siit request to Resolved → Notify requester.*

### 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.** It's tempting to connect every Jira project — but mapping fields and statuses for one well-used project first is faster and lower-risk.
* **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.
* **Use status sync to close the loop.** Mapping Jira "Done" to Siit "Resolved" keeps requesters informed without anyone manually updating the Siit ticket.

### Help Center guides

* [Jira integration setup](https://help.siit.io/jira-integration) — step-by-step setup with screenshots
* [Jira guide](https://help.siit.io/jira-guide) — day-to-day usage and best practices
* [Jira fields consumed](https://help.siit.io/jira-fields-consumed) — full field reference
* [Custom field mapping](https://help.siit.io/custom-field-mapping) — map Siit data to Jira custom fields

### Troubleshooting

**"Authorization failed" on connect.** The admin signing in lacks Jira admin rights, or the Jira site has restricted third-party app installs. Try with a site admin.

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

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

**Status sync isn't updating Siit.** Check the status mapping in **Settings → Integrations → Jira → Status sync**. If a Jira status isn't mapped, transitions through it won't update Siit.

**"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: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.siit.io/integrations/ticketing/jira.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.