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. Off by default — see Comments from Jira below, which also explains where to find it again later

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.

FreeITSM does not sit waiting for Jira to call — it asks. Every few minutes a small task wakes up and puts one question to Jira: what has changed? Anything that comes back from Jira — a status moving to In Progress, a new comment from a developer — arrives because that task ran. We call it the check.

⚠️ Nothing you set up on this page does anything until the check is running. Issues will sit forever showing the status they had the moment they were raised, and no comment will ever appear. There is no warning, because from the outside a tracker where nothing has happened looks exactly like one that is not being asked.

Your administrator sets it to run automatically — the instructions are in docs/integration-poll-cron-setup.md. Every 5 minutes is the usual choice.

Running the check once, by hand

Useful when you are testing, or before the schedule has been set up. Either:

• From the server's command line, in the FreeITSM folder:

  php cron/integration_poll.php
  

• Or by opening its web address, if your administrator has set the token:

  https://your-install/cron/integration_poll.php?token=…
  

It prints what it did — one line per tracker, plus any status changes and comments it brought back:

Jira                         checked   1, changed  0
    comments: 1 seen, 1 imported

💡 It will not run twice in quick succession — each connection has its own interval (5 minutes by default) and the check skips any tracker asked recently, reporting "No connections due". That is not a fault; wait and run it again.

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.

Switching it on

It is off until you tick it, on each connection separately. The tickbox lives inside the connection itself, not on the list page — so you have to open the connection to reach it:

1. System → Integrations → Jira
2. Find your connection in the list and press the pencil (Edit) button on its row
3. Scroll to the bottom of the panel that opens — Accept updates from Jira is the second tickbox, directly under Active
4. Tick it and press Save

💡 Leave the API token box empty. FreeITSM never shows you a stored token, so a blank box means "keep the one already saved". You do not need to re-enter it to change this setting.

Once it is on, the connection's row shows an Updates on badge next to Active, so you can see at a glance which trackers are sending comments back without opening each one.

⚠️ Write your first test comment after the first check, not before

This catches people out, and it is deliberate rather than a fault.

Ticking the box does not reach back into Jira's history — the first check after you save simply marks the starting point. A comment written before that moment will never appear, because as far as FreeITSM is concerned it happened before it was asked to listen.

So to test it:

1. Tick the box and save
2. Let one check run — wait for the schedule, or run it once by hand. This is the one that marks the starting point; it will report no comments, and that is correct
3. Now write a comment on the issue in Jira
4. Let the next check run
5. Open the linked ticket — the note is there

If you comment at step 1 and nothing ever arrives, this is why. Write a fresh comment and wait for another check.

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 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. This works by remembering exactly which comments it posted — not by looking at who wrote them, so comments you write yourself come back normally even if the connection uses your own Jira account.

---

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 — its row will show an Updates on badge when it is. See "Switching it on" above for where the tickbox lives.
Ticked it, but the comment I wrote still has not appeared	Almost certainly the ordering. The first check after ticking only marks the starting point, so a comment written before it is ignored for good. Write a fresh comment and wait for the next check.
I cannot find the tickbox	It is inside the connection, not on the list page. Press the pencil on the connection's row; it is under Active, at the bottom of the panel.

---

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