Service Status Developer Guide

Service Status - Developer Guide

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

In plain words

Service Status is a board of services and the incidents affecting them. A service's status is never stored. It is worked out every time it is read: the most severe impact level among the open incidents that affect it, or the default impact level when there are none.

Every write - from the board, the REST API, Domains, planned maintenance - goes through one class, ServiceStatusService (includes/services/service_status.php). Each save also appends a snapshot to an update log, which is what the timeline, the portal and the uptime figures read.

The module is install-wide: none of its tables has a tenant_id.

Uptime and history are covered on their own page, Service uptime and history - Developer Guide, and are only summarised here.

The files

Area	File	What it is
⚙️ Service	includes/services/service_status.php	ServiceStatusService - every write rule
⚙️ Baseline	includes/service_impact_levels.php	defaultImpactLevel() - the level a healthy service shows
⚙️ Planned	includes/service_status_planned.php	planned maintenance: save, cancel, list, and turning it into an incident at its start
⚙️ Portal	includes/service_status_portal.php	the only code that decides what end users may see
⚙️ Uptime	includes/services/service_uptime.php	ServiceUptime - the read side of history (its own guide)
🖥️ Page	service-status/index.php	the board, incident list, planned maintenance and the three dialogs - its script is inline
🖥️ Page	service-status/settings/index.php + manifest.php	Services, Incident statuses, Impact levels and Uptime tabs
🖥️ Page	service-status/help.php	the in-app guide
🔌 UI API	api/service-status/*.php	session endpoints - thin adapters over the service
🔌 Portal API	api/self-service/get_dashboard.php, api/self-service/get_incident_updates.php	what the self-service portal reads
🔌 Portal switch	api/system/service_status_portal.php	the System setting that publishes incidents to the portal
🔌 REST	api/v1/resources/service_status.php	/api/v1/service-status/... - the same service, from an API key

Tables

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

Table	Holds
status_services	name, description, display_order, is_active
status_incidents	title, status_id, comment (mirrors the latest update), created_by_id, created_datetime, updated_datetime, resolved_datetime
status_incident_services	which services an incident affects now, each with its impact_level_id
service_incident_statuses	incident statuses - is_resolved is what makes an incident closed; is_default, colour, order, active
service_impact_levels	impact levels - severity_order (1 = worst), is_default (the healthy level), counts_as_downtime, colour, order, active
status_incident_updates	the update log - one row per moment: status_id, comment, is_internal, created_by_id, created_datetime
status_incident_update_services	the per-service impacts at that moment - a full snapshot per update
status_planned	planned maintenance not yet an incident - planned_start_datetime, planned_end_datetime, state, incident_id, project_id
status_planned_services	the services and impacts a plan will affect

The user page's table list uses short names (services, incidents and so on); the real names are the ones above.

In database/freeitsm.sql, status_incident_updates.incident_id is ON DELETE CASCADE from status_incidents, and status_incident_update_services cascades from its update, so deleting an incident takes its timeline with it. status_planned.incident_id is ON DELETE SET NULL.

Status derivation

There is no "current status" column anywhere. Two queries work it out, and they must agree:

• the board: api/service-status/get_dashboard.php - a correlated subquery per service;
• the REST API: apiServiceStatusSubquery() in api/v1/resources/service_status.php.

Both take, for each service, the impact level of its links in status_incident_services whose incident is open (is_resolved = 0, or no status at all), ordered by severity_order ascending, first row. No row means the default level: COALESCE(..., defaultImpactLevel()['name']). The self-service portal's dashboard does the same.

defaultImpactLevel($conn) returns {id, name, colour} for the row with is_default = 1; failing that, the least severe active level; failing that (an empty table), the literal Operational. It is cached per request and has no dependency beyond PDO, so the portal can use it.

🔴 TRAP: never write the word Operational in a reader. It used to be hardcoded in six places, and renaming the level left half the board on the old name with no colour. Ask defaultImpactLevel(), and compare against its name. The board and portal get it as default_impact in their JSON. Full story: Renaming an impact level.

The same rule appears in validateIncidentServices(): an affected service sent with no impact gets the default level by name, not a literal.

The service: ServiceStatusService

Method	What it does
saveService($conn, $ctx, $in)	Create (no id) or partial update. Fires WorkflowEngine::emitCrud('status_service', ...).
deleteService($conn, $ctx, $id)	Deletes the service and its status_incident_services links in one transaction.
saveIncident($conn, $ctx, $in)	Create when there is no id; with an id it hands over to the private updateIncident(). Create: status by status_id or status (a name), default Investigating; is_internal defaults to true; writes the incident, its links and the opening update in one transaction. Fires service_status.incident_created, and incident_resolved if it was created resolved.
updateIncident() (private)	Partial: keys left out keep their value, so a one-click Resolve sends only {id, status}. Stamps resolved_datetime once on entering a resolved status (COALESCE) and clears it on reopen. Appends an update only when the status, comment or services changed. Fires incident_updated, and incident_resolved on the move into resolved.
deleteIncident($conn, $ctx, $id)	Deletes the links and the incident. Fires service_status.incident_deleted.
validateIncidentServices($conn, $services)	[{service_id, impact_level_id or impact_level}] → [[serviceId, impactId], ...]. Strict: an unknown service or an unknown / inactive level is a 422. Public, because planned maintenance uses it too.
editIncidentUpdate($conn, $ctx, $updateId, $in)	Corrects one timeline entry in place - its comment and is_internal only. If it is the latest entry, the incident's own comment follows.
deleteIncidentUpdate($conn, $ctx, $updateId)	Removes one entry; the incident's comment becomes the new latest one's.
saveIncidentStatus(), deleteIncidentStatus()	Lookup CRUD. Setting a default clears the others; with none left the first by order is promoted. Delete refuses the default and any status still in use.
saveImpactLevel(), deleteImpactLevel()	The same for impact levels, plus severity_order and counts_as_downtime (absent means 1). With no default left, the least severe level is promoted.

The update log and what counts as an update

recordIncidentUpdate() (private) appends a row to status_incident_updates and a full snapshot of the per-service impacts to status_incident_update_services - not a diff, because replaceIncidentServices() deletes and re-inserts the live links and would otherwise lose the earlier level. Passed null links, it snapshots the current ones. It is best-effort: on an install that has not run Database Verification it logs and carries on rather than failing the save.

In updateIncident() the three "did anything change?" answers are worked out before anything is written - replaceIncidentServices() overwrites the rows incidentServicesDiffer() compares against. The comparison is order-insensitive. When only the status changed, the new entry carries no comment, so the timeline does not repeat the previous sentence under the new status. Changing only the visibility is not a new entry either: that is what editIncidentUpdate() is for.

Why the log exists and how it is read back: Service uptime and history - Developer Guide.

Internal and external

is_internal defaults to 1 in the column and to true in the service. A caller that has never heard of it - an older page, a workflow, the REST API - therefore never publishes. The board sends it explicitly from the dialog's radio buttons so the screen and the row cannot disagree.

The portal

includes/service_status_portal.php is the single place that decides what an end user may read.

• ssPortalSettings() reads three system_settings keys (SS_PORTAL_DEFAULTS): service_status_portal_updates ('0' - off by default), service_status_portal_mode (open, recent or all) and service_status_portal_days. Deliberately not cached.
• ssPortalIncidents($conn, $limit) returns [] when the switch is off, so a caller that forgets to check gets nothing. Otherwise only incidents with at least one external update, filtered by mode, each with its active affected services and its count of external updates.
• ssPortalIncidentUpdates($conn, $incidentId) - the external entries of one incident, for api/self-service/get_incident_updates.php.

api/self-service/get_dashboard.php sends the service board (the same derivation), ssPortalIncidents(), upcoming planned maintenance (only when ssPortalUpdatesEnabled()), and default_impact. The switch itself is saved by api/system/service_status_portal.php, which sits behind the System admin guard (includes/admin_api_guard.php) rather than Service Status access, because it decides what end users see. service-status/index.php renders portalShowsUpdates into the page so the dialog can say whether "external" will really reach anybody.

Planned maintenance

includes/service_status_planned.php. A plan is not an incident until it starts, because about fifteen readers decide "open" from the incident's status and none of them knows a start time.

scheduled ─(planned_start)→ started ─(planned_end)→ finished
    └─ cancelled (by hand, before it starts)

Function	What it does
statusPlannedSave($conn, $ctx, $in)	Schedule, or change while still scheduled. Needs a title, at least one service (checked with validateIncidentServices()), and an end after the start. A start already passed starts at once (statusPlannedRun($conn, $id)).
statusPlannedCancel()	Only while scheduled.
statusPlannedList($conn, $opts)	project_id, states (default scheduled + started), limit.
statusPlannedDue($conn)	One cheap query: is anything due to start or end? If so, runs statusPlannedRun().
statusPlannedRun($conn, $onlyId)	Claims each due plan with a compare-and-set on state (so overlapping runs cannot start one twice), then starts or finishes it; on failure it gives the claim back.
statusPlannedStart()	Makes an ordinary incident through ServiceStatusService::saveIncident(), external, with the first open non-default status (statusPlannedStatusId()), as the person who scheduled it (statusPlannedActor()), then backdates the incident and its opening update to the planned start.
statusPlannedFinish()	Resolves it with the first resolved status and backdates the end - unless somebody already resolved it, in which case theirs stands.

Who calls statusPlannedDue(): the board (get_dashboard.php, planned.php), the portal (api/self-service/get_dashboard.php), Watchtower (includes/watchtower_queries.php) and Projects (includes/services/project_tools.php). The scheduled workflow job runs statusPlannedRun() from includes/workflow_scheduled.php (entry point cron/workflow_scheduled.php - see Time-Based Triggers). A project attaches its project_id only through the Projects tools; planned.php strips it from the request.

Incidents raised by other modules

Everything that raises an incident calls ServiceStatusService::saveIncident(), so it gets the opening update, the impact snapshot and the workflow events exactly like one typed in by hand. As of this writing the callers are:

Caller	How
Domains	includes/domains/status_link.php: domainStatusRaise() (the Raise incident button, and the scheduled run in mode auto) and domainStatusRun() (auto-resolve). One incident per outage, never twice for the same trouble (domain_status_incidents), internal unless domain_status_public says otherwise. The scheduled actor is ActorContext with actorId: 0 and the name Domains. Details: Domains - Developer Guide §12.
Planned maintenance	statusPlannedStart() and statusPlannedFinish(), above.
REST API	apiStatusIncidentsCreate() / apiStatusIncidentsUpdate() - see REST API: Service Status.

domainStatusImpactId() deliberately falls back to the most severe level that counts as downtime, not the default: on a stock install the default is "Operational", and an incident saying the service is fine would be worse than none.

Readers outside the module include Watchtower, Report Packs (includes/report_packs/blocks_status.php), Warbot (includes/warbot/tools.php), and Microsoft Teams alerts, whose "Status page incident" alert listens for service_status.incident_created (includes/integrations/msteams.php).

The UI endpoints

All need a session and requireModuleAccessJson('service-status'). The settings writes also need a capability (Cap::SERVICE_STATUS_SERVICES, _STATUSES, _IMPACTS, _UPTIME; umbrella Cap::SERVICE_STATUS_MANAGE). Incident and update writes need module access only - the module has no Read only level.

Endpoint	Calls
get_dashboard.php	services with their derived status, open and last-30-days incidents with their services, planned, default_impact
get_services.php, get_incident_statuses.php, get_impact_levels.php	lookups for the dialogs and Settings
get_incident_updates.php	one incident's whole timeline, internal and external, oldest first
get_service_history.php	one service's history and uptime (ServiceUptime)
save_incident.php, delete_incident.php	saveIncident(), deleteIncident()
save_incident_update.php, delete_incident_update.php	editIncidentUpdate(), deleteIncidentUpdate()
planned.php	GET list (?states=); POST action = save or cancel
save_service.php, delete_service.php	saveService(), deleteService()
save_/delete_incident_status.php, save_/delete_impact_level.php	the lookup methods
save_uptime_settings.php	status_uptime_window_days, status_uptime_show_portal

The board page

service-status/index.php holds three dialogs (#incidentModal, #updateEditModal, #plannedModal) and an inline script with API_BASE = '../api/service-status/'. Main functions:

Function	Does
loadDashboard()	fetches the three lookups and get_dashboard.php, then draws everything
renderServiceGrid(), toggleServiceHistory(), loadServiceHistory(), renderServiceHistory()	the service cards and their history strip
renderIncidents(), toggleIncidentUpdates(), reopenUpdateThreads()	the incident list and each one's timeline
openIncidentModal(), editIncident(), addServiceRow() + the incidentForm submit handler	create / edit; the payload sends status by name, services as {service_id, impact_level} and is_internal explicitly
resolveIncident()	one-click Resolve: the first status with is_resolved, sent alone; says so plainly when none exists
deleteIncidentById(), editUpdate(), deleteUpdate()	delete an incident; correct or remove a timeline entry
renderPlanned(), openPlannedModal(), addPlannedServiceRow()	planned maintenance
openIncidentContextMenu()	the right-click menu (Edit, Resolve, Delete, Show updates)

REST API

api/v1/resources/service_status.php - routes /service-status/services[/{id}] (scope services) and /service-status/incidents[/{id}] (scope service_incidents), plus the read-only lookups /service-incident-statuses and /service-impact-levels (scope reference). Writes call ServiceStatusService with ActorContext::fromApiKey($apiKey). There is no REST endpoint for planned maintenance, incident updates, or the incident-status and impact-level lookups' writes. Usage: REST API: Service Status.

Workflow events

service_status.incident_created, incident_updated, incident_resolved and incident_deleted, each with incident.id, incident.title and (except deleted) incident.status_id; registered in workflow/includes/engine.php. Services, statuses and impact levels also emit generic CRUD events through WorkflowEngine::emitCrud() (status_service, incident_status, impact_level). See Workflows.

Related pages

• Service Status - the user page
• Service uptime and history · its Developer Guide
• REST API: Service Status · Mobile: Service Status
• Renaming an impact level (#70) · Self-Service Portal · Domains - Developer Guide · Service Layer Architecture