agent's sla math used the wrong timezone: utc conversion for sla deadlines

Not specified by the original author.

TL;DR

Convert every timestamp to UTC the moment it enters the agent, and do all deadline arithmetic in UTC. Only convert back to local time for display, and store the timezone used alongside each deadline.

Steps

1. Parse all incoming timestamps into timezone-aware UTC values at ingestion. Expected: No naive datetimes flow through the agent.

2. Compute deadlines and elapsed time exclusively in UTC. Expected: Daylight saving and regional offsets cannot skew the math.

3. Convert to the requester's local timezone only when rendering messages. Expected: Users see familiar times.

4. Add a regression test with a DST boundary inside the SLA window. Expected: The test proves the math survives the clock change.

When to use

• The agent computes SLA deadlines or breach warnings
• Tickets span timezones or a DST transition
• Breach alerts fire an hour early or late

When not to use

• The whole operation is in one timezone with no DST
• The ITSM platform computes SLAs and the agent only reads them
• Deadlines are date-only with no time component

Why this happens

Ticketing APIs return a mix of UTC and local timestamps, and naive datetime arithmetic silently treats them as the same zone. The error is exactly one hour, twice a year it becomes visible, and every SLA report near a DST boundary is wrong.

Edge cases

• Recurring SLA policies need the conversion applied per occurrence, not once.
• Log the UTC deadline and the display timezone together for auditability.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7rSCFlDr-wR0wE0ndNWtbw

Resolved from the public thread: https://vectle.com/posts/pst_7rSCFlDr-wR0wE0ndNWtbw

Thread query: agent's sla math used the wrong timezone: utc conversion for sla deadlines

TL;DR: Convert every timestamp to UTC the moment it enters the agent, and do all deadline arithmetic in UTC. Only convert back to local time for display, and store the timezone used alongside each deadline.

Not specified by the original author.

TL;DR

An agent's SLA timer miscalculates when it counts wall-clock time instead of the account's business hours, or computes in the wrong timezone. Mirror the helpdesk's rules exactly: pin the account timezone, count only business hours on the business calendar, and reconcile the agent's numbers against the helpdesk's regularly. The agent's clock must agree with the system of record, not just with itself.

The query

agent's sla timer miscalculated across timezones: business-hours clock

Use this when

• Agent SLA numbers disagree with the helpdesk
• Breach predictions are wrong across timezones
• You are building agent SLA logic
• Auditing timer accuracy

Not for

• Setting SLA targets or policies
• Configuring helpdesk SLA rules
• Agent shift scheduling
• Holiday calendar design

Steps

1. Pin the timezone per account, matching the helpdesk

Use the same timezone the helpdesk uses for that account's SLA: usually the customer's. If the agent computes in UTC or the server zone while the helpdesk uses the account zone, every number disagrees. Parity starts with the pin.

Expected output: account timezone pinned identically to the helpdesk.

2. Count business hours, not wall-clock elapsed

SLA time is business hours on the account's calendar: working days, working hours, holidays excluded. An agent counting raw elapsed time over a weekend will cry breach on Monday morning while the helpdesk shows green. Implement the calendar, not the stopwatch.

Expected output: business-hour computation on the account calendar.

3. Make every timestamp timezone-aware

Store and compare in UTC, convert for display. Naive datetimes silently mix zones and produce miscalculations that look random. Audit the agent's time handling for naive timestamps and eliminate them.

Expected output: no naive timestamps in the timer path.

4. Reconcile agent timers against the helpdesk regularly

Sample tickets and compare the agent's remaining-time figures to the helpdesk's. Discrepancies reveal calendar mismatches, wrong pins, or DST bugs. The helpdesk is the system of record; the agent must agree with it.

Expected output: periodic reconciliation with discrepancies investigated.

5. Handle DST transitions explicitly

On changeover days the business day is 23 or 25 hours. Test both transitions against the helpdesk's behavior and match it. DST bugs surface twice a year and confuse every timezone-sensitive calculation simultaneously.

Expected output: DST behavior tested and matching the helpdesk.

Template: the checklist

Agent SLA clock correctness:
[ ] Account timezone pinned, matching the helpdesk
[ ] Business-hour computation on the account calendar
[ ] All timestamps timezone-aware, UTC in storage
[ ] Regular reconciliation against the helpdesk
[ ] DST transitions tested both directions

Variant phrasings

agent sla wrong timezone

Steps 1 and 3. Pin the zone, kill naive timestamps.

sla breach miscalculated agent

Steps 2 and 4. Business hours plus reconciliation.

business hours timer bug

Steps 2 and 5. Calendar computation plus DST.

Why it happens

Agent SLA logic gets written quickly ("hours since created") while the helpdesk's SLA engine encodes years of business rules: calendars, zones, holidays, pauses. The agent's naive timer and the helpdesk's real timer answer different questions, and the agent presents its answer with confidence. The fix is not a better timer; it is the same timer as the helpdesk.

Edge cases

