How Change Management is built. For what it does and how to use it, start with the user page: Change Management.

A change is one row in changes. Every write to it - from the change page, the table view, the right-click menu or the REST API - goes through one class, ChangesService (includes/services/changes.php). That class keeps the audit trail, the full history of the long-text fields, the approval rounds and the workflow events, all inside one transaction per write.

The approval rules (stages, Record / Enforce, rounds, votes, templates) live in three helper files under includes/changes/. They were designed in the three-part Approvals and evidence series; this page summarises them and links there for the detail.

The front end is one big script, assets/js/change-management.js, behind change-management/index.php. The Calendar, Table and Approvals pages are thin pages with their own small scripts.

All in includes/db_verify_schema.php and database/freeitsm.sql.

change_checklist_items and change_notifications are in the schema but nothing in the module reads or writes them; only the analyst offboarding map (includes/analyst_lifecycle.php) mentions them.

⚠️ TRAP: change_approvals is ON DELETE RESTRICT from changes - a change with rounds is evidence. deleteChange() deletes the rounds itself, deliberately, before the change row. Votes cascade from their round.

Each UI endpoint and each REST handler turns its caller into an ActorContext plus an input array and calls one method. The service validates, writes and returns an id or a small result array, or throws ServiceError; it never sends HTTP. See Service Layer Architecture for the pattern.

