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, show you what the development team have done with it, and bring their comments back to the ticket.

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
Accept updates from Jira	Tick it if you want comments written in Jira to come back to the ticket — see Comments from Jira below

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 check

This step is easy to miss and everything looks fine without it. A scheduled task asks Jira what has changed — both the status of your issues and any new comments. Without it, every issue will show the status it had the moment it was raised, forever, and no comment will ever arrive.

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.

---

Comments from Jira

When a developer writes a comment on the issue, it arrives on the ticket as an internal note — so the question "what were the repro steps?" reaches you without anyone having to watch Jira.

Each note names the issue and the person who wrote it:

Jira · 14:32 KAN-6 · comment from Dave Smith Which build is this on? I can't reproduce it on 4.2.

Switch it on per connection with Accept updates from Jira (System → Integrations → Jira → edit the connection). It is off until you tick it.

Three things worth knowing:

• They are always internal. A developer writing in Jira does not know a customer might be reading. Comments are never shown to the requester — if one should be passed on, you do that yourself in your own words.
• Turning it on does not bring back old comments. The first check after you tick the box only marks the starting point. You will see comments written from then on, not a backlog dumped onto tickets that closed months ago.
• They arrive with the scheduled check, so allow a few minutes rather than expecting them instantly. Nothing needs to be exposed to the internet — FreeITSM asks Jira, Jira never has to reach you.

💡 Comments FreeITSM itself posted to Jira (via Send note to issue tracker) are recognised and never come back as notes, so the two systems cannot end up echoing each other.

---

What is not there yet

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

Instant updates	Not yet. Status and comments arrive on the scheduled check, so expect a few minutes' delay rather than the change appearing immediately.
Replying to a Jira comment from the ticket	Not yet — reading works, but there is no reply box on the note. A workflow rule can post a comment to the issue; answering a specific question still means opening Jira.
Being told automatically when the issue is finished	Not yet. The status on the pill changes, but you have to look — a rule like "when the issue is done, tell the requester" is not possible yet.
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 check" above.
Status updates but no comments arrive	Accept updates from Jira is not ticked on that connection. Remember the first check after ticking it imports nothing — write a fresh comment in Jira and wait for the next one.

---

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