Issue Trackers

Issue trackers (Jira)

Some tickets are not really support tickets. A user reports that the invoice screen crashes, and no amount of service desk work will fix it — a developer has to. Until now that meant copying the details into Jira by hand and trying to remember to check back.

FreeITSM can now raise a Jira issue straight from a ticket, keep the link, and show you what the development team have done with it.

Works with Jira Cloud and Jira Data Center / Server. GitHub, GitLab and Azure DevOps are planned and will appear in the same place.

---

Setting it up

You need a Jira account and an API token. This is a one-off, done by an administrator.

1. Get an API token from Atlassian

The token is not in Jira itself — it is in your Atlassian account, at id.atlassian.com → Security → API tokens. Create one, give it a name you will recognise later (FreeITSM), and copy it. It is shown only once.

2. Add the connection

Go to System → Integrations → Jira → Add.

Field	What to enter
Name	Anything you will recognise — "Our Jira"
Jira site URL	https://yourcompany.atlassian.net
Email address	The email address your Atlassian account uses. Leave blank for Jira Data Center, which uses a token on its own
API token	The token from step 1
Company	See below
Active	Leave ticked

Press Test before saving. It will tell you which account it connected as, or exactly what Jira objected to.

💡 Editing a connection later? Leave the token box blank to keep the one already saved. FreeITSM never shows you a stored token, so an empty box means "no change", not "clear it".

3. Schedule the status check

This step is easy to miss and everything looks fine without it. A scheduled task asks Jira what has changed. Without it, every issue will show the status it had the moment it was raised, forever.

Your administrator will find the instructions in docs/integration-poll-cron-setup.md. Recommended: every 5 minutes.

If you support more than one company

Each connection is either:

• All companies — your own development team's Jira, used for everyone's tickets. This is the usual choice.
• One company — a client who has their own Jira and wants their issues in it.

A ticket can only ever be escalated to a tracker its own company is allowed to use. If you support Acme and Globex, an Acme ticket cannot reach Globex's Jira, however the rule is written.

---

Raising an issue from a ticket

1. Open the ticket.
2. In the Links strip, choose Link to… → Issue tracker.
3. Pick the tracker, enter the project key (the short code at the start of every Jira issue — the KAN in KAN-6) and the issue type.
4. Read the preview. This is exactly what the development team will see.
5. Press Raise.

The issue is created in Jira and a pill appears on the ticket.

⚠️ Internal notes are never sent. The description is built from the requester's original message and the ticket's details only. Nothing you have written in a private note can reach Jira.

⚠️ You cannot unsend it. A Jira issue is visible to everyone with access to that project, and FreeITSM cannot withdraw it. That is why there is a preview — read it before pressing Raise.

Which issue type?

Whatever your Jira project actually offers. Many projects have Task, Epic, Incident and Service Request but no Bug, despite Bug being the obvious choice. If you are unsure, click Create in Jira and look at the type dropdown. Entering a type the project does not have will fail with a message saying so.

---

What you see on the ticket

The linked issue appears as a pill in the Links strip, alongside any linked problems, changes and tickets:

◐ KAN-6 · In Progress · Sam Patel

• The key is the issue in Jira — click to open it.
• The status and assignee are whatever Jira last reported.
• The symbol shows roughly where it is: ○ not started, ◐ in progress, ● done, ⊘ cancelled.

The status updates on its own as the development team work, as long as the scheduled check is running.

Opening a ticket never waits for Jira. If Jira is slow or offline the ticket still opens instantly — the status shown is simply the last one we fetched.

---

Escalating automatically

You do not have to do it by hand. Because escalation is a Workflows action, you can make it a rule:

When a ticket's type is changed to Bug → raise it in Jira.

Go to Workflows, create a rule, pick your trigger and conditions, and add the action Escalate to issue tracker. You can use ticket details in the summary and description, exactly as in any other workflow action.

Two things worth knowing:

• Skip if this ticket already has an issue is on by default, and should stay on. A trigger like "status changed" can fire many times on one ticket, and without it your development team would get a pile of duplicates.
• Test fire and dry run are safe. A dry run describes what it would raise without creating anything in Jira.

There is also Send note to issue tracker, which posts a comment onto the issue a ticket is already linked to. If the ticket has no linked issue, it does nothing rather than failing.

---

What is not there yet

Being straight about the gaps, because some of them matter:

Comments coming back from Jira	Not yet. If a developer asks a question on the issue, you will not see it in FreeITSM — check Jira. This is the biggest gap and the next thing being built.
Instant updates	Not yet. Status arrives on the scheduled check, so expect a few minutes' delay rather than the change appearing immediately.
Attachments	Not yet. Screenshots stay on the ticket; mention them in the description.
Priority mapping	Deliberate. Your ticket's priority appears as text in the description rather than being set as Jira's priority field, because Jira priorities differ per project and guessing wrong fails the whole thing. Choosing the mapping yourself is planned.
Issues raised in Jira creating tickets	Not yet.

---

If something goes wrong

FreeITSM passes Jira's own error message through, so it is usually specific.

Message	What it means
"Jira rejected the credentials"	Wrong email or the token has been revoked. Create a new token and re-test.
"…is required" naming a field	That Jira project demands a field we did not send — often an Epic Link. Ask your Jira administrator to make it optional, or use a project that does not require it.
"The target project doesn't exist or you don't have permission"	Wrong project key, or the account behind the token cannot see that project.
"That tracker belongs to a different company than this ticket"	The tracker is reserved for one client and this ticket belongs to another. This is deliberate and cannot be overridden.
Nothing ever changes status	The scheduled check is not running. See "Schedule the status check" above.

---

See also: External issue trackers — Developer Guide · Jira connector — Developer Guide · Workflows