Change Management Developer Guide

Change Management - Developer Guide

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

In plain words

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.

The files

Area	File	What it is
⚙️ Service	includes/services/changes.php	ChangesService - every write rule for a change
⚙️ Approvals	includes/changes/approvals.php	stages, approval settings, rounds, the guard on status moves
⚙️ Text history	includes/changes/revisions.php	ChangeRevisions - every saved version of the long-text fields
⚙️ Templates	includes/changes/templates.php	ChangeTemplates - standard-change templates and their approved versions
🖥️ Page	change-management/index.php	the list, detail view and editor (one page, three views)
🖥️ Page	change-management/new/index.php	/change-management/new/ - sets $openCreateOnLoad and includes ../index.php
🖥️ Page	change-management/calendar.php + assets/js/change-calendar.js	month / week / day calendar
🖥️ Page	change-management/table.php + assets/js/change-table.js	full-screen grid on the shared data-table engine
🖥️ Page	change-management/approvals.php	the approvals queue (its script is inline)
🖥️ Page	change-management/evidence.php	the server-rendered, printable evidence export
🖥️ Page	change-management/settings/index.php + manifest.php	Settings tabs and the capability each needs
🖥️ Script	assets/js/change-management.js	the main front end (see below)
🖥️ Script	assets/js/change-revisions.js	the text-history viewer (get_revisions.php, get_revision.php)
🔌 UI API	api/change-management/*.php	session endpoints - thin adapters over the service
🔌 REST	api/v1/resources/changes.php	/api/v1/changes... - the same service, from an API key
📁 Files	change-management/attachments/<change id>/	uploaded files; never served directly (.htaccess + web.config deny), only through get_attachment.php

Tables

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

Table	Holds
changes	the change: lookups (change_type_id, status_id, priority_id, impact_id, category_id), people (requester_id, assigned_to_id, approver_id, created_by_id), work and outage windows, the six rich-text bodies, risk (risk_likelihood, risk_impact_score, risk_score, risk_level), PIR fields, cab_required / cab_approval_type, approval_id (the current round), approval_datetime, template_version_id, tenant_id
change_statuses	name, colour, stage, is_closed, default / order / active
change_types	the same, plus approval_route (review or emergency)
change_priorities, change_impacts, change_categories	plain lookups
change_field_sections, change_field_layout	the configurable form (which section each fixed field sits in, its order, visible or not)
change_cab_members	the CAB roster, and each member's vote in the current round
change_approvals	one row per approval round - route, state, snapshot, content_hash, who decided, is_independent, closed_reason
change_approval_votes	every vote ever cast - is_counted, content_hash, was_current
change_text_revisions	every saved version of a long-text field, and the text of deleted comments
change_audit	the audit trail - action_type, field_name, old_value, new_value
change_comments	comments on the timeline
change_attachments	files, with sha256 and client_reference (REST idempotency)
change_tickets	incidents (tickets) linked to a change
change_templates, change_template_versions, change_template_teams	standard-change templates: the working draft, its versions, who may use it
change_relations	a change's link to a problem - written from Problem Management, not from this module

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.

The service: ChangesService

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.

Public methods

Method	What it does
createChange($conn, $ctx, $tenantId, $in)	Inserts a change in the company the adapter chose. Lookups by name or <key>_id, strict (an unknown one is a 422); defaults from lookupDefault(). Computes risk. Writes the "Created as ..." audit row and a first text revision for each long field. With template_version_id it fills in the template's values and may pre-authorise. Created straight into an awaiting stage opens a round; straight into approved records a manual round. Fires change.created.
updateChange($conn, $ctx, $changeId, $in)	Partial update - absent keys are left alone, so the table's inline edit (update_field.php) is the same method with one key. Writes one audit row per changed field, a revision per changed long field, recomputes risk, then moves the approval round with the status (see Lifecycle).
cancelChange($conn, $ctx, $changeId, $in)	Moves the change to the Stopped-stage status changeCancelTarget() picks, with an optional reason, and withdraws an open round. What a change with approval history gets instead of Delete.
deleteChange($conn, $ctx, $changeId)	Refused (409 change_has_approval_history) where the settings keep submitted changes. Otherwise deletes the rounds, attachment rows and the change in one transaction, and the files only after it has committed. Fires change.deleted.
decideApproval($conn, $ctx, $changeId, $in)	The named approver's Approve / Reject, on a change with no CAB. Checked against the version on screen and for independence.
overrideApproval($conn, $ctx, $changeId, $in)	An administrator approves without the vote, with a written reason. Only when Settings → Approvals allows override; recorded as an override round.
createComment(), deleteComment()	A comment is always internal. Deleting copies the text, author and date into change_text_revisions (source deleted) first, then audits the deletion.
saveCab($conn, $ctx, $changeId, $members)	Replaces the CAB roster by diff (add / remove / required-optional), one audit row each. Fixed once submitted in Enforce mode.
voteCab($conn, $ctx, $changeId, $in)	The acting analyst votes Approve, Reject or Abstain. Needs an open round and a roster place, and refuses a second vote. Writes the member row and a change_approval_votes row, then counts the round.
linkTicket(), unlinkTicket()	Link / unlink an incident in change_tickets; same company required on a multi-company install; audited.
uploadAttachment($conn, $ctx, $changeId, $file, $reference)	Stores the file through uploadStoreFile() (includes/uploads.php), hashes it, and inserts the row - in its own transaction (it throws if one is already open, because a rollback cannot undo a file move). A repeated client_reference with the same name and bytes returns the existing id with replayed: true.
auditAttachment()	The audit row for a file added or removed, with the start of its sha256. delete_attachment.php calls it.

Rules every write follows

• 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. riskLevel() bands likelihood x impact: up to 4 Low, 9 Medium, 15 High, 20 Very High, else Critical. Each input must be 1-5 (riskInput()).
• 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.

The lifecycle in code

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:

Move	What happens to the round
into awaiting	changeApprovalGuardSubmit() checks somebody independent can decide it (Enforce); the old round is closed (withdrawn or superseded), CAB votes are cleared, a new round opens. Fires change.submitted or change.resubmitted.
into approved by hand	Stamps approval_datetime and records a manual round, so the history never shows a vote that did not happen. Fires change.approved with route manual.
back to draft, or past the decision by hand	The round is withdrawn (an emergency round stays open into Implementing and Done). Fires change.approval_withdrawn.
a material edit while a round stands	Where an edit withdraws approval (Enforce, or Settings say so): the round is superseded, an approved change goes back to awaiting, and a new round opens. Otherwise nothing is written and the panel says "approved against an earlier version".

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.

CAB and approvers

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.

Standard changes (templates)

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.

Text history and evidence

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 jsPDF cuts it into A4 pages. Until 4.1.0 html2pdf did this with its own older copy of jsPDF bundled inside it; the three steps now live in changePdfDocument() so the install has one, current jsPDF. The text colour is set there too - inherited from a dark theme it came out pale grey on the white page.

The UI endpoints

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.

Group	Endpoints
Read	list.php (status and search filters, counts; ?analysts=1 for the people list), get.php (the change plus approval, approval_rounds, approval_rules, template, allowed_status_ids), get_calendar_changes.php, get_approvals.php (filter = all, assigned, requested, cab), get_audit.php, get_comments.php, get_revisions.php, get_revision.php, get_attachment.php, get_field_layout.php, get_usable_templates.php, list_linkable_tickets.php
Write	save.php (create or full update - maps the UI's date keys to the service's *_at keys), update_field.php (one field), cancel.php, delete.php, save_comment.php, delete_comment.php, save_cab_members.php, upload_attachment.php, delete_attachment.php, link_ticket.php, unlink_ticket.php, move_to_company.php, send_share_email.php, override_approval.php
Approve	submit_cab_vote.php, decide_approval.php
Settings	save_/delete_change_status.php, _priority, _type, _impact (each behind its own Cap::CHANGES_*), save_field_layout.php (Cap::CHANGES_FIELDS, against the fixed catalogue in _field_catalogue.php), get_/save_approval_settings.php (Cap::CHANGES_APPROVALS), get_templates.php / save_template.php (Cap::CHANGES_TEMPLATES), template_action.php (action = approve or retire, requireActionJson(Cap::CHANGES_TEMPLATES_APPROVE, $conn))

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.

The front end

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

Region	Main functions
Initialization	the DOMContentLoaded handler - loads layout, lookups, analysts and the list; opens ?change_id= (also open, change, id) or create mode for /new/
Form Layout	loadFormLayout(), isFieldVisible(), refreshFormLayout() - places the fixed fields into the configured sections
Data Loading	loadStatuses(), loadChanges() (list.php), updateCounts()
View Change Detail	viewChange() (get.php), renderChangeDetail()
Linked incidents	renderLinkedIncidents(), linkChangeIncident(), unlinkChangeIncident()
Risk Matrix / PIR	renderRiskMatrix(), renderPirDetail(), updateRiskScore(), updatePirVisibility()
Activity Timeline	loadActivityTimeline() - fetches get_audit.php and get_comments.php in parallel and merges them newest first; renderActivityTimeline(), postComment()
Create / Edit	openCreateChange(), editCurrentChange(), loadChangeTemplatePicker(), applyChangeTemplate(), applyApprovalEditorRules() (disables statuses and locks the approval set-up), savingWithdrawsApproval() (warns before a material edit)
Save / Delete	saveChange() (saves, then the CAB roster when CAB is on), deleteCurrentChange(), confirmDelete()
Attachments	setupFileUpload(), uploadFiles(), deleteAttachment()
TinyMCE / tabs	initEditors(), destroyEditors(), switchTab() - the six rich-text fields share one tabbed widget
CAB editor	toggleCabConfig(), addCabMember(), renderCabMemberChips()
CAB Review Panel	renderApprovalPanel(), renderCabReviewPanel(), submitCabVote(), submitApproverDecision(), handleStaleApproval(), openOverrideDialog(), cancelCurrentChange()
Share	shareChangeLink(), shareChangePdf(), sendShareEmail(), buildPdfContent(), changePdfDocument()
Context menu	openChangeContextMenu(), saveChangeFieldFromContext() (status, priority, type, impact through update_field.php), moveChangeToCompanyFromContext()

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

REST API

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.

Elsewhere in the product

• 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.

Related pages

• 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