External Issue Trackers Developer Guide

External Issue Trackers — Developer Guide

How a FreeITSM ticket gets linked to an issue in someone else's tracker, and why the machinery underneath is deliberately not about Jira. Shipped as #945–#957. Proven against a real Jira Cloud site on 2026-08-02 — including, in #956, a design fault that only a live account could have exposed.

Jira is the first connector and the only one currently written, but almost nothing here is about Jira. This page is the contract; everything Jira-specific lives on Jira Connector — Developer Guide, which doubles as the worked example for anyone adding GitHub, GitLab or Azure DevOps.

The analyst-facing page is Issue trackers (Jira).

⚠️ Status: it is two-way for comments, one-way for everything else. You can configure a tracker, escalate a ticket by hand or by workflow rule, see the issue on the ticket, and — since #954 — read the comments people write in Jira as internal notes. What still does not exist is webhooks (so everything arrives on the poll's schedule, not instantly) and the tracker.* triggers that would let a workflow react to an inbound event. Everything inbound depends on the poll cron: unscheduled, nothing ever changes. §9 has the full picture.

1. 📁 The files involved

Colour key: 🧠 shared rule · 🔌 provider · 🗄️ schema · 🧪 tests · 📄 docs

🎨	File	What it does
🧠	`includes/integrations/IssueDoc.php`	One description or comment, built once, rendered four ways (§4)
🧠	`includes/integrations/IssueTrackerProvider.php`	The abstract contract every tracker implements (§3)
🧠	`includes/integrations/integrations.php`	The service: the provider registry, load a connection, escalate, refresh status, pull comments back — and the company guard (§6, §7, §7d)
🔌	`includes/integrations/JiraProvider.php`	The first concrete connector — see its own page
⚙️	`workflow/includes/engine.php`	The two actions, the connection lookup and `argBool()` (§7a)
⚙️	`cron/integration_poll.php`, `docs/integration-poll-cron-setup.md`	The poll — the only thing that refreshes status or brings comments back (§7, §7d). Analyst-facing setup: Scheduled tasks
⌨️	`system/integrations/index.php`, `provider.php`, `.htaccess`	The settings screen and its pretty URLs (§7b)
🔌	`api/integrations/list_connections.php`, `save_connection.php`, `test_connection.php`, `delete_connection.php`	Connection CRUD, admin-gated
⌨️	`system/includes/areas.php`	The System landing card + its icon
⌨️	`assets/js/inbox.js`, `tickets/index.php`, `assets/css/inbox.css`	The pill in the Links strip and the escalate modal (§7c) — bump `inbox.js?v=`
🔌	`api/tickets/get_email_detail.php`	Adds `tracker_links` to the ticket payload
🔌	`api/tickets/get_notes.php`	LEFT JOIN on analysts + attribution for imported notes (§7d)
🔌	`api/integrations/escalate_ticket.php`, `connections_for_ticket.php`	The manual escalate + its company-filtered connection list
🔌	`api/integrations/tracker_options.php`, `get_mapping.php`, `save_mapping.php`	The mapping screen’s data: what the tracker offers, and what we map to it (§7e)
🌍	`lang/en/tickets.php`, `lang/pt-BR/tickets.php`	`tickets.tracker.*`
🗄️	`database/freeitsm.sql`, `includes/db_verify_schema.php`, `includes/db_verify_indexes.php`	`integration_connections`, `integration_links`, `integration_comment_map`, `integration_field_maps`, their keys and indexes
🌍	`lang/en/system.php`, `lang/pt-BR/system.php`	`system.integrations.*`, EN and pt-BR in the same commit
🧪	`tests/integrations/run.php`	252 assertions, none needing a live tracker (§8)
📄	`CHANGELOG.local.md`, this wiki	logged as #945–#957

Note what is not there: no change to the tickets module at all. That is a consequence of escalation being a workflow action (§2), not an accident.

2. The shape

Three layers. The middle one is new; the outer two already existed.

    WORKFLOW ENGINE  (exists — workflow/includes/engine.php)
    triggers · conditions · action registry · vars · dry run · step log
                        │  escalate_to_tracker · send_note_to_tracker  ✔ built
                        │  ▲ tracker.* triggers (V2, not built yet)
    ┌───────────────────┴──────────────────────────────────────┐
    │  INTEGRATION ENGINE  (this page)                         │
    │  link registry · IssueDoc · status categories ·          │
    │  company guard · escalate service · status refresh       │
    └───────────────────────┬──────────────────────────────────┘
                            │  IssueTrackerProvider (abstract)
        ┌───────────────────┼──────────────────┬────────────────┐
    JiraProvider      GitHubProvider     GitLabProvider   DevOpsProvider
      (built)            (later)             (later)          (later)

The bottom split is deliberately the same one as includes/messaging/MessagingProvider.php, which already puts Twilio and Meta Cloud behind a single contract while ingestion, ticket creation and the reply path stay ignorant of which is live. That pattern is proven in this codebase, so it was copied rather than reinvented.

