Add Slack; cross-link from Issue Trackers and the sidebar
Slack as a messaging channel (freeitsm #977), proven end to end on a real
workspace. Covers why it is NOT a third issue tracker, the bring-your-own-app
decision and what it costs, the two setup traps that produce silently degraded
results rather than failures, every scope with its justification, the file map,
and the four bugs the live run found that the test suite could not.
Issue trackers: workflow rules work the same for both (#967)
Ed asked whether the workflow module can drive Azure DevOps like it does
Jira. It can — you pick a CONNECTION, so the tracker follows from that
and nothing about writing the rule differs. The page now says so, since
"raise it in Jira" implied otherwise.
Added, because they are the two ways a rule can be written and still be
wrong:
- leave Project and Issue type BLANK and the connection's mapping
decides, which sidesteps the next point entirely;
- ⚠️ if you fill them in they mean different things per tracker — Jira
wants the key, Azure DevOps the name — and Azure DevOps issue types
come from the project's template, so a rule hard-coded to Bug works
against an Agile project and fails against a Basic one in the SAME
organisation.
Also noted that the tracker triggers can branch on which tracker fired
them, so per-tracker rules are possible rather than one rule having to
serve both.
Neutralised the last two Jira-shaped paths in shared sections (the
mapping screen's location, the dry-run note).
Verified no dead in-page anchors.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Issue trackers: make the analyst page genuinely cover both (#964)
Ed asked "what should the project key be if I send it to devops" — and
that question was the review. The page defined project key as "the KAN
in KAN-6", which is not merely Jira-flavoured wording but ACTIVELY WRONG
for Azure DevOps, where there is no key at all and the project NAME is
the identifier.
The connector page shipped with the connector; this is the analyst half
catching up properly rather than having a DevOps preamble bolted onto a
Jira walkthrough.
- "Which project?" is now a two-row table, because the answer genuinely
differs: Jira wants the KEY, Azure DevOps wants the NAME, and getting
it wrong produces a permission-shaped error that reads like bad
credentials.
- "Which issue type?" gains the per-PROCESS table. ⚠️ Two projects in
ONE Azure DevOps organisation can disagree about whether Bug exists —
Basic has no Bug at all — so "raise it as a Bug" is not a safe default
the way it reads on Jira. Also documents that a blank type becomes a
Task, because Task is the one type in every process.
- The connection table is now Jira | Azure DevOps side by side, which is
where the missing email field and the extra Resolved setting become
obvious rather than needing prose.
- Neutralised the shared prose that quietly assumed Jira: the scheduled
check, the multi-company rule, the never-blocks-the-ticket note and
the comments section all describe behaviour that is not Jira's.
Kept Jira-specific what genuinely is — the Atlassian token steps are
scoped with a marker rather than generalised into uselessness.
Verified: no dead in-page anchors after renaming "Comments from Jira",
no dead page links.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Issue trackers: Azure DevOps connector, and the contract test it settled (#964-966)
New page: Azure-DevOps-Connector-Developer-Guide, the sibling of the Jira
one. Issue-Trackers gains Azure DevOps setup and the Resolved setting;
the two guides that PREDICTED this work now record how it turned out.
The engine guide committed to a falsifiable claim before Jira shipped:
adding connector #2 must touch nothing but the provider, one registry
row and its settings partial. It held, and the page now says so with the
three things that did change for everyone:
- settings_fields, and why it is separate from credential_fields — a
dropdown among the credential boxes inherits their blanking rule and
silently resets on every save;
- integrationsAbsoluteUrl(), because the ticket link every connector
puts in an issue was built from BASE_URL, which is a path, so it 404'd
from inside any tracker and had never worked;
- $target may be keyed either way — core's neutral `issue_type` or the
provider's own word — because reading only one silently creates the
wrong kind of work item.
The Jira guide's "if you are writing the next connector" list is now
marked as validated, with two of its decisions reclassified as Jira-ONLY
now there is something to compare against:
- relative JQL dates exist because Jira reads an absolute date in the
USER's timezone. Azure DevOps honours an explicit UTC Z. Copying
either across is a bug, and both are right for their own tracker;
- flavour-dependent author_identity is an Atlassian quirk, not a general
requirement. What IS general is that it match testConnection().
What the new page records that the code cannot say for itself:
- ⚠️ which field holds the body depends on the work item TYPE. A Bug's
form shows Repro Steps and not System.Description, so writing the
description to the obvious field returns 200 and produces a work item
that looks empty to the developer who opens it;
- 🔑 five state categories, not four, and why the fifth is a per-connection
SETTING rather than a mapping — plus the live vindication of "never
branch on a status name": "Resolved" is category Resolved on a Bug and
InProgress on a User Story, same project;
- ⚠️ timePrecision=true is a query parameter, not a body field, and the
tempting fix for the error it throws silently re-reads a day of comments;
- ⚠️ echo suppression must use createdBy.id — the two endpoints report
DIFFERENT descriptor formats for the same person, so comparing those
never matches and every comment we write comes back as a developer's;
- ⚠️ attachments are two steps and step one attaches the file to nothing;
- ⚠️ a rejected token answers 203 with a sign-in page, not 401 with JSON.
Also corrected two stale rows in the analyst page's "not there yet"
table: attachments and "tell the requester when it is done" both shipped
weeks ago and were still listed as missing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Issue trackers: document mapping (#957)
Engine guide gains 7e: the precedence rule and why it is that way round,
why priority has no wildcard, the narrow rejected-priority retry, the
namespaced local_key, and two traps — the column is ticket_type_id not
type_id, and a shared service must not assume it owns the transaction.
Analyst page gains a Mapping section in plain terms, and the Jira page
records that mapping needed no connector change beyond listPriorities(),
which is the abstraction doing its job.
Add a Scheduled tasks page; bring the tracker dev guides current
New page: Scheduled-Tasks. Ed asked for one place covering every cron
job / Windows task FreeITSM needs, because "you must schedule something
or comments never arrive" was buried in the Jira page. Covers all four
jobs, what silently breaks without each, Windows and Linux commands, how
to run one by hand, and how to tell whether they are working.
Also documents what is NOT a scheduled task, so nobody goes looking for
a job that does not exist or schedules the InTune workers, which the app
starts itself. Notes that mail is fetched by the browser, so nothing is
collected overnight with every browser closed.
Windows gotchas that cost time today: /ru SYSTEM tasks are invisible to
a non-elevated session, 0x41303 means "not yet run", and the escaped
quoting fails if a path has spaces.
Linked from Home, the sidebar, and five places in Issue-Trackers.
Dev guides brought current for #954-956: assertion count 227, range
#945-956, the pipeline diagram no longer shows the removed author
guard, and a new note on inbound_enabled — a column that shipped in V1
with no writer, so the feature it gated could never be turned on. That
is a trap worth naming for the other columns V1 shipped early.
Issue trackers: why author-based echo suppression was removed (#956)
Records the failure and the reasoning, at length, because the idea is
tempting enough that someone will reach for it again: "authored by our
account, therefore our own echo" assumes a service account that never
types, and the token owner is usually a human who comments.
Also notes the uncomfortable part — the suite was green and contained
assertions pinning the wrong behaviour, because they shared the design's
assumption. Only a live account found it.
Issue trackers: say what "the check" is, and where the tickbox lives
Both raised by Ed while setting this up for real, and both were fair.
"Run the poll" was jargon that meant nothing to a user. The page now
explains the check in plain terms — FreeITSM asks Jira rather than Jira
calling us — says that nothing on the page works until it runs, and
shows how to run it once by hand for testing.
The Accept updates tickbox is inside the connection, not on the list
page, so the page now spells out the pencil-then-scroll route, notes the
token box can stay blank, and adds both to troubleshooting.
Issue trackers: comments coming back, and the join that hid notes (#954)
The engine guide gains 7d — the inbound pipeline, both echo guards, the
"first poll imports nothing" rule and why the comment map row is written
before the note (the unique key is what wins a race between two cron
runs, not the check before it).
The Jira guide gains 7: two calls rather than one per issue, why the JQL
date must be relative (an absolute one is read in the Jira user's
timezone, not UTC), why the ADF reader lives in the connector rather
than IssueDoc, and that author_identity must match testConnection() or
echo suppression silently stops working.
The analyst page documents the toggle, that imported comments are always
internal, and that enabling it does not bring back a backlog.
Also recorded: get_notes.php inner-joined notes to their author, so 10
of 17 notes on the dev install were invisible. Both dev pages now list
what forces an update, including the rules above.
Issue trackers: the analyst page, and cross-links (#945-953)
The dev pair existed but the analyst page did not, so a user had no
page at all. Issue-Trackers covers setup (including the API token
living in the Atlassian account, not Jira), raising an issue, reading
the pill, automating it with a workflow rule, and an honest 'what is
not there yet' — comments coming back is named as the biggest gap
rather than left to be discovered.
Also: sidebar entry, and both dev pages now point at it.