Skip to content

Issue 375 REST API Wall Clock Times

Ed Mozley edited this page Nov 17, 2026 · 2 revisions

πŸ•— #375 REST API: change windows and ticket scheduled work were treated as UTC

GitHub #375, reported by @cloudcogsio Β· REST API, Change Management, Tickets Β· fixed in 5.5.0 (#2994)

What you saw

An API client in Toronto (UTC-5) created a change for 20:46-22:10 on 16 November:

POST /api/v1/changes
{ "title": "...", "work_start_at": "2026-11-16T20:46:00-05:00", "work_end_at": "2026-11-16T22:10:00-05:00" }

The change calendar put it on 17 November, 1:46 AM - 3:10 AM. Reading it back through the API looked right - "2026-11-17T01:46:00Z" is the same moment - so the client had no way to tell anything was wrong. A ticket's scheduled work did the same.

What was wrong

FreeITSM has two kinds of date and time, and the difference is the whole story (GH #116):

  • An instant - when something happened: created_at, closed_at, a time entry. Stored in UTC, shown in each reader's own time zone, sent by the API with a Z.
  • A wall-clock time - what a person typed into a form: a change's work, outage and PIR windows, a ticket's scheduled work, a task's schedule, a calendar event. Stored as typed and shown exactly as typed to everyone (formatNaiveDateTime() in the UI), never converted.

The app treated the change and ticket schedules as wall-clock. The REST API treated the same columns as instants, in both directions:

// includes/services/changes.php and tickets.php - parseDate(), used for these fields
$dt = new DateTimeImmutable($v, new DateTimeZone('UTC'));
return $dt->setTimezone(new DateTimeZone('UTC'))->format('Y-m-d H:i:s');   // 20:46-05:00 -> 01:46 next day

// api/v1/resources/changes.php and tickets.php
'work_start_at' => apiIsoDate($r['work_start_datetime']),                   // adds a Z

and the spec's own examples sent UTC ("2026-07-05T20:00:00Z"). Any client that followed them stored every time shifted by its UTC offset.

Was it more than one place? Ten fields over two resources, plus the filters: changes work_start_at, work_end_at, outage_start_at, outage_end_at, pir_actual_start_at, pir_actual_end_at; tickets work_start_at, work_end_at; and the changes work_start_from / work_start_to filters, which compared those columns with a UTC-converted value. Two other parts of the API already did it right: task scheduling (TasksService::parseNaiveDateTime()) and the calendar resource (apiParseNaiveDatetime()).

The trap inside the trap: TicketsService::parseDate() is also used for a time entry's entry_at, which really is an instant. Changing parseDate() would have broken time entries; the two schedule fields now call the wall-clock parser instead, and parseDate() stays for entry_at.

The fix

One parser for every wall-clock field, next to ServiceError so any service can use it:

// includes/service_context.php
function serviceWallClockDateTime($value, string $field): ?string
// accepts 2026-11-16T20:46:00, 2026-11-16 20:46, 2026-11-16 (midnight); drops fractions of a second;
// refuses a Z or an offset (422) rather than converting it
  • ChangesService::parseDate() calls it (every date a change stores is wall-clock); TicketsService calls it for work_start_at / work_end_at.
  • The API returns these fields with apiWallClockDate(): "2026-11-16T20:46:00", no Z.
  • The filters use apiParseWallClock() (400 on an offset).
  • spec.json and the OpenAPI schemas describe them as local wall-clock times, drop format: date-time (which means an RFC 3339 instant, with an offset), and the examples lose their Z.

Why refuse an offset instead of converting it to the server's zone? There is no single right zone to convert to - FreeITSM shows these times exactly as typed to analysts in any zone - and silently guessing is how this bug happened. A clear 422 tells the client what to send. It matches task scheduling and the calendar API, so the whole API now has one rule.

⚠️ What changes for API clients

A client that sends these fields with a Z or an offset now gets 422:

'work_start_at' is a local wall-clock time and must not carry a time zone (no Z or offset): send it as YYYY-MM-DDTHH:MM:SS, exactly as it should show.

Those clients were already storing shifted times; send the local time the change should show instead. Reads now return these fields without a Z - parse them as local times. Every other date in the API (created_at and so on) is unchanged: UTC with a Z. The app's own forms already sent local times and behave exactly as before.

Records created through the API before 5.5.0 with a Z are still stored shifted; they are not changed by the upgrade, because nothing records which ones came from the API. Correct them in the app, or by sending the right local time.

πŸ“ Files

File Change
🟣 includes/service_context.php serviceWallClockDateTime()
🟣 includes/services/changes.php parseDate() is wall-clock
🟣 includes/services/tickets.php work_start_at / work_end_at use the wall-clock parser; entry_at unchanged
🟣 api/v1/lib/response.php apiWallClockDate(), apiParseWallClock()
🟣 api/v1/resources/changes.php, tickets.php Output without a Z; the work filters
βšͺ api/v1/spec.json, api/v1/lib/openapi_schemas.php Described; examples without Z
🟒 tests/api-wallclock-times.php 26 checks, part 2 over real HTTP

How it was verified

Reproduced first over real HTTP on a test install, with the issue's own values: POST /changes with 20:46:00-05:00 gave 201, stored 2026-11-17 01:46:00 and returned "2026-11-17T01:46:00Z"; a ticket PATCH did the same.

tests/api-wallclock-times.php: 26 passed. Part 1 checks the parser (local forms accepted, Z and offsets refused, an impossible date refused). Part 2, over HTTP: an offset is refused on POST and PATCH and nothing is stored; a local time is stored as sent and comes back without a Z, including the outage and PIR times; the filters compare local times and refuse a Z; a ticket's created_at still has its Z. Control: on the old code 10 fail, with the shifted values above. The existing change suites (approvals, risk policy, approver access, attachments) pass unchanged.

What this means for you

If you only use the app: nothing changes. If you have an integration that writes change or ticket schedules through the REST API: update it to send local times without a Z before upgrading to 5.5.0.

Not covered here, and not checked: CMDB properties of type date are returned as …T00:00:00Z, so a client that converts that to a western time zone may show the day before.

Related: REST API: Changes Β· Timezones and date formats Β· REST API: Calendar

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally