> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira ITM

*This article covers **Jira**, the ITSM integration for Jira Cloud and Jira Server. It syncs users and powers ticket logging and syncing for access requests. To manage Jira user accounts and group memberships, use Jira Provisioning (Jira Cloud) or Jira Server Provisioning (self-hosted Jira Server/Data Center) instead.*

## After this article

You can connect Jira to Lumos to sync users from your Jira tenant and to log and sync access-request tickets. ITSM logging works with Jira Service Management. If you don't have Jira Service Management, you can still enable it through the mail-handler workaround in Phase 3.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| :- | :- | :- | :- | :- |
| Users | Account | Yes | No | Users from your Jira tenant |

ITSM capabilities (configured under **Admin → Settings → ITSM** after connecting):

* Create a Jira ticket when access is requested in the AppStore (raised on behalf of the target user where possible, though if Jira disallows it or no Jira account is found, Lumos raises on behalf of the integrating user). By default the reporter is the integrating user. Set `creation_static_fields.set_target_user = true` in the ITSMConfig custom attributes to make the reporter the target user instead.
* Comment on the ticket when an access request task is assigned or completed, and resolve the ticket via your mapped transition when the request completes.
* Create or log tickets for Access Review removals and automated deprovisioning (audit trail), with bidirectional resolution syncing. The auto-generated deprovisioning ticket uses a fixed Lumos template (Target User, Requester, Permissions) and does not carry the original request's custom intake fields. It includes a back-link comment to the original provisioning ticket, and the Task Center surfaces the custom fields.
* Sync access request comments between the Lumos Slackbot and Jira (**Jira Cloud only**). Only regular comments sync. Internal Jira notes do not.
* Sync access request statuses with Jira ticket status (**Jira Cloud only**). Jira cannot move a Lumos request back to a previous status (Lumos requests only move forward). Statuses map 1:1, so a single Jira status cannot map to multiple Lumos request statuses.

Comment sync and status sync are supported only in Jira Cloud, **not** Jira Server/Data Center. Last-login activity tracking is not available for the Jira (ITSM) integration. Approving a Jira ticket on behalf of another user is not supported. The Jira approval API requires the authenticated user to be on the approval list, and only Connect Apps using OAuth 2LO can impersonate, which is a different integration type than the OAuth 3LO used here.

## Required plan and roles

* **Jira Service Management (standard path):** the standard Jira ITSM connection uses Jira Service Management, which requires a **Service** space-typed project. Business-space projects won't appear as selectable options in Lumos. If your organization hasn't purchased Jira Service Management, you can still enable ITSM logging through the mail-handler workaround in Phase 3.
* You must be logged in as a **Jira Admin** to connect Jira Cloud, and as a **Site Admin** to connect Jira Server (the Server personal access token must be generated by a Site Admin).
* If your organization uses Jira's team-managed (next-gen) projects, contact Lumos before proceeding with the connection.
* **Authentication:** Jira Cloud uses OAuth 2.0 (3LO) with rotating refresh tokens (reuse detection). Jira Server uses a personal access token (PAT). Adding new scopes to the app causes existing Cloud tokens to fail validation, so a reconnect is required after any scope change.
* OAuth scopes requested on Jira Cloud (all required):
  * `offline_access` to refresh OAuth tokens
  * List users from your Jira tenant: `read:user:jira`, `read:application-role:jira`, `read:avatar:jira`, `read:group:jira`
  * Set up ITSM logging: `read:servicedesk:jira-service-management`, `read:requesttype:jira-service-management`, `read:workflow-scheme:jira`, `read:issue-security-level:jira`, `read:project-role:jira`, `read:screen:jira`, `read:status:jira`, `read:project-category:jira`, `read:workflow:jira`, `read:issue-type:jira`, `read:project:jira`, `read:comment:jira`, `write:comment:jira`, `read:request:jira-service-management`, `write:issue:jira`, `write:request:jira-service-management`, `read:comment.property:jira`, `write:issue.property:jira`
  * Webhooks for comment and status sync: `read:webhook:jira`, `read:issue-details:jira`, `read:jql:jira`, `delete:webhook:jira`, `read:field:jira`, `write:webhook:jira`