• One transaction, one row lock. inTransaction() runs the work (or joins the caller's transaction - analyst offboarding moves many records at once), and lockRow() takes SELECT ... FOR UPDATE on the change. Two last votes landing together used to both tip the threshold; now the second waits.
• Events after commit. The apply*() methods return closures; afterCommit() fires them. A rolled-back save never sends its email.
• Company scope in one place. loadJoined() 404s a change outside the actor's company scope, the same as one that does not exist. NULL tenant_id counts as the Default company. See Multi-Tenancy Developer Guide.
• Read only is refused in the service too. assertCanWrite() refuses an actor whose module level is read, so an API key acting as a read-only analyst cannot write either. It is deliberately not called by voteCab() or decideApproval(): approving is identity, not a write, so a read-only approver can still approve.
• Risk (since #246). Ratings are validated and assessed by ChangeRiskPolicy (includes/changes/risk_policy.php) on a risk policy: the change's own version, or the one in use for a first rating. The result is read from the policy's matrix - never by banding the score, which is still likelihood x impact. risk_level stores the result's word: on the built-in 5 x 5 the same English word as before (Low ... Critical), which the front end translates for display; on a saved policy the organisation's own word, shown as typed. risk_policy_version_id (NULL = built-in) records the scale. A full-form save that sends a change's own ratings back leaves an older change on its scale; different ratings or risk_reassess move it to the current policy. The whole model is in Change risk policies - Developer Guide.
• Dates go through parseDate() to UTC Y-m-d H:i:s; an unparseable one is a 400.
• People must exist and be active (resolveAnalyst()); the audit trail names them, not their ids.

A status's name means nothing to the code - its stage does. CHANGE_STAGES in includes/changes/approvals.php is draft, awaiting, approved, implementing, done, stopped; stageOf() reads it, and a NULL stage means "not classified yet". When the code needs to move a change it asks changeStatusForStage($conn, $stage) for the first active status in that stage - never a name. Why: Part 1 §3.

What applyUpdate() does when the stage changes:

The guard. In Enforce mode every path that sets status_id calls changeApprovalGuardMove(?array $round, array $to, array $cfg), which refuses (409 approval_required) a move into Approved, Implementing or Done without an approved round, except an open emergency round going into Implementing or Done. Record mode never refuses. The editor's status dropdown disables what the guard would refuse, from allowed_status_ids (changeApprovalAllowedStatuses(), returned by get.php) - comfort only.

⚠️ The code sketch in Part 1 §10 shows the design-time signature with $conn, $change and $from. The function as built takes (?array $round, array $to, array $cfg), and the row lock is lockRow().

Settings come from changeApprovalSettings(): the system_settings keys in CHANGE_APPROVAL_DEFAULTS (every default is the pre-3.8.0 behaviour), normalised into $cfg. In Enforce mode edit_withdraws, stale_refused and delete_refused are always true.

changeApprovalRoute() picks the route for a new round: cab when cab_required, approver when there is a named approver, else manual. routeFor() makes it emergency for a type whose approval_route is emergency. The other routes - override, pre_authorised, legacy - are written by the code that records them.

applyVote() counts only this round's counted votes from change_approval_votes:

• one counted required Reject → the round is rejected and an awaiting change moves to rejectTarget() (the Settings choice if it is still an active Draft or Stopped status, else the first Draft one);
• all: every counted required member approves; majority: more than half → approved, and an awaiting change moves to the first approved-stage status;
• Abstain never moves anything; optional members never count;
• voteCounts(): in Enforce mode the change's own people (changeApprovalOwnPeople()) are recorded but not counted, unless Settings allows it. In Record mode they count and the round is marked not independent.

A vote or decision carries the round id and content_hash the page was drawn with; changeApprovalCheckVersion() marks it was_current = 0 or refuses it. Full design: Part 1 §5 and §7.

Who may set up the approval. Setting the approver, cab_required, cab_approval_type or the roster needs analystMayAct($conn, $actorId, Cap::CHANGES_CHOOSE_APPROVERS), which only bites when Settings → Approvals restricts it. See Part 3.

ChangeTemplates (includes/changes/templates.php). The Templates tab edits the working draft in change_templates; submitVersion() freezes it as a change_template_versions row; approveVersion() approves it (superseding the previous approved one; the version's author cannot approve it unless Settings allows approving your own); retire() retires the template. mayUse() reads change_template_teams (no rows = everyone with the module).

In the service, preAuthorise() calls ChangeTemplates::check(): the version must be approved and not retired, templates must be switched on, the person must be allowed to use it, and the sha256 of the template's fixed fields must still match the change (fixedHash()). If so, it records an approved pre_authorised round and moves an awaiting change on to Approved. If not, the change takes the normal route. With templates switched off they still pre-fill a change; they never approve one. Design: Part 1 §8.

ChangeRevisions::FIELDS lists the eight long-text fields that keep every version: the six rich-text bodies plus pir_lessons_learned and pir_follow_up. write() stores the whole new value in the same transaction as the save; ensureBaseline() first stores the old value as a baseline ("as found when history began") for a change older than the feature. The audit row is text_edit with Revision #<id>. Design: Part 2.

change-management/evidence.php renders the evidence pack on the server: the change, every round and vote, every text version, the audit trail, comments including deleted ones, and attachments with sha256. Taking it writes an evidence_export audit row. Every stored text is printed through sanitiseUserHtml() or escaped. The share menu's PDF option is a different, client-side export (shareChangePdf() / buildPdfContent() / changePdfDocument()): html2canvas draws the content off screen at the printable width and the picture is cut into A4 pages, each placed in the PDF by FreeITSM's shared PDF writer (FitsmPdf.create(), on PDFKit since #254 - see PDF writer - Developer Guide). Until 4.1.0 html2pdf did this with its own older copy of jsPDF bundled inside it; the three steps then moved into changePdfDocument() so the install had one, current jsPDF, and since #254 there is no jsPDF at all. The text colour is set there too - inherited from a dark theme it came out pale grey on the white page.

All need a session and requireModuleAccessJson('changes'). Writes also call requireModuleWriteJson('changes') (Read only access is refused there and in the service). Voting (submit_cab_vote.php) and the approver decision (decide_approval.php) deliberately do not.

The file list in Part 1 §15) names approve_template_version.php, retire_template.php and get_approval_rounds.php. As built, the first two are template_action.php, and the rounds come back inside get.php.

assets/js/change-management.js is split into regions by // ============ Name ============ comments. The ones worth knowing:

The table view's inline edit (change-table.js) posts one field to update_field.php; status is not editable there.

Changelog #2730, commit 41fa6fd43. Any ticket - an incident, a request, a problem report, whatever types the install has - could always be linked to a change; nothing in the code ever filtered by type. The screen just called them all "incidents". 4.9.0 changed the wording to "tickets" in every locale and shows each linked ticket's type. The table, the API field and the stored audit marker were deliberately left alone, and that is most of what a developer needs to know here.

change_tickets in database/freeitsm.sql:

CREATE TABLE IF NOT EXISTS `change_tickets` (
    `id`               INT NOT NULL AUTO_INCREMENT,
    `change_id`        INT NOT NULL,
    `ticket_id`        INT NOT NULL,
    `created_by_id`    INT NULL,
    `created_datetime` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uq_change_ticket` (`change_id`, `ticket_id`),
    KEY `ix_ctickets_ticket` (`ticket_id`),
    CONSTRAINT `fk_ctickets_change` FOREIGN KEY (`change_id`) REFERENCES `changes` (`id`) ON DELETE CASCADE,
    CONSTRAINT `fk_ctickets_ticket` FOREIGN KEY (`ticket_id`) REFERENCES `tickets` (`id`) ON DELETE CASCADE

A plain many-to-many: a ticket can be linked to several changes and a change to several tickets, once each (uq_change_ticket). There is no type column, and none is needed - the type is the ticket's own ticket_type_id, read through a join when it is shown. The link goes with either side when that side is deleted.

api/change-management/list_linkable_tickets.php?change_id=&q= feeds the Link ticket picker. It builds its WHERE in steps:

// Scope to the change's own company (matches the same-company rule in link_ticket).
$where = " WHERE t.deleted_datetime IS NULL AND t.closed_datetime IS NULL";
$params = [];
if (isMultiTenant($conn)) {
    $ct = $conn->prepare("SELECT tenant_id FROM changes WHERE id = ?");
    $ct->execute([$changeId]);
    $cten = $ct->fetchColumn();
    $eff = ($cten === null || $cten === false) ? getDefaultTenantId($conn) : (int) $cten;
    if ($eff === getDefaultTenantId($conn)) {
        $where .= " AND (t.tenant_id = ? OR t.tenant_id IS NULL)";
        $params[] = $eff;
    } else {
        $where .= " AND t.tenant_id = ?";
        $params[] = $eff;
    }
}

// Exclude already-linked.
$where .= " AND t.id NOT IN (SELECT ticket_id FROM change_tickets WHERE change_id = ?)";
$params[] = $changeId;

• Open, not trashed. deleted_datetime IS NULL drops the ticket trash; closed_datetime IS NULL drops closed tickets. A status that is not is_closed (such as a Resolved status set up that way) is still offered.
• The change's company, not the analyst's. On a multi-company install the picker lists only tickets in the same company as the change, because the service would refuse anything else (below). A change with a NULL tenant_id belongs to the Default company, and Default-company tickets can have NULL too, hence the OR t.tenant_id IS NULL branch. A single-company install skips the block entirely.
• Not already linked, through the NOT IN subquery on this change's own links.
• An optional ?q= adds t.ticket_number LIKE ? OR t.subject LIKE ?.

The select is where #245 added the type:

$sql = "SELECT t.id, t.ticket_number, t.subject, t.created_datetime,
               ts.name AS status, tt.name AS ticket_type, COALESCE(NULLIF(TRIM(u.display_name),''), u.email) AS requester
        FROM tickets t
        LEFT JOIN ticket_statuses ts ON ts.id = t.status_id
        LEFT JOIN ticket_types tt ON tt.id = t.ticket_type_id
        LEFT JOIN users u ON u.id = t.user_id
        $where
        ORDER BY t.created_datetime DESC
        LIMIT 200";

LEFT JOIN, not JOIN: tickets.ticket_type_id is nullable, and a ticket with no type (or a type since deleted) must still be offered, just without a pill. The requester falls back from a blank display name to the email address.

api/change-management/get.php returns the links inside the change:

// Linked tickets - any type, not only incidents (GH #245); the key stays 'incidents'
// because the screen and older callers read it. Degrades to [] if the table isn't present yet.
$change['incidents'] = [];
try {
    $incSql = "SELECT t.id, t.ticket_number, t.subject, ts.name AS status, tt.name AS ticket_type
               FROM change_tickets ct
               JOIN tickets t ON t.id = ct.ticket_id
               LEFT JOIN ticket_statuses ts ON ts.id = t.status_id
               LEFT JOIN ticket_types tt ON tt.id = t.ticket_type_id
               WHERE ct.change_id = ? AND t.deleted_datetime IS NULL
               ORDER BY t.created_datetime DESC";

Unlike the picker, closed tickets are shown - a link made while a ticket was open stays visible after it closes. Trashed tickets are hidden but the link row survives, so restoring the ticket from the trash brings the link back.

TRAP: the response key is incidents and stays incidents. renderLinkedIncidents() reads c.incidents, and anything outside the screen that reads get.php may too. The field was not renamed with the wording; it now holds tickets of every type.

api/change-management/link_ticket.php and unlink_ticket.php are thin adapters (they also accept a ticket_number, looked up to an id). The rules are in includes/services/changes.php:

// Same-company rule: NULL normalises to Default.
if (isMultiTenant($conn)) {
    $default = getDefaultTenantId($conn);
    $cTid = $change['tenant_id'] === null ? $default : (int)$change['tenant_id'];
    $tTid = $ticket['tenant_id'] === null ? $default : (int)$ticket['tenant_id'];
    if ($cTid !== $tTid) {
        throw new ServiceError('validation', 'invalid_field', 'That ticket belongs to a different company than this change.');
    }
}

Before that, linkTicket() calls assertCanWrite(), loads the change through loadJoined() (a change outside the actor's company scope is a 404), and checks the actor can see the ticket too (canAccessTenantRow($conn, $ctx, 'tickets', $ticketId)). The same-company rule is a separate, stricter check: an analyst who can see both companies still cannot link a ticket in one to a change in the other. A duplicate is refused with a conflict before the insert, so the unique key is never the thing that answers.

Then the link and its audit row:

$conn->prepare("INSERT INTO change_tickets (change_id, ticket_id, created_by_id, created_datetime) VALUES (?, ?, ?, UTC_TIMESTAMP())")
     ->execute([$changeId, $ticketId, $actorId]);
// TRAP: 'Linked incident' is a stored marker, not wording - the timeline matches it
// (change-management.js) and shows the translated "linked ticket". Renaming it would
// orphan every existing history row; the screen went neutral in GH #245, this stays.
self::auditWrite($conn, $changeId, $actorId, 'field_change', 'Linked incident', null, $ticket['ticket_number']);

unlinkTicket() reads the ticket number first (falling back to #<id>), deletes the row (404 Link not found. when nothing was deleted), and writes the mirror image: the same field_name, with the number in old_value and new_value NULL:

self::auditWrite($conn, $changeId, $ctx->actorId, 'field_change', 'Linked incident', $ticketNumber, null);

Both touch changes.modified_datetime.

The audit trail stores field_name = 'Linked incident' for both directions. The activity timeline in assets/js/change-management.js (renderActivityTimeline()) recognises the rows by that exact string and draws them in the reader's language:

} else if (entry.field_name === 'Linked incident') {
    description = entry.new_value
        ? `${window.t('change-management.detail.linked_incident')} <span class="new-val">${escapeHtml(entry.new_value)}</span>`
        : `${window.t('change-management.detail.unlinked_incident')} <span class="old-val">${escapeHtml(entry.old_value)}</span>`;

new_value set means linked, old_value set means unlinked. The keys kept their old names too; their English is now 'linked_incident' => 'linked ticket' and 'unlinked_incident' => 'unlinked ticket' in lang/en/change-management.php.

Do not rename the stored string. Every change on every install already has rows saying Linked incident. Change the service to write Linked ticket and the old rows stop matching, falling through to the generic changed <strong>Linked incident</strong> to ... line, while new rows show differently from old ones. To change the wording, change the translation, never the marker. The same reasoning kept the JS function names (renderLinkedIncidents(), linkChangeIncident(), unlinkChangeIncident()) and the CSS classes (.linked-incidents-table and friends).

Each linked ticket's row now carries its type beside the number, only when there is one:

<td><a href="../tickets/index.php?ticket_id=${i.id}" target="_blank" rel="noopener">${escapeHtml(i.ticket_number || ('#' + i.id))}</a>${i.ticket_type ? ` <span class="linked-ticket-type">${escapeHtml(i.ticket_type)}</span>` : ''}</td>

The type name is set by an administrator, so it is escaped like everything else in the row. The picker (loadLinkableIncidents()) shows it in the meta line between the number and the status: ${t.ticket_type ? ' · ' + escapeHtml(t.ticket_type) : ''}.

The pill, in assets/css/change-management.css, uses theme variables with light fallbacks so it follows dark mode:

.linked-ticket-type {
    display: inline-block;
    margin-left: 6px;
    padding: 1px 8px;
    border-radius: 10px;
    background: var(--surface-2, #f3f4f6);
    border: 1px solid var(--border, #e5e7eb);
    color: var(--text-muted, #6b7280);
    font-size: 12px;
    font-weight: 500;
    white-space: nowrap;
}

No test in tests/ covers linked tickets. By hand, on a test install:

1. Link a ticket of a non-incident type to a change: the picker shows its type in the meta line, the row shows the pill, and the timeline says linked ticket. Unlink it: unlinked ticket.
2. A change whose history has links from before 4.9.0 still shows them as linked ticket lines, not as changed Linked incident - the marker check.
3. A ticket with no type links and shows with no pill.
4. Multi-company: a change in company A lists only company A's tickets; posting another company's ticket id to link_ticket.php is refused.
5. Switch to dark mode and check the pill is readable.

api/v1/resources/changes.php registers its routes in api/v1/lib/routes.php and calls the same ChangesService methods with ActorContext::fromApiKey($apiKey), so every rule above applies to the API too. Changes are company-scoped there as well (changes.tenant_id). Usage: REST API: Changes.

• Watchtower (includes/watchtower_queries.php) counts awaiting changes by stage and open emergency rounds through changeApprovalEmergencyOpenCount().
• Problem Management links a change to a problem through change_relations.
• Projects read changes for their links and the "change approved" gate (includes/projects/gatecheck.php, includes/projects/links.php).
• Workflows hear change.created, change.approved, change.submitted, change.resubmitted, change.rejected, change.approval_withdrawn and change.deleted - see Part 1 §11 and Workflows.

• Change Management - the user page
• Approvals and evidence - design · Part 1 - approvals · Part 2 - text history · Part 3 - approver and reviewer access
• REST API: Changes · Mobile: Change Management · Saved table views - Developer Guide
• Module Access Control · Roles and Permissions