# Jira

Jira gives the agent your ticket system on the phone. A caller can ask "what is happening with SUP-1234?" and hear the current status, or report a problem and get a new issue filed while they are still on the line. **Integrations - Catalogue - Jira - Connect** opens **Connect Jira**. One connection is shared by the whole company, and every agent that has the Jira tool on uses it.

  <ShotPlaceholder
    src="/assets/integrations/jira.png"
    name="jira-connect"
    alt="Connect Jira dialog with Site URL, Account email and API token"
    capture="Integrations - Catalogue - Jira - Connect dialog."
  />

## What you need before you start

- A Jira Cloud site (the address you open Jira on, ending in `atlassian.net`).
- An Atlassian API token. In Atlassian go to **id.atlassian.com - Security - API tokens - Create API token** and copy the token straight away. Atlassian shows it only once.
- Preferably a dedicated service account to own the token. Every issue, comment and status change the agent makes is recorded under the token owner's name.

## What you enter

- **Site URL** (required) — Your Jira address, for example `https://yourcompany.atlassian.net`.
- **Account email** (required) — The email of the Atlassian account that owns the token.
- **API token** (required) — The token you just created.
- **Default project key** — The project new issues go to when the caller does not name one, for example `SUP`.
- **Default issue type** — The issue type for new issues. Jira's "Task" is used when you leave it blank.

## First setup

1. Create the API token in Atlassian and copy it.
2. **Integrations - Catalogue - Jira - Connect**. Fill in the site URL, account email and token, click **Test connection**, then **Connect**.
3. Open **My Agents - your agent - Skills - Tools & Workflows**. Turn the **Jira** tool on and open its settings.
4. Pick the operations. **Look up issue** and **Search issues** are ticked by default. Add **Create issue**, **Add comment** or **Transition issue** only if the agent should change tickets.
5. Optionally set a **Default project key** and **Default issue type** for this agent, and choose **Identify the caller by**: phone (automatic from caller ID), VAT number, email, a custom identifier the agent asks for, or no tagging. With phone, you can also turn on **Pre-load the caller's tickets on call start**.
6. **Save** the agent.
7. Prove it: call the agent, read out an existing issue key and ask for its status. Then open the issue in Jira to compare.

## What the agent can do

**Find tickets**
- Look up an issue by its key and read its status and summary.
- Search issues by free text across summaries, descriptions and comments.
- Read the latest comments on an issue.
- List the projects available, so it can pick the right one when the caller names a project.

**Change tickets** (only the operations you enabled)
- Create a new issue in the default or named project.
- Update an issue's summary, description or priority.
- Add a comment to an existing issue.
- Move an issue to another status, such as In Progress or Done.
- Assign or reassign an issue to a person by email or name.

**Know who is calling**
- Tag issues it creates with the caller's identifier (phone, VAT, email or custom), so the next call from the same person finds their tickets. Issues get a label starting with `vl-caller-`.

## Troubleshooting

**Test connection fails**

A 401 or 403 means the email and token do not match. Make sure the email is the account that created the token, and that the token was not revoked. If the error says Voice Logica could not reach Jira, check the site URL: it must be the full `https://...atlassian.net` address.

**The agent cannot create an issue**

Check that **Create issue** is ticked on the agent and that a project is known: either the caller names one, or a **Default project key** is set. The token owner also needs permission to create issues in that project.

**The agent says it cannot move the issue to the status the caller asked for**

Jira only allows the transitions your workflow defines from the issue's current status. When the requested status is not one of them, the agent gets the list of statuses it can move to and should offer those instead.

## Next Steps

[Get an integration working](https://docs.voicelogica.ai/integrations/) - the company connection, then the agent tool.  
[ClickUp](https://docs.voicelogica.ai/integrations/productivity/clickup/) - if your team tracks work in ClickUp instead.  
[Trello](https://docs.voicelogica.ai/integrations/productivity/trello/) - for board-and-card workflows.