## Read-only access vs provisioning

**Is read-only possible?** Yes, and it's the only mode this connector offers for Jira accounts. This connector does not does not create, update, or delete Jira accounts or group memberships.

**What read-only requires.** The same Jira Admin (Cloud) or Site Admin (Server) connection described above, then follow the steps below to connect.

**Watch out for.** The scope list above includes several `write:*` scopes (`write:comment:jira`, `write:issue:jira`, `write:request:jira-service-management`, `write:webhook:jira`), don't read these as account provisioning access, they only govern ITSM ticket actions like commenting, resolving, and webhook registration. To manage Jira user accounts and group memberships, connect the separate **Jira Provisioning** (Jira Cloud) or **Jira Server Provisioning** (self-hosted Jira Server/Data Center) integration instead, that is a distinct connection card from this one. Adding new OAuth scopes to this Cloud connection also invalidates existing tokens, so any scope change requires a reconnect.

## Instructions

**Phase 1: Prepare Jira**

*Jira Cloud:* no preparation needed. Authentication is OAuth, completed in Phase 2 while logged in as a Jira Admin.

*Jira Server:*

1. Log in to your Jira Server instance as a Site Admin.
2. Copy the base site URL (e.g. `https://jira.custom-domain.com`).
3. Click your profile picture (top right) → **Profile** → **Personal Access Tokens**.
4. Create a new token and copy it.

**Phase 2: Connect in Lumos**

1. Click the Jira card in your Lumos integrations (reconnect an existing card or add a new one).
2. Choose **Jira Cloud** or **Jira Server** in the dropdown.
3. Jira Cloud: enter only the **subdomain** of your Jira tenant URL. If the full URL is `cyberdyne.atlassian.net`, enter just `cyberdyne`. Click **Connect Jira** and accept the OAuth scopes.
4. Jira Server: paste the base site URL into the **Base URL** field and the token into the **Personal Access Token (PAT)** field, then connect.

**Phase 3: Configure ITSM logging (optional)**

ITSM behavior is configured under **Admin → Settings → ITSM** after connecting. Pick the path that matches your Jira setup.

*Jira Cloud (with Jira Service Management):*

1. Choose **Jira Cloud** in the dropdown and click **Connect**. If your Jira is behind a firewall, allowlist the Lumos outbound IP addresses so Lumos can reach your tenant (see Troubleshooting).
2. Choose the sync you want to configure.
3. Set the **Project**, **Request Type**, and **Resolve With** values. The **Project** maps to your Jira Service Desks, and you can't select a Project without valid Request Types. The **Request Type** must have a summary field and a description field, with **no other required fields**. For Custom Requests you'll see a **Resolve with** option. Choose the transition that maps most accurately to a closed ticket.
4. Enable the syncs you want (synced tickets, access-removal tickets, comment sync, status sync), then click **Save**.

*Jira Server (manual status mapping):* Jira Server maps statuses manually with Lumos Support rather than through the dropdown.

1. Log into Jira as an Administrator and open your workflows.
2. Select a project, then from the project sidebar select **Project settings → Workflows** and select **Text**.
3. Retrieve the Jira status value you want mapped to each Lumos request status: **Provisioned** (required), Awaiting Approval, Awaiting Provisioning, Canceled, Denied, and Expired. You can only map statuses 1:1 between Lumos and Jira. A single Jira workflow status cannot map to multiple Lumos request statuses. To reuse the same transition across multiple states, modify the workflow via **Diagram → Add Transition → Reuse a transition**.
4. Take a screenshot of your workflow with the status-value mappings and send it to [support@lumos.com](mailto:support@lumos.com) so Lumos can finish connecting the integration.

