Service Status Developer Guide - edmozley/freeitsm GitHub Wiki

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