> 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
## 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 → Integrations → 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 → Integrations → 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 → Integrations → 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 → Integrations → 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 (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. 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 → Integrations → 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 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. **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 → Integrations → 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.