*No Jira Service Management (mail-handler workaround):* if your organization hasn't purchased Jira Service Management, you can still enable ITSM logging for tickets created from AppStore access requests.

Set up ticket creation and updates with a Jira mail handler:

1. In Jira, go to **Settings → System**.
2. Open the **Incoming Mail** section.
3. Click **Add incoming mail server** and configure a new mail server to your preferences (skip this if you already have a mail server and no handlers).
4. Click **Add incoming mail handler**. Give it a name, choose the mail server you just created, and choose the event **Create a new issue or add a comment to an existing issue** for the Mail Handler Type.
5. Choose the project in which issues will be created, then click **Add**.
6. Copy the email address from the Jira email server. In the Lumos ITSM settings page, choose the **Email Messaging** option, enter the email address, and click **Save**.

Set up auto-resolution with a Jira automation rule:

1. In Jira, go to your project settings page and open the **Automation** section.
2. Click **Create rule** and choose **Issue commented**. Leave Comment type as **All comments** and save.
3. Add **New condition → Issue fields condition**. Choose the **Summary** field and the **contains** condition, and enter `[Access Request]`. Save.
4. Add **Advanced compare condition**. First value `{{comment.body}}`, condition **equals**, second value `This ticket can be closed`. Save.
5. Add **New action**. Set the fields needed to close your ticket, at minimum the **Transition issue** action moving the ticket to your completed status.

Detailed configuration lives in the *Configuring Jira ITSM Logging*, *Configuring Jira ITSM Logging Without Jira Service Management*, *Enabling ITSM Comment and Status syncs for Jira*, and *Enabling Jira tickets for Access Review removals* articles.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**ITSM tickets aren't being created in Jira.** Confirm **Create Synced Tickets** is enabled in Lumos ITSM settings. Verify the correct Project and Request Type are selected. Check the Request Type in Jira has a summary field and a description field, with **no other required fields**. Confirm the requesting user has the **Customer** role in Jira Service Management. Review the Activity Log in Lumos for the specific error.

**Not all Jira transitions appear in the "Resolve with" dropdown.** For Custom Requests, "Resolve with" only lists transitions accessible directly from the ticket's initial state. Create a resolution transition reachable from that initial state (you may need to publish the workflow in Jira, then refresh in Lumos).

**Ticket status transitions fail and the ticket never leaves its initial status.** Jira returns HTTP 400 ("Can't move, missing required information") while comments still post, so it is not a permissions problem. Two known causes. (1) A Lumos stage in **Admin → Settings → ITSM → Define Transitions** is mapped to a Jira transition that no longer exists on the project workflow. Remap it to a valid transition or Not Set. (2) A required field or validator on the transition (commonly a required **Resolution** on the close transition) that the API call doesn't populate. Relax the validator or add a post-function to set the field automatically. Related: Lumos stores transition **IDs**, not names. If a transition is deleted, set the Lumos status to **Not Set**, save, then set it to the new transition.

**Lumos-posted Jira comments render as a raw JSON block.** A special character (tab, backslash, carriage return) in an interpolated value, typically the app's custom provisioning instructions, breaks comment rendering. Edit the app's provisioning instructions in AppStore settings and replace the special character with a normal space. Access requests still complete normally.

**Webhook registration fails with "A maximum of 5 webhooks is allowed per app per user".** Jira caps webhooks at 5 per app per user. Remove stale registrations for that user before reconnecting.

**Comment sync isn't working.** Comment sync relies on the Lumos webhook in Jira, so **Intercept ITSM Requests** must be enabled in your Lumos ITSM settings. Comment sync is Jira Cloud only. Reconnect to grant the required scopes if comments still don't sync, and ensure Jira accounts are matched to Lumos users.

**Jira is behind a firewall.** Allowlist the Lumos IP addresses `44.228.74.159` and `54.244.99.235`.