Skip to main content
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

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 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

​
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.