Issue Trackers

Issue trackers (Jira and Azure DevOps)

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 the development team's tracker by hand and trying to remember to check back.

FreeITSM can raise an 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 Data Center / Server) and Azure DevOps (Services and Server). GitHub and GitLab are planned and will appear in the same place.

Everything on this page works the same for both. Where they genuinely differ — what the credential is called, and one extra setting Azure DevOps needs — it says so.

---

Setting it up

This is a one-off, done by an administrator. There is a step-by-step guide inside the product too: System → Integrations → your tracker → How to set up.

If you are using Azure DevOps

The steps are the same shape as Jira's below, with three differences:

• The credential is a personal access token, not an API token, and it is in Azure DevOps rather than the Azure portal. If you land on portal.azure.com you are in the wrong product. Go to dev.azure.com (or aex.dev.azure.com if that redirects you), then the user settings icon top-right → Personal access tokens → New Token. Under Scopes choose Custom defined and set Work Items to Read, write & manage — FreeITSM never touches your code.
• ⚠️ Note the expiry. Azure DevOps caps tokens at one year and often defaults to 90 days. When it lapses, escalation stops. This is the commonest reason a working connection stops working months later.
• The Organisation URL is the organisation, e.g. https://dev.azure.com/yourorg — not a project. On-premises, it is the collection address.

There is also one extra setting, because Azure DevOps has a state Jira does not — see Resolved, and what you want it to mean below.

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.

🔴 You must set up a scheduled task (Windows) or cron job (Linux) for any of this to work. It is not automatic and a fresh install has nothing scheduled. Without it:

• issue status is frozen at whatever it was when the issue was raised, forever, and
• no comment written in Jira will ever reach a ticket.

There is no warning and nothing in a log, because from the outside a tracker where nothing has happened looks exactly like one that is never asked.

👉 Scheduled tasks (cron jobs) has the exact commands for Windows and Linux, plus the other three jobs FreeITSM needs.

The job is cron/integration_poll.php and every 5 minutes is the usual choice. There is a per-job document in the application's docs/ folder too (integration-poll-cron-setup.md), but the wiki page above is the place to start.

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, or leave them blank to use your mapping.
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 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.

---

Mapping — set it once instead of typing it every time

By default, every escalation has to be told which Jira project to use and which issue type to raise. That gets tedious fast, and it is one more thing to get wrong in every rule you write.

System → Integrations → Jira → the arrows button on your connection opens Mapping, where you say it once.

Which project issues go in

Checked most specific first:

Rule	Beats
A department rule	everything below
A company rule	the default
Everything else	nothing — it is the fallback

So "the Development department's tickets go to DEV, everything else goes to KAN" is two rows. If nothing matches and nothing was typed on the escalation, FreeITSM refuses rather than guessing — an issue filed in an arbitrary project is worse than one not filed at all.

Ticket type becomes issue type

Same idea: "our Fault becomes their Bug, everything else becomes a Task."

💡 The issue types offered come from your default project. Other projects on the same site may offer different ones, so you can type any value rather than being held to the list.

Priority

Your priorities, translated to theirs — our High is their Highest.

Two deliberate differences from the sections above:

• There is no "everything else" option. Marking a development team's entire backlog urgent helps nobody, so an unmapped priority is simply not sent — it still appears as text in the description, as it always did.
• A priority Jira rejects will not lose your escalation. Jira defines priorities per project, so a project that renamed Highest to P1 will refuse ours. Rather than fail, FreeITSM raises the issue without a priority and notes why on the connection. Losing a priority is a cosmetic problem; losing the escalation is not.

After mapping, rules get simpler

Leave Project key and Issue type blank on an escalation rule (or on the manual Raise button) and the mapping decides. Anything you do type still wins, so rules you have already written carry on behaving exactly as before.

⚠️ Needs a Database Verification — mapping adds a table. The screen tells you if it is missing rather than quietly saving nothing.

---

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.

---

Resolved, and what you want it to mean

Azure DevOps only — Jira has no equivalent, so this setting does not appear there.

Azure DevOps has a state that sits between in progress and closed: Resolved, meaning a developer believes it is fixed but nobody has checked yet. Bugs use it; user stories do not.

FreeITSM cannot decide for you whether that counts as done, so the connection asks:

Choice	What happens
Treat it as still in progress (the default)	The person who raised the ticket hears nothing until somebody verifies the fix.
Treat it as done	They hear as soon as the developer marks it resolved. Right if your team closes on resolve.

The default is the cautious one on purpose: telling somebody their problem is fixed when it turns out not to be is the worse of the two mistakes.

You can change it at any time on the connection, and it takes effect on the next check.

---

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 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 the tracker.
Custom fields and components	Not yet. Project, issue type and priority can be mapped (see Mapping above); other fields cannot. Azure DevOps priority cannot be mapped at all — it is a number there rather than a named list, so there is nothing to choose from.
Issues raised in the tracker creating tickets	Not yet.
Clearing a field back to empty	Not possible on Azure DevOps — a value can be set or changed, but not emptied.

---

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 check is not running — by far the most common cause. See Scheduled tasks.
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: Scheduled tasks (cron jobs) · External issue trackers — Developer Guide · Jira connector — Developer Guide · Workflows