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

# Adding Lumos Access Request Agent to Jira Service Management

## Background

The Lumos Agent appears in your Jira Service Management assignee dropdown like any other agent, through the Lumos app on the [Atlassian Marketplace](https://marketplace.atlassian.com/204087541). Assign an access request ticket to it, and Lumos reads the ticket, builds the matching access request, and runs it through your approval and provisioning workflows. Lumos writes status back to the ticket until the request reaches a terminal state. Your team stays in Jira, and no one has to re-enter the request in Lumos.

This article covers what the agent does, what must be in place before it works, and how service desk agents work with it. Setup requires the Jira integration and the Organization Admin role in Lumos. For the integration, see [Connecting Jira (ITSM)](/integrations/library/jira/jira).

## When to use the agent

* **Ticket-first intake.** Your employees file a Jira ticket for everything. Pointing them to the AppStore breaks that habit; assigning the ticket to Lumos does not.
* **Audit trail in Jira.** The access request carries the ticket ID and URL, and the ticket carries the request ID. Either system leads an auditor to the other.
* **Triage volume.** Your service desk handles a steady stream of access requests. The agent handles the complete ones end to end and comments on the ones it can't act on.

## Prerequisites

All of the following must be true before the Forge app installs. Lumos refuses the install instead of binding to a site where it can't resolve people.

* The Jira integration is connected in your Lumos tenant and approved by an Organization Admin of your Atlassian site. This ties the Jira site to your Lumos tenant.
* The user sync has run, so your Atlassian accounts appear in Lumos and are linked to Lumos users.
* You have one Jira site per Lumos tenant. When two sites share a tenant, two-way ticket sync is unreliable for the second site.
* The person installing the app has a linked Atlassian account and the Organization Admin role in that Lumos tenant.

## Set up the Lumos Agent

### In Lumos

1. Go to **Settings → Integrations → Discover** and connect **Jira (ITSM)**.
2. Add the connection information and approve the OAuth grant as an Organization Admin of your Atlassian site.
3. After setup, confirm that accounts sync. Go to **Apps → Jira (ITSM) → Accounts**. Users show as matched, without the yellow **Unmatched** label.

### In Jira

1. Install the Lumos Access Request Agent from the [Atlassian Marketplace](https://marketplace.atlassian.com/204087541).
2. Open a service desk project and confirm that **"Lumos Agent"** appears in the assignee dropdown.
3. Create a test ticket with access request details, assign it to **"Lumos Access Request Agent"**, and confirm that Lumos comments on the ticket.

## How the agent handles a ticket

1. A service desk agent triages the ticket and sets the assignee to **"Lumos Access Request Agent"**.
2. Lumos reads the ticket's reporter, summary, and description, and resolves them against your Lumos identities and your AppStore catalog.
3. Lumos submits the access request and comments on the ticket with a link to it.
4. The request runs through the approval and provisioning workflows configured for that app and permission.
5. Lumos writes each status change back to the ticket, then closes the ticket when the request reaches a terminal state.

## What Lumos records on every request

| Field | Source |
| - | - |
| Origin, agent, agent version | Set by Lumos on the request |
| Jira project | Ticket |
| Jira issue ID and URL | Ticket |
| Issue title and description | Ticket |
| Originating actor | Ticket reporter |
| Assigning service desk agent | The Jira user who set the assignee |

### Terminal states

| State | What it means |
| - | - |
| Completed | Access was granted |
| Denied | The request did not clear approvals |
| Cancelled | Someone cancelled the request before completion |
| Expired | No approver or admin acted within 14 days |

## Error handling

When Lumos can't act on a ticket, it says so on the ticket instead of guessing.

| Situation | What happens |
| - | - |
| Jira site not connected to any Lumos tenant | Lumos refuses the install |
| Installer's Atlassian account not linked to a Lumos user | Lumos refuses the install |
| Installer linked but not an Organization Admin | Lumos refuses the install |
| Reporter's Atlassian account not linked | Lumos declines the ticket and asks an admin to link the account |
| Reporter matches more than one Lumos user | Lumos declines the ticket and asks an admin to resolve the duplicate accounts |
| Jira integration credentials have lapsed | Lumos declines the ticket and asks an admin to reconnect Jira |
| App or permission missing from the catalog, inactive, or ineligible | Lumos comments with the conflict and a proposed alternative where one exists |
| Duration or business justification missing and not inferable | Lumos comments naming exactly what it needs |
| Target user already holds the access | Lumos comments and does not submit a request |

Fix the underlying issue, then assign the ticket to **"Lumos Access Request Agent"** again. The agent runs again against the updated ticket.

## Frequently asked questions

**Do requesters need Lumos accounts?**

Yes. Anyone who is the reporter on a ticket needs a linked Lumos user. For most customers this happens automatically, because people arrive in Lumos from your HRIS or IdP.

**Can we use the agent on more than one Jira site?**

Connect each Jira site to its own Lumos tenant. When two sites share one tenant, two-way ticket sync is unreliable for the second site.

**Does this replace the existing Jira access request sync?**

No. Two-way status sync between Lumos access requests and Jira tickets works as configured. The agent adds a way to create the request from the ticket.