The top connection is the important design decision. Escalation is a workflow action, not code in the tickets module — because Workflows already has triggers, conditions, {{ticket.subject}} substitution, dry run and an audit trail. "When a ticket becomes type Bug, raise it in Jira" is therefore a rule a user writes, not a feature we build.

The bet paid off exactly as intended: shipping escalation added not one line to the tickets module. Two entries in the action registry, two handlers, one lookup source.

3. The contract — what is generic, what is yours

This is the table to read before writing a connector. Generic means the engine relies on it and you must comply. Provider-specific means it is only how one tracker happens to work, and copying Jira's shape into a different tracker would be a mistake.

Concept	Generic (the contract)	Provider-specific (illustrative)
Issue identity	every tracker has a stable id, and usually a human key	Jira's id is numeric, its key is `OPS-412` and changes on project rename
Status	must map onto four categories: `todo` / `in_progress` / `done` / `cancelled`	Jira exposes `statusCategory.key` with three values and no cancelled
Body	build an `IssueDoc`, never a string	Jira Cloud wants ADF; Data Center wants wiki markup
Auth	credentials are a JSON blob, encrypted at rest	Jira Cloud is Basic `email:token`; Data Center is a Bearer PAT
Identity of us	`testConnection()` must return `account_identity`	Cloud gives `accountId`, Data Center gives a username
Target	opaque array passed to `createIssue()`	Jira needs project + issue type; GitHub needs only a repo
Optional features	declare via `supports()`; unsupported methods throw	Jira supports everything, GitHub has no issue types at all

What you must implement

Four abstract methods, because every tracker genuinely has them:

abstract public function createIssue(array $target, string $summary, IssueDoc $body, array $fields = []): array;
abstract public function fetchIssue(string $externalId): array;
abstract public function testConnection(): array;
abstract public function renderDoc(IssueDoc $doc);

Everything else — addComment(), addAttachment(), verifyWebhook(), pollChanges(), listProjects(), listIssueTypes() — has a default that throws "not supported for this provider". That is copied from MessagingProvider and it matters: if optional methods were abstract, the contract would collapse to whatever the weakest tracker can do.

supports() answers the same question for the UI, which needs to know before it renders a field. A thrown exception is the wrong way for a settings screen to discover that GitHub has no issue types.

`fetchIssues()` — the batch escape hatch

The default loops fetchIssue(), which is always correct. Providers that can read many issues in one call should override it, because the status-refresh cron is the hot path. One issue failing must not lose the rest.

`pollChanges(?string $since, array $externalIds = [])` takes a watch list

Polling is scoped to the issues we actually hold links to, not to "everything that changed" — an unscoped poll on a busy tracker returns thousands of issues nobody here cares about. V4, where an issue raised in the tracker creates a ticket, is the case that will need an unscoped variant; it can pass an empty list plus a project scope then.

⚠️ The service is self-contained on purpose

integrations.php requires encryption.php, ssl.php and tenancy.php itself rather than leaving it to the caller. It originally did not, which worked only because the first callers — the settings endpoints — happened to require them already. The workflow engine does not, and the escalate action fataled on decryptValue() the first time it ran for real. A shared service cannot assume anything about who called it.

⚠️ Never branch on a status name

Status names are per-project, per-workflow and renamed at will. Every decision in the system keys off status_category; status_name is stored for display only. This is the same lesson as tickets.merged_into_id — a merged ticket is identified by a column, never by a status called "Merged", because a user can rename it.

4. `IssueDoc` — one document, four renderers

The problem: every tracker wants a different body format.

Tracker	Format
Jira Cloud	ADF — Atlassian Document Format, a nested JSON document
Jira Data Center	wiki markup
GitHub / GitLab	Markdown
Azure DevOps	HTML

If core built strings, there would be four sets of string-building that drift. So core builds a document:

$doc = (new IssueDoc)
    ->heading('Raised in FreeITSM')
    ->para('Ticket ', IssueDoc::link($url, 'SD-1042'), ' · Jane Doe (Acme Ltd)')
    ->rule()
    ->para($ticket['description']);

…and asks for the shape it needs: toAdf(), toWikiMarkup(), toMarkdown(), toHtml(), toPlainText().

The renderers live in IssueDoc, not in the connectors. That is what makes a new tracker cheap — renderDoc() is usually one line returning an existing renderer, so adding GitHub means writing no renderer at all.

Deliberately small: heading, paragraph, link, bullet list, code block, rule. It is not a rich-text format. Anything bigger becomes a second thing that has to be kept safe against untrusted ticket text, and the house rule is that there is only ever one sanitiser (assets/js/safe-html.js) — so this stays small enough not to become a rival to it.

⚠️ Escaping is the renderer's job

Text is always treated as plain text and escaped for the target format. A requester writing "use the * wildcard" must not produce italics; <script> must not survive into an Azure DevOps description. Never pass markup in and expect it to survive.

⚠️ ADF is strict