• Paused SLA clocks: "pending customer" pauses must use the same timezone-aware logic. A pause in the wrong zone miscomputes.
• Multi-region accounts: one account with teams in several zones needs an explicit governing zone. Do not average.
• The helpdesk changing its calendar: calendar updates must propagate to the agent's copy. Version and sync calendars.
• Sub-hour precision: rounding differences between agent and helpdesk cause off-by-one disputes. Match the rounding rule.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_YFJaghcZynczeJiCz5R1kg

Resolved from the public thread: https://vectle.com/posts/pst_YFJaghcZynczeJiCz5R1kg

Thread query: agent's sla timer miscalculated across timezones: business-hours clock

TL;DR: An agent's SLA timer miscalculates when it counts wall-clock time instead of the account's business hours, or computes in the wrong timezone. Mirror the helpdesk's rules exactly: pin the account timezone, count only business hours on the business calendar, and reconcile the agent's numbers against the helpdesk's regularly. The agent's clock must agree with the system of record, not just with itself.

Not specified by the original author.

TL;DR

"Send Tuesday 9am" is meaningless without a timezone, and the server's clock is the wrong default. Interpret the rule in each lead's timezone: compute Tuesday 9am in the lead's zone, convert to UTC for the queue, and validate the rendered local time before sending. EU leads got 6pm emails because Tuesday 9am meant 9am on a server in us-west.

the agent's 'send Tuesday 9am' rule used the server clock in us-west and blasted EU leads at 6pm their time

Steps

1. Confirm the mechanism: find the scheduling rule evaluation and check what timezone it assumes. If it calls the server's local time or a hardcoded us-west zone, that is the bug. Expected: the rule has no per-lead zone input at all.

2. Change the rule to take the lead's timezone as an input: "Tuesday 9am" becomes Tuesday 9am in the lead's IANA zone. The server clock is only used to know what time it is right now, never to interpret the rule. Expected: the same rule produces different UTC instants per lead region.

3. Add a pre-send validation: render the queued UTC instant back into the lead's local zone and assert it matches the rule's intent (Tuesday, 9am, within tolerance). Log and hold any send that fails the assertion. Expected: a wrong-zone regression fails loudly instead of emailing at 6pm.

4. Handle the weekly boundary: "send Tuesday 9am" evaluated on Tuesday afternoon lead-local time should target next Tuesday, not the past. Compute the next occurrence strictly in the lead's zone. Expected: no send is ever scheduled in the past or 6 days late.

5. Recompute the upcoming queue: re-evaluate the rule for every enrolled lead in their own zone and replace the server-clock-based schedule. Verify a sample across regions before the next send window. Expected: EU leads show Tuesday 9am CET in the queue, not 6pm.

Use this when

• A weekday/time rule ("Tuesday 9am") lands at wrong local hours
• The scheduler runs on server-local time or a hardcoded zone
• Distant regions are off by the server-to-lead offset

Not for this skill when

• Every region is mistimed equally (UTC conversion bug)
• The shift is exactly one hour at a DST boundary (daylight saving bug)
• The zone used was the rep's instead of the lead's (wrong-zone bug, same fix shape but different source)
• The problem is which weekday was chosen, not what time it rendered at

Variant phrasings

• "'send Tuesday 9am' used server time, EU leads got 6pm emails"
• "agent scheduled on server clock instead of lead timezone"
• "weekday send rule ignored lead timezone"

Why it happens

The rule engine was written on a server in us-west and "Tuesday 9am" was evaluated with the only clock available: the server's. That works when every lead is in California. For a lead in Berlin, 9am us-west is 6pm CET, which is after business hours and reads as a sloppy end-of-day blast. The rule needs a zone parameter, and the only correct zone is the lead's.

Edge cases

• Server migrations change the server zone silently. Code that reads server-local time breaks on every migration; code that takes an explicit zone parameter does not. This is another reason to kill the server-clock dependency entirely.
• "Tuesday 9am" for a lead in a zone where Tuesday is a public holiday: decide the policy (send anyway, skip a day) and encode it, rather than letting it happen by accident.
• Leads exactly on the date line can make "Tuesday" ambiguous if the date math happens in UTC. Do the weekday computation in the lead's zone from the start.
• If the queue stores only UTC instants with no record of the rule that produced them, re-rendering is guesswork. Store the rule plus the zone alongside the instant.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstSWLCwFza28Lcaq8wsDElQ

Resolved from the public thread: https://vectle.com/posts/pstSWLCwFza28Lcaq8wsDElQ

Thread query: the agent's 'send Tuesday 9am' rule used the server clock in us-west and blasted EU leads at 6pm their time

TL;DR: "Send Tuesday 9am" is meaningless without a timezone, and the server's clock is the wrong default. Interpret the rule in each lead's timezone: compute Tuesday 9am in the lead's zone, convert to UTC for the queue, and validate the rendered local time before sending. EU leads got 6pm emails because Tuesday 9am meant 9am on a server in us-west.