ADF rejects empty text nodes and empty paragraphs, and a malformed document 400s the whole request with an unhelpful error. So the builders refuse to create empty blocks at all: ->para('') adds nothing, a leading ->rule() is swallowed, and an entirely empty document still renders as one valid paragraph rather than an invalid empty one.

5. 🗄️ The tables

`integration_connections`

One configured tracker instance — a Jira site, a GitHub org. credentials is a JSON blob encrypted at rest with the same helper as messaging_channels.credentials; webhook_secret likewise.

Two columns deserve a note:

account_identity — who our token authenticates as, captured at connection test. ⚠️ It is deliberately not used to suppress comments — see §7d and #956; doing so swallowed the token owner's own comments. It is kept for the inbound events guard 1 cannot cover (edits, field changes) and for a possible per-connection setting.
ingress_mode — webhook or poll. See §9.

`integration_links`

The spine: one row per "our work item ↔ their issue".

entity_type is polymorphic from day one (ticket / problem / change) even though only ticket is ever written. It costs nothing now and would be a migration later.
external_id is the provider's stable id, not the key — PROJ-412 becomes OPS-412 when a project is renamed, so the key is display only.
UNIQUE (connection_id, external_id, entity_type, entity_id) — one issue may legitimately link to two tickets, never twice to the same one.

`integration_comment_map` (#954)

One row per comment that has crossed in either direction. direction is in (tracker → note) or out (note → tracker); local_note_id is nullable because a comment pushed by a workflow has text behind it but no note.

⚠️ UNIQUE (link_id, external_comment_id) is not an optimisation, it is the guarantee. The service reads the map before importing, but that read is check-then-act: two overlapping cron runs would both pass it and both post the note. The unique key is what makes the second writer lose. Never drop it "because we check first".

This is also why the row is written before the note rather than after — see §7d.

6. ⚠️ Multi-company: a connection is a connection

This is the part most likely to be got wrong, because tenant_id means three different things in three kinds of table. See Multi-Tenancy — Developer Guide §1 for the full table; the short version for this module:

integration_connections.tenant_id NULL = shared across every company (an MSP's own Jira). Set = pinned to that one company (a client with their own Jira).

That is the connection shape — the same as mailboxes and messaging channels, and the opposite of tickets, where NULL means "the Default company's".

Consequences:

The admin list is deliberately unfiltered. Someone configuring routing needs to see every connection at once.
Never scope it with activeTenantFilter(). That treats NULL as Default-owned and would hide every shared connection from every client company.
A read that returns credentials is the exception to "capabilities guard writes, not reads". integrationsListConnections() returns has_credentials as a boolean and never the token. That is what makes an install-wide list defensible; without it, "deliberately unfiltered" would be a cross-company credential leak.

The guard

integrationsCompaniesCompatible(?int $entityTenantId, ?int $connectionTenantId, ?int $defaultTenantId): bool

Escalation is workflow-driven, and a workflow's conditions are editable by anyone who can author workflows. The wiki is blunt that inbound company routing must never become a workflow rule — it is a hardcoded synchronous membrane. This is the outbound twin of exactly that rule: without it, one mis-scoped workflow escalates Acme's ticket content into Globex's Jira.

So the check lives in code nobody can edit, and runs before any network call and before any write.

Shared connection → accepts anything.
Pinned connection → accepts only its own company.
A NULL work item is resolved to the Default company before comparing, so a Default ticket can still reach a Default-pinned connection.
No resolvable owner + a pinned target → refuse, never guess.
On a single-company install every call is trivially true — correct rather than a bypass, because there is nothing to leak to.

7. The service

integrationsEscalate() is the one place an escalation happens. The workflow action and the manual button will both call it. There is deliberately no separate "automatic" implementation, because the guards would then exist twice and one copy would eventually drift.

Order of operations, which is itself the design:

Schema gate → 2. validate → 3. load connection → 4. company guard → 5. skip_if_linked → 6. dry-run returns here → 7. create the issue → 8. record the link.

Note that dry run returns before the network call. A workflow test that minted a real Jira issue would be an unacceptable surprise.

⚠️ The schema gate

Every read goes through integrationsSchemaReady(). An install that has not run Database Verification has no tables, and an unguarded query would throw inside the ticket view. "Not set up" must look like "no linked issues", never like an error — a missing gate of exactly this kind once produced an empty inbox.

The poll cron

cron/integration_poll.php — the only way status ever changes today, since webhooks are V2. An install that never schedules it shows every issue frozen at the status it had when it was raised, which is why docs/integration-poll-cron-setup.md opens by saying so.

It honours each connection's own poll_interval_minutes, stamps last_poll_datetime even on failure (so a permanently broken connection is not retried every single run), and reports one broken tracker without abandoning the others. Same token + min-interval conventions as the webhook and SLA crons.

⚠️ A totally unreachable tracker must be reported, not hidden. JiraProvider::fetchIssues() swallows a failed chunk so one bad page does not lose the rest — but if every chunk failed it rethrows, because returning [] is indistinguishable from "none of those issues exist" and the poll would otherwise print "checked 12, changed 0" while Jira had been down for a week. That distinction was found by a test, not by reading the code.

Status refresh

integrationsRefreshConnection() batches every link on a connection into one provider call and writes only rows that actually moved, so a quiet day costs one read and no writes. An issue missing from the batch leaves its cached value alone rather than blanking it.

Only a change of category is reported as an event. A rename from "In Progress" to "In progress" is not something to wake a requester for.

7d. 💬 Comments coming back (#954)

The half that makes the integration two-way: a developer asks "what were the repro steps?" in Jira and the analyst sees it on the ticket without opening Jira.

   poll cron ─▶ integrationsPullComments()
                      │  provider->pollChanges($watermark, $watchList)
                      │     ├─ JQL: which of OUR issues changed?      (1 call)
                      │     └─ read comments on just those            (n calls)
                      ▼
              canonical comment_added events
                      │
                      ▼  integrationsApplyCommentEvent()
              have we seen this comment id? ─ yes ─▶ drop
                      │ no                    (this is the whole echo guard)
                      ▼
              map row (UNIQUE wins races) ─▶ internal note ─▶ back-fill note id

⚠️ There is deliberately no author check in that chain. #956 removed one, and the section below is why.

Three rules that are product decisions, not implementation details

Always internal. A Jira comment is written by someone who does not know a customer might read it. It never reaches the requester unless an analyst decides to pass it on. is_internal = 1, not configurable.
The first poll imports nothing. pollChanges(null, …) returns an empty array and makes no HTTP call at all; the run only writes the watermark. Without this, switching Accept updates on would tip a tracker's entire comment history onto tickets that closed months ago.
Off by default. integration_connections.inbound_enabled gates the whole path. Inbound writes to tickets, so a half-finished setup must not start posting — the same rule the messaging webhooks follow.

⚠️ Echo suppression — the loop this exists to stop

We push a note to Jira → the poll sees a new comment → it becomes a note → which pushes again → forever.

The guard is integration_comment_map, and it works by comment id. We record the id Jira returns for everything we push, so our own writing is recognised on the way back whoever appears to have written it. Its UNIQUE key makes that exact even under two overlapping cron runs.

That is the whole guard. It is enough, and it is the only one applied to comments.

⚠️ Why author identity is NOT used — a design idea that failed on contact (#956)

The original design had a second guard: drop anything authored by account_identity, the account our token authenticates as. It shipped in #954 and broke on the first live run against a real Jira.

The token owner is usually also a human who comments in Jira. So their own comments were classified as our echo and dropped — silently, with the poll cheerfully reporting 1 seen, 0 imported (skipped: echo=1). On a small team that is not an edge case; it is everybody.

It was redundant as well as harmful. Guard 1 already covers every comment we create, by id. Identity only adds value for events guard 1 cannot see — edits, attachments, field changes — none of which we process.

integrationsCommentIsEcho() is therefore kept but not applied to comments. It stays reachable through integrationsCommentSkipReason()'s $suppressByAuthor flag so that:

a per-connection "ignore comments from the connection's own account" setting is a wiring change rather than a rewrite, and
the branch is exercised by tests rather than rotting.

⚠️ Do not restore it as a default. If you find yourself reaching for author-based suppression, the regression test "A comment from OUR OWN account is still imported" is there to stop you, and this section is why.

⚠️ An unknown author is never treated as ours either. A tracker that stopped sending an author must not silently swallow every comment — the failure has to be visible.

The general lesson, which is the reason this is written up at length: the guard was correct against the model of a service account posting on our behalf, and wrong against the reality of one person owning both the token and the keyboard. It could not have been caught by any test written from the same assumption — only by running it against somebody's real Jira.

⚠️ `analyst_id = 0`, and the inner join that hid it

An imported note has no FreeITSM author. api/tickets/get_notes.php used JOIN analysts, which silently dropped every such note — presenting as "Jira comments never arrive", with nothing in any log. It is a LEFT JOIN now, and the header falls back to the connection's name.

That join turned out to be hiding real data already: on the development install 10 of 17 existing notes were invisible, written by analysts whose rows no longer exist (#955). api/tickets/delete_analyst.php is a plain DELETE that reassigns nothing, so this is the normal fate of every note a person wrote once they leave — not an edge case. An inner join on an author is a data-loss bug waiting for someone to delete a user; api/v1/resources/tickets.php and the portal's reader had both already got this right, and only this endpoint had not.

The endpoint now returns an author_kind and the browser resolves the label, because the translations live there:

`author_kind`	When	Shown as
`analyst`	the join resolved	their name
`tracker`	imported from an issue tracker	the connection's name ("Jira")
`former`	a real `analyst_id` with no row left	Former analyst
`system`	`analyst_id` 0 and no tracker behind it	System

Collapsing those four into one "Unknown" throws away information the row actually holds — which of them a note is, is knowable in every case.

Attribution is written into note_text as well as resolved by that join, because plenty of readers take note_text directly — the REST API, the portal, the AI write-up. A note reading only "any update?", with no hint it came from a dev in Jira, is worse than no note.

The watermark

integration_connections.last_poll_watermark, stamped from before the provider call so a comment posted mid-poll lands in the next window rather than the gap between them, and advanced only on success so a failed pull is retried rather than skipped past.

The provider then converts it to relative JQL minutes (updated >= -90m), never an absolute date — see the Jira page §10 for why that distinction is not cosmetic. The lookback is capped at 24 hours regardless of how stale the watermark is, which is the same "no backlog" rule as the first-poll case.

7e. 🗺️ Mapping — our vocabulary into theirs (#957)

The V3 slice. One table, one screen, applied at escalation: what our values mean in the tracker.

integrationsEscalate()
   target given by the caller?  ── yes ─▶ use it (mapping never overrides)
            │ no
            ▼
   integrationsLoadMaps(connection)
            │
   project     ─ dept:N ▸ tenant:N ▸ '*' ▸ null
   issue_type  ─ typeId ▸ '*' ▸ null
   priority    ─ priorityId ▸ null          ← no '*', deliberately

The precedence rule, and why it is that way round

integrationsResolveProject() checks department, then company, then *. A team with its own board is a sharper signal than the company a ticket belongs to, so it wins. Returning null when nothing matches is the point: an escalation with no resolvable project must say so, never file the issue in whatever project happened to be first.

⚠️ Priority has no wildcard, and that is not an oversight

issue_type and project both honour a * row. priority does not. "Everything is a Task" is a reasonable thing for an admin to mean; "every priority is Highest" would quietly mark a dev team's whole backlog urgent. An unmapped priority simply travels as text in the description, exactly as it did before mapping existed. Two tests pin this, including a positive control so the assertion is about the wildcard rather than a broken lookup.

⚠️ A rejected priority must not lose the escalation

Jira priorities are per project, so a project whose scheme renamed Highest to P1 rejects our mapped value and 400s the whole create. integrationsEscalate() catches that, drops the priority, and retries once:

if (!isset($fields['priority']) || !integrationsLooksLikePriorityRejection($e->getMessage())) throw $e;

Both halves of that condition matter. The retry is narrow on purpose — retrying on any failure could turn a genuine error into an issue nobody meant to raise — and the reason it is worth doing at all is that losing a priority is cosmetic while losing the escalation is not. The dropped value is written to integration_links.last_error so the admin can see the mapping needs attention rather than it being silent.

`local_key` is a namespaced string, not a foreign key

What it points at differs per map_type: a tenant or department for routing, a ticket type id, a priority id. So project routing namespaces it — tenant:5, dept:3, * — and one map_type covers both routing dimensions plus the fallback, instead of a second column that would be NULL most of the time.

⚠️ The ticket column is ticket_type_id, not type_id. The workflow engine's lookup key is ticket.type_id, which is not the column name — an easy way to write a query that silently returns nothing. integrationsEntityRouting() has the correct name and a comment saying so.

⚠️ `integrationsSaveMaps()` does not assume it owns the transaction

It replaces whole map types at a time (a mapping the admin deleted has to disappear, and diffing rows is more code and more ways to be wrong), so it needs a transaction — but PDO throws "There is already an active transaction" on a nested beginTransaction(). A caller that wraps it in its own — a bulk import, a test harness — would fatal.

$ownsTransaction = !$conn->inTransaction();
if ($ownsTransaction) $conn->beginTransaction();

Found by the harness that proved mapping end to end, not by review. Same lesson as this file requiring its own dependencies (§3): a shared service cannot assume anything about its caller.

The screen

api/integrations/tracker_options.php is the first thing ever to call listProjects() / listIssueTypes() over HTTP — until #957 they existed on the connector and were exercised only by tests, which is exactly why the workflow action asked admins to type a project key.

Projects and priorities are site-wide, so they load once as real dropdowns.
Issue types are per project, so they are loaded from the default routing row's project and offered as suggestions — another project on the same site may legitimately offer different ones.
A value saved earlier that the tracker no longer offers stays selectable, so it cannot vanish silently on the next save.
If the tracker is unreachable the row degrades to a free-text box rather than blocking the screen.

7a. ⚙️ The workflow surface

Two actions in WorkflowEngine::availableActions(), dispatched from executeAction():

Action	What it does
`escalate_to_tracker`	Raise an issue from a ticket and record the link
`send_note_to_tracker`	Post a comment onto the issue a ticket is already linked to

Plus one lookup source (integration_connection → integration.connection_id → the integration_connections table) feeding the connection dropdown, and argBool(), which did not exist because this is the engine's first 'type' => 'bool' arg.

The handlers do no safety checking of their own. The company guard lives in integrationsEscalate(), and a second copy would be a second copy to get wrong — especially since a workflow's args are editable by anyone who can author workflows.

Three behaviours that are deliberate

skip_if_linked defaults ON. A status-change trigger fires repeatedly on the same ticket; without this, each firing hands the dev team another duplicate.
Dry run cannot create an issue. runInner() short-circuits before executeAction(), so this is true by construction rather than by the handler remembering to check. Do not add a dry-run branch to a handler — it would be dead code implying a guarantee that lives elsewhere.
send_note_to_tracker skips rather than fails when a ticket has no link. "On status change, tell the dev team" will fire on plenty of tickets nobody escalated, and that is not an error.

⚠️ The rough edge: project and issue type are text, not dropdowns

Their valid values depend on which connection was chosen and must be fetched from the tracker's API, but the editor builds every dropdown once at page load and has no cascade mechanism. Rather than invent one, the admin types the key. Routing (V3) removes the need entirely.

This is the target-arity problem in miniature — Jira needs project + issue type, GitHub needs only a repo, Azure DevOps needs project + team + area path + iteration path. A future target descriptor (each provider declaring its target fields, the editor rendering them) is the real fix, and it is the one place a core change is expected.

7b. ⌨️ The settings screen

System → Integrations → Jira, at /system/integrations/jira.

/system/integrations/ is just a folder with an index.php — already pretty, no rewrite needed, same as system/sso/.
/system/integrations/<provider> is rewritten to provider.php?provider=<key> by a folder-level .htaccess, house style copied from api/v1/.htaccess. ^([a-z0-9-]+)/?$ so both /jira and /jira/ work with no DirectorySlash 301, behind !-f !-d guards so a real file always wins.

One shared provider.php, not a folder per provider. The form renders from the registry's credential_fields, so a tracker whose auth looks nothing like Jira's needs no change to the page, and its URL starts working the moment the connector is registered.

`inbound_enabled` — the toggle, and a warning about shipping columns early (#954)

Accept updates from {name} lives in the connection modal, under Active, and gates the whole comment path.

⚠️ The column existed from V1 and nothing ever wrote it. integration_connections.inbound_enabled was in the schema, in integrationsListConnections(), and read by the service — but no endpoint set it and no control existed, so the feature it gates could never be switched on. It looked finished from every angle except the only one that counts.

The lesson for the columns V1 shipped ahead of need (ingress_mode, poll_interval_minutes, webhook_secret): a column with no writer is not "ready", it is a trap. When you build the feature, check the write path exists rather than assuming the schema implies it.

The connections list shows an Updates on badge beside Active when it is set. That was added because "is it even on?" otherwise cost one click per connection — and because the tickbox being inside the modal made it genuinely hard to find. poll_interval_minutes still has no UI and is schema-only.

The label is system.integrations.inbound_label with a {name} placeholder — the page is shared across providers, so it must not hardcode "Jira" the way the design doc's Jira-specific vocabulary (§5.0) does.

⚠️ Apache only. web.config has no <rewrite> section, so pretty URLs do not work on IIS — the same pre-existing gap as /login. The page is still reachable at provider.php?provider=jira.

Things that will bite the next person here

.form-row is display: flex in inbox.css. Reusing that class name puts labels beside inputs and wraps them mid-phrase. This page uses .int-field instead — a scoped class beats an override war.
Full-width settings pages need BOTH. max-width: none alone does nothing while an inherited margin: … auto is still centring it. There is no auto margin here at all.
Use showConfirm / showToast, not confirm() and not a bespoke result box. Both are loaded on every analyst page by renderWaffleMenuJS().
Icon buttons break e.target. A click lands on the <path> inside the SVG, so read the attribute off closest('[data-…]').

7c. 🎫 The ticket side

A linked issue is rendered as a pill in the existing Links strip, not in a panel of its own. A Jira issue is a link, and that strip is already where an analyst looks for "what else is this connected to". Reusing it meant no new layout, no new empty state, and no new place to remember.

The pill is tinted by status_category — the four categories every provider normalises onto — so nothing on the ticket screen knows Jira's vocabulary. api/tickets/get_email_detail.php adds tracker_links to the payload.

⚠️ Rendering a ticket never calls the tracker. The status shown is whatever the poll last cached. A ticket must not take three seconds to open because somebody else's API is slow, and must not fail to open because it is down.

The manual escalate

Links strip → Link to… → Issue tracker, which opens a modal that:

lists only connections this ticket's company may use (connections_for_ticket.php applies the same company rule the service enforces — the UI half, never the enforcement);
builds the description server-side in preview mode and shows it verbatim;
escalates through escalate_ticket.php → integrationsEscalate() — the same service the workflow action uses.

⚠️ The preview is not decoration. Raising an issue is a one-way door into a system we do not control: it cannot be unsent, and anyone with access to that tracker can read it. Show the exact text first.

⚠️ `integrationsBodyToText()` — why `strip_tags()` is not enough

The first real ticket previewed produced a Jira description containing several hundred lines of the email's CSS. strip_tags() removes the tags of <style> but keeps its content, so a marketing-styled email dumps its whole stylesheet into the issue.

So the helper kills <style>/<script>/<head>/<title> outright, turns block ends into newlines, collapses the   runs and CRLF pairs HTML mail is full of, and caps the length with a visible "(truncated)" marker. It has its own tests (§8, section 7) precisely because it is the sort of thing that rots silently.

Two traps on the ticket page

Modals open with classList.add('active'), never style.display. .modal is already display: flex and hidden via visibility/opacity, so setting display achieves nothing — the click just appears to do nothing at all. This shipped to Ed once and that is exactly how it presented.
Bump inbox.js?v= in tickets/index.php. Edit the file without bumping and every browser keeps running the old one, which also looks like "the button does nothing".

8. 🧪 Testing without a live tracker

tests/integrations/run.php — 252 assertions, no database, no network:

php tests/integrations/run.php

The trick is that payload building and response parsing are separate protected methods rather than being inlined into the HTTP calls, so the suite subclasses a provider and stubs httpRequest() with a queue of canned [code, body] pairs. Everything that decides correctness — the ADF-vs-wiki choice, status mapping, error extraction, paging, auth headers — is therefore provable offline.

⚠️ Every negative assertion is paired with a positive control

"The asterisk did not become italics" proves nothing on its own; it is equally true of a renderer that dropped the text. So each escaping test also asserts the surrounding content survived.

This matters most for the company guard, which was verified in both directions by deliberate breakage:

Breakage	Result
company guard made permissive (`return true`)	exactly the 5 refusal assertions fail
company guard made refuse-everything (`return false`)	exactly the 10 permission assertions fail
comment-map guard disabled (`already_imported` never returned)	exactly 3 fail — an echo is no longer recognised

That last one is the one to repeat when touching §7d. Note what it does not prove on its own: a guard that dropped everything would also stop echoes, and would pass every negative assertion while being completely broken — which is why the positive controls beside it (a dev's comment imports, our own account's comment imports, a different id imports) carry the weight.

⚠️ #956 is the cautionary tale here. The suite was green, including assertions that specifically pinned author-based suppression as correct behaviour. The tests were faithful to a design that was wrong, so they defended the bug. Only a live run found it.

⚠️ What this suite cannot prove

It has no database, so it cannot catch a wrong column name or a unique key that does not fire. Those were verified separately by running the real integrationsApplyCommentEvent() against a live dev database inside a transaction and rolling it back — which is how the write order, the unique key, the is_internal flag and the display join were each confirmed, along with a positive control that a genuine new comment still lands. Do the same for anything here that touches SQL.

A guard that refused everything would otherwise pass the whole negative half while being completely broken. Do the same for anything you add here.

That exercise also caught an assertion that fatalled rather than failing — hiding every test after it. Guard assertions that could receive the wrong type.

9. What is not built yet

Piece	State
Settings screen (`/system/integrations/jira`)	✔ built (#948)
Workflow actions `escalate_to_tracker` / `send_note_to_tracker`	✔ built (#949)
Ticket pill and the manual escalate button	✔ built (#950)
Poll cron	✔ built (#951)
Comments tracker → ticket, echo suppression	✔ built (#954), proven against real Jira 2026-08-02; author-based suppression removed in #956 (§7d)
Comments ticket → tracker	✔ the action exists (#949); ⚠️ still never run against a live Jira — now the untested half
`tracker.*` triggers (inbound events firing workflows)	V2 — designed (§5.2), not built
Webhooks (instant instead of the poll's ~5 min)	V2 — designed (§8.1), not built
Project routing, issue-type + priority mapping	✔ built (#957, §7e)
Attachments, custom fields, components, per-analyst tokens	V3, not built
Issues raised in the tracker creating tickets	V4
GitHub, GitLab, Azure DevOps connectors	V5

The full parity scoreboard against HaloITSM — feature by feature, plus where we are already ahead and the build order — is §16 of the design doc (docs/design/external-issue-trackers.md in the app repo; local only, since docs/design/ is gitignored).

Inbound will be webhook or poll, and both must produce the same canonical events — polling is a degraded webhook, not a second pipeline. A self-hosted install behind a firewall often cannot receive an inbound call, which is the same wall the WhatsApp channel hit; the difference is that trackers all expose a queryable REST API, so the firewalled case needs no relay, it just polls.

10. Adding a new tracker

The payoff, and the test of whether the engine is right:

Write includes/integrations/<Name>Provider.php extending IssueTrackerProvider.
Implement the four abstract methods. renderDoc() is usually one line.
Map the tracker's states onto the four categories.
Declare capabilities().
Add one line to the factory and one entry to integrationsAvailableProviders() in integrations.php.

That registry entry is what makes the rest free: it carries the provider's name, blurb, URL label and — importantly — its credential_fields, which the settings form renders from. So a tracker authenticating completely unlike Jira needs no change to the settings page, and its URL /system/integrations/<key> starts working immediately.

Adding GitHub should touch nothing else. If it needs a change to the link table, the service, the settings page or the workflow action, the abstraction was wrong.

⚠️ The known exception is the workflow action's project / issue_type args (§7a) — those are Jira-shaped and a provider with a different target arity will want the target descriptor building. That is expected, and it is the one place a core change is already anticipated rather than a failure of the design.

⚠️ Validate against Azure DevOps, not GitHub. GitHub is the easy one — everything will appear to fit and you will learn nothing. DevOps breaks the most assumptions: updates use JSON Patch documents rather than a fields object, states are per-process, targets are a tree of project + team + area path + iteration path, and the body is HTML. If the contract survives DevOps, the others are trivial.

11. 📄 Keeping this page honest

This page and the code must never disagree. It documents decisions, not just mechanics, and a decision that changed in code but not here is worse than no documentation — someone will trust it.

If you change any of the following, update this page in the same commit:

the abstract method list, or which methods are optional
the four status categories, or how a provider maps onto them
IssueDoc's block types or any renderer's output shape
either table's columns, or what tenant_id NULL means (§6)
the company guard's behaviour in any case
the order of operations in integrationsEscalate() (§7)
the echo guard, or the order of writes in integrationsApplyCommentEvent() (§7d) — the map row goes in first, and that is a correctness decision, not a style one
anything that reintroduces author-based suppression (§7d, #956) — it has been tried and it silently ate real comments
the "first poll imports nothing" rule, or the lookback cap (§7d) — both are product promises made in the settings hint
that imported comments are always internal (§7d)
the workflow actions, their args, or the defaults in §7a
the provider registry's shape (§10) — it is what keeps a new tracker cheap
what is and is not built (§9), which is the first thing a reader checks

⚠️ A lesson about this page, not about the code

#948 and #949 shipped before this page was updated, and the §9 table then said "not built" about two things that were live. A wiki that is confidently wrong is worse than one that is missing — someone will trust it. Update in the same commit, not in the next one.

The design doc behind all of this is docs/design/external-issue-trackers.md in the app repo — local only, since docs/design/ is gitignored.

Jira-specific behaviour is on Jira Connector — Developer Guide, which has its own version of this note.

FreeITSM — an open-source IT Service Management platform · github.com/edmozley/freeitsm · MIT licence

FreeITSM

Home

Getting Started

External Issue Trackers Developer Guide

External Issue Trackers — Developer Guide

1. 📁 The files involved

2. The shape

3. The contract — what is generic, what is yours

What you must implement

fetchIssues() — the batch escape hatch

pollChanges(?string $since, array $externalIds = []) takes a watch list

⚠️ The service is self-contained on purpose

⚠️ Never branch on a status name

4. IssueDoc — one document, four renderers

⚠️ Escaping is the renderer's job

⚠️ ADF is strict

5. 🗄️ The tables

integration_connections

integration_links

integration_comment_map (#954)

6. ⚠️ Multi-company: a connection is a connection

The guard

7. The service

⚠️ The schema gate

The poll cron

Status refresh

7d. 💬 Comments coming back (#954)

Three rules that are product decisions, not implementation details

⚠️ Echo suppression — the loop this exists to stop

⚠️ Why author identity is NOT used — a design idea that failed on contact (#956)

⚠️ analyst_id = 0, and the inner join that hid it

The watermark

7e. 🗺️ Mapping — our vocabulary into theirs (#957)

The precedence rule, and why it is that way round

⚠️ Priority has no wildcard, and that is not an oversight

⚠️ A rejected priority must not lose the escalation

local_key is a namespaced string, not a foreign key

⚠️ integrationsSaveMaps() does not assume it owns the transaction

The screen

7a. ⚙️ The workflow surface

Three behaviours that are deliberate

⚠️ The rough edge: project and issue type are text, not dropdowns

7b. ⌨️ The settings screen

inbound_enabled — the toggle, and a warning about shipping columns early (#954)

Things that will bite the next person here

7c. 🎫 The ticket side

The manual escalate

⚠️ integrationsBodyToText() — why strip_tags() is not enough

Two traps on the ticket page

8. 🧪 Testing without a live tracker

⚠️ Every negative assertion is paired with a positive control

⚠️ What this suite cannot prove

9. What is not built yet

10. Adding a new tracker

11. 📄 Keeping this page honest

⚠️ A lesson about this page, not about the code

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

`fetchIssues()` — the batch escape hatch

`pollChanges(?string $since, array $externalIds = [])` takes a watch list

4. `IssueDoc` — one document, four renderers

`integration_connections`

`integration_links`

`integration_comment_map` (#954)

⚠️ `analyst_id = 0`, and the inner join that hid it

`local_key` is a namespaced string, not a foreign key

⚠️ `integrationsSaveMaps()` does not assume it owns the transaction

`inbound_enabled` — the toggle, and a warning about shipping columns early (#954)

⚠️ `integrationsBodyToText()` — why `strip_tags()` is not enough