From bf7f6d476b2f3274eb3a2d7fc0b29583109b0a0c Mon Sep 17 00:00:00 2001 From: johnnyq Date: Fri, 13 Nov 2026 02:41:53 -0500 Subject: [PATCH] Word contract SLA targets as the SLA clock counts them: slaMinutesText now gives formatSlaMinutes in business time, so the contract page, the contract and template windows, the contract document and its PDF read 4 business hours and 6 business days where they read 4 hrs and 2 days; add an exact option to formatSlaMinutes that drops no remainder, used by contracts and Admin > SLAs so both word a target the same, with the emails unchanged; keep the old wording only for comparing fingerprints through the new contractDocumentIs, so a contract signed or out for signature before this is not marked as changed or withdrawn by the rewording alone and keeps the text it was sent with; a document now depends on the business hours wherever a target is a business day or more; changelog entries for 26.11.8 including an Upgrading note to check signed copies; no database change --- CHANGELOG.md | 7 +++-- admin/modals/sla/sla_form.php | 2 +- admin/sla.php | 8 ++--- functions/contract.php | 24 +++++++++++---- functions/contract_signature.php | 52 +++++++++++++++++++++----------- functions/sla.php | 13 ++++++-- 6 files changed, 72 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index efa3c24a1..4a7d36129 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ This file documents all notable changes made to ITFlow. ### Upgrading -Update from Maintenance > Update — Queue Update hands the job to cron and it applies on its own. There is no database change in this release, so nothing else is required. From 26.11.3 or earlier, the same update also brings 26.11.4 and its database changes - see its notes below. +Update from Maintenance > Update — Queue Update hands the job to cron and it applies on its own. There is no database change in this release, so nothing else is required. If clients have signed contracts with you, read the first Contracts entry under Bug Fixes: a signed copy may give shorter response times than the ones your SLAs time tickets by. From 26.11.3 or earlier, the same update also brings 26.11.4 and its database changes - see its notes below. ### New Features & Updates @@ -36,6 +36,8 @@ Update from Maintenance > Update — Queue Update hands the job to cron and it a - Backups: the window for exporting the master key said the key "is not written anywhere". An encrypted copy is filed with the other backups; the window now says so, and that every agent is notified of the export. - SLAs: business hours saved with the day ending before it starts were accepted, and SLA clocks then ran around the clock without saying so - a 4-hour target given late on a Friday came due that evening. They are now refused, with how to set cover around the clock. A warning percent outside 1 to 99 is kept within it. - SLAs: the message after saving an SLA with an apostrophe in its name showed a backslash in it. +- Contracts: a contract's response times - on its page, in its window and in the document the client signs - were worded in plain time, where SLA clocks count only your business hours. With a 9 to 5 day, a 48-hour resolution target read "2 days" and a 24-hour one "24 hrs", where the clock gives 6 and 3 business days. They now read as the clock counts them - "4 business hours", "6 business days" - the same as Admin > SLAs and the emails to clients. A contract already signed, or out for signature, keeps the wording it was sent with and is not marked as changed. Open the signed copy of any contract whose targets run to a business day or more: if it promises more than you meant, set the SLA's targets to what you meant in Admin > SLAs, or send the contract to be signed again. +- Contracts: because the wording now follows your business hours, changing them changes what a target of a business day or more comes to. A contract signed from this release on is then marked as changed since it was signed, as it is when its SLA's targets are changed. ### Developer Updates @@ -66,7 +68,8 @@ Update from Maintenance > Update — Queue Update hands the job to cron and it a - `admin/modals/sla/`: `sla_add.php` and `sla_edit.php` share the new `sla_form.php`, which posts `response_hours` and `response_minutes`, `resolution_hours` and `resolution_minutes`; `holiday_generate.php` is new, in place of the year box in the card's header; `holiday_add.php` is tidied. `add_sla` and `edit_sla` (`admin/post/sla.php`) add hours to minutes, so a caller that sends only `response_minutes` and `resolution_minutes` as totals gets what it did before. - `admin/post/sla.php`: `add_sla` and `edit_sla` check the name and targets first; `edit_sla_settings` takes the hours as HH:MM, refuses a day that ends before it starts when any day is picked, and keeps `warning_percent` within 1 to 99; the messages count tickets properly and say which ("1 ticket not yet closed", "80 tickets not yet closed" - a save works out again every ticket still to close, resolved ones included, which can be more than the open tickets a row counts), use the name as typed, and `generate_holidays` says when every one was already in. What is saved, the restamping of open tickets and the audit log are unchanged. - Removing a closure day is a `button.confirm-link` in its form (`js/confirm_modal.js`) in place of an inline `onsubmit="return confirm()"`, and Archive carries its own `data-confirm-*` text. -- Found and left alone: `slaMinutesText()` (`functions/contract.php`), which words an SLA on contracts and in the contract form, calls 2880 minutes "2 days" where the clock and `formatSlaMinutes()` make it 6 business days of a 9 to 5 day. +- `slaMinutesText()` (`functions/contract.php`), which words a target for `contractSlaTargets()` and the contract document, is now `formatSlaMinutes($minutes, true)`. `formatSlaMinutes()` gains `$exact`, which drops no remainder ("1 business day 7 hours 30 minutes"): a contract and Admin > SLAs say a target in full, and the emails keep the rounder wording, as the deadline is next to it there. +- The old wording stays behind `$old_wording` on `slaMinutesText()`, passed along by `contractSlaTargets()`, `contractSlaTableHtml()`, `contractPlaceholderValues()`, `contractFillTerms()` and `contractDocumentHtml()`, and only `contractDocumentIs($row, $as_of, $hash)` asks for it. `contractSignatureCheckChanged()` and `contractSignatureOutdated()` compare a round's `contract_signature_document_hash` through it - the document in today's wording, then in the old - so a round sent up to 26.11.7 is not withdrawn or marked outdated by the rewording alone. A document's fingerprint now depends on the business days and hours wherever a target is a business day or more. - Hooks for tests and scripts: `data-sla-view` on each view's link, `data-sla-list` with `data-sla-id` on each row, `data-sla-default-for`, `data-sla-archive` and `data-sla-restore`; `data-sla-days` with `data-sla-day` (the date) on each row; `data-sla-new`, `data-sla-new-day` and `data-sla-us-holidays`; `data-sla-default` (the priority) on each default's select, `data-sla-closures`, `data-sla-alerts-stopped` and `data-sla-now`. ## [26.11.7] diff --git a/admin/modals/sla/sla_form.php b/admin/modals/sla/sla_form.php index e1513e8f4..2cf01ccad 100644 --- a/admin/modals/sla/sla_form.php +++ b/admin/modals/sla/sla_form.php @@ -70,7 +70,7 @@ $f_day_minutes = slaBusinessDayMinutes();
0) { ?> - Targets count business hours only. Your business day is , so 24 hours here is , not one - for a target of two business days, give . + Targets count business hours only. Your business day is , so 24 hours here is , not one - for a target of two business days, give . No business hours are set, so the clocks run around the clock and a target is plain time - 24 hours is one day. diff --git a/admin/sla.php b/admin/sla.php index a345701e4..55d5cc7c9 100644 --- a/admin/sla.php +++ b/admin/sla.php @@ -168,13 +168,13 @@ if (intval($row['config_enable_cron']) !== 1) { // An SLA's targets in a line - "Respond in 4 business hours, resolve in 6 business days" $targets_text = function ($sla) { - return 'Respond in ' . formatSlaMinutes($sla['sla_response_minutes']) - . (intval($sla['sla_resolution_minutes'] ?? 0) > 0 ? ', resolve in ' . formatSlaMinutes($sla['sla_resolution_minutes']) : ''); + return 'Respond in ' . formatSlaMinutes($sla['sla_response_minutes'], true) + . (intval($sla['sla_resolution_minutes'] ?? 0) > 0 ? ', resolve in ' . formatSlaMinutes($sla['sla_resolution_minutes'], true) : ''); }; // A target for the list: how long it is in business time, and under it the hours as typed once that is days $target_html = function ($minutes) use ($day_minutes) { $minutes = intval($minutes); - $html = '' . escapeHtml(ucfirst(formatSlaMinutes($minutes))) . ''; + $html = '' . escapeHtml(ucfirst(formatSlaMinutes($minutes, true))) . ''; if ($minutes >= ($day_minutes ?: 1440)) { $html .= '
' . escapeHtml(formatSlaClockMinutes($minutes)) . '
'; } @@ -486,7 +486,7 @@ $pill_url = function ($view) use ($on_days) {

SLAs are optional. A new ticket gets the SLA its client's contract gives its priority, else the default for the priority. With neither, it has none and nothing about it changes.

-

Targets are business time. 0 ? 'Four hours given an hour before the day ends runs out three hours into the next business day - and 24 hours is ' . escapeHtml(formatSlaMinutes(1440)) . '.' : 'With no business days picked the clocks run around the clock, so a target is plain time.' ?>

+

Targets are business time. 0 ? 'Four hours given an hour before the day ends runs out three hours into the next business day - and 24 hours is ' . escapeHtml(formatSlaMinutes(1440, true)) . '.' : 'With no business days picked the clocks run around the clock, so a target is plain time.' ?>

Two clocks. Response runs until the first reply. Resolution runs until the ticket is resolved, and stops while it is in a status that pauses it, like On Hold - set in Ticket Statuses.

How you're doing. The SLA Summary and SLA by Client reports show how often targets were met.

diff --git a/functions/contract.php b/functions/contract.php index fd2b6dca1..24333432b 100644 --- a/functions/contract.php +++ b/functions/contract.php @@ -342,18 +342,30 @@ function contractDefaultHints() { return $hints; } -/** An SLA's targets in words - "Respond in 1 hr, resolve in 8 hrs". */ -function contractSlaTargets(array $sla) { - $text = 'Respond in ' . slaMinutesText($sla['sla_response_minutes']); +/** An SLA's targets in words - "Respond in 1 business hour, resolve in 2 business days". $old_wording as slaMinutesText() has it. */ +function contractSlaTargets(array $sla, $old_wording = false) { + $text = 'Respond in ' . slaMinutesText($sla['sla_response_minutes'], $old_wording); if (intval($sla['sla_resolution_minutes'] ?? 0) > 0) { - $text .= ', resolve in ' . slaMinutesText($sla['sla_resolution_minutes']); + $text .= ', resolve in ' . slaMinutesText($sla['sla_resolution_minutes'], $old_wording); } return $text; } -/** Minutes in words - "45 min", "4 hrs", "2 days". */ -function slaMinutesText($minutes) { +/* + * A target in words, as the SLA clock counts it - "45 minutes", "4 business + * hours", "6 business days" (formatSlaMinutes(), with nothing rounded off). + * + * $old_wording is how it read up to 26.11.7 - "45 min", "4 hrs", "2 days" - + * which was plain time where the clock counts business time: 48 hours of a 9 + * to 5 day is six business days, not two. Nothing is worded that way any + * more; it is kept so that a document sent or signed with those words is + * still known for the same document (contractDocumentIs()). + */ +function slaMinutesText($minutes, $old_wording = false) { $minutes = intval($minutes); + if (!$old_wording) { + return formatSlaMinutes($minutes, true); + } if ($minutes > 0 && $minutes % 1440 === 0 && $minutes >= 2880) { return ($minutes / 1440) . ' days'; } diff --git a/functions/contract_signature.php b/functions/contract_signature.php index d10abb663..7fe4b2e65 100644 --- a/functions/contract_signature.php +++ b/functions/contract_signature.php @@ -117,16 +117,16 @@ function contractSlaRows(array $row, $date = null) { return $rows; } -/** The response times as a table - for [SLA] and the document's own section - as of $date. */ -function contractSlaTableHtml(array $row, $date = null) { +/** The response times as a table - for [SLA] and the document's own section - as of $date. $old_wording: see slaMinutesText(). */ +function contractSlaTableHtml(array $row, $date = null, $old_wording = false) { $html = '' . ''; foreach (contractSlaRows($row, $date) as $priority => $item) { $sla = $item['sla']; $html .= ''; if ($sla) { - $html .= '' - . ''; + $html .= '' + . ''; } else { $html .= ''; } @@ -135,8 +135,8 @@ function contractSlaTableHtml(array $row, $date = null) { return $html . '
PriorityRespond withinResolve within
' . escapeHtml($priority) . '' . escapeHtml(slaMinutesText($sla['sla_response_minutes'])) . '' . (intval($sla['sla_resolution_minutes']) > 0 ? escapeHtml(slaMinutesText($sla['sla_resolution_minutes'])) : 'No set time') . '' . escapeHtml(slaMinutesText($sla['sla_response_minutes'], $old_wording)) . '' . (intval($sla['sla_resolution_minutes']) > 0 ? escapeHtml(slaMinutesText($sla['sla_resolution_minutes'], $old_wording)) : 'No set time') . 'No set timeNo set time
'; } -/** What the placeholders become for a contract - lowercase name => value, raw. $as_of is the day it is sent ('Y-m-d'). */ -function contractPlaceholderValues(array $row, $as_of = null) { +/** What the placeholders become for a contract - lowercase name => value, raw. $as_of is the day it is sent ('Y-m-d'). $old_wording: see slaMinutesText(). */ +function contractPlaceholderValues(array $row, $as_of = null, $old_wording = false) { global $mysqli; $as_of = $as_of ?: date('Y-m-d'); $company = billingCompany(); @@ -161,7 +161,7 @@ function contractPlaceholderValues(array $row, $as_of = null) { $slas = []; foreach (contractSlaRows($row, $as_of) as $priority => $item) { if ($item['sla']) { - $slas[] = "$priority: " . strtolower(contractSlaTargets($item['sla'])); + $slas[] = "$priority: " . strtolower(contractSlaTargets($item['sla'], $old_wording)); } } return [ @@ -196,12 +196,12 @@ function contractPlaceholderValues(array $row, $as_of = null) { * becomes the table of response times, in a sentence the times in words. A * [word] with nothing to put in stays as it is. $html is already made safe. */ -function contractFillTerms($html, array $row, $as_of = null) { +function contractFillTerms($html, array $row, $as_of = null, $old_wording = false) { $space = '(?:\s| |\x{00A0})'; - $html = preg_replace_callback('/<(p|div|h[1-6])\b[^>]*>' . $space . '*\[SLA\]' . $space . '*<\/\1>/iu', function () use ($row, $as_of) { - return contractSlaTableHtml($row, $as_of); + $html = preg_replace_callback('/<(p|div|h[1-6])\b[^>]*>' . $space . '*\[SLA\]' . $space . '*<\/\1>/iu', function () use ($row, $as_of, $old_wording) { + return contractSlaTableHtml($row, $as_of, $old_wording); }, (string) $html); - return ticketPlaceholderFill($html, contractPlaceholderValues($row, $as_of), true); + return ticketPlaceholderFill($html, contractPlaceholderValues($row, $as_of, $old_wording), true); } /** The [words] left in filled-in terms - placeholders with nothing to put in, or words that aren't placeholders. */ @@ -212,12 +212,14 @@ function contractUnfilled($html) { /* * The contract as a document - as of $as_of, the day it is sent (today when * not given). Escaped here; its terms are purified HTML. Classes only, no - * styles: includes/contract_paper.php and the PDF dress it. + * styles: includes/contract_paper.php and the PDF dress it. $old_wording + * gives the response times as documents had them up to 26.11.7 + * (slaMinutesText()) - only contractDocumentIs() asks for that. */ -function contractDocumentHtml(array $row, $as_of = null) { +function contractDocumentHtml(array $row, $as_of = null, $old_wording = false) { $company = billingCompany(); $bill_to = billingBillTo(intval($row['contract_client_id'])); - $values = contractPlaceholderValues($row, $as_of); + $values = contractPlaceholderValues($row, $as_of, $old_wording); $e = function ($value) { return escapeHtml((string) $value); }; @@ -276,9 +278,9 @@ function contractDocumentHtml(array $row, $as_of = null) { $html .= ''; $html .= '

Response times

'; - $html .= contractSlaTableHtml($row, $as_of); + $html .= contractSlaTableHtml($row, $as_of, $old_wording); - $terms = trim((string) $row['contract_details']) !== '' ? contractFillTerms(documentHtmlPurify((string) $row['contract_details']), $row, $as_of) : ''; + $terms = trim((string) $row['contract_details']) !== '' ? contractFillTerms(documentHtmlPurify((string) $row['contract_details']), $row, $as_of, $old_wording) : ''; if (trim(strip_tags($terms, '')) !== '') { $html .= '

Terms

'; $html .= '
' . $terms . '
'; @@ -291,6 +293,20 @@ function contractDocumentHash($html) { return hash('sha256', (string) $html); } +/* + * Whether a contract still comes out as the document with fingerprint $hash, + * as of $as_of. A document sent up to 26.11.7 worded its response times in + * plain time ("2 days"); they are now in the SLA clock's business time ("6 + * business days"), so one that no longer matches is tried in the old wording + * too - the same contract reworded has not changed, and a copy signed or out + * for signature stays as it was sent. + */ +function contractDocumentIs(array $row, $as_of, $hash) { + $hash = (string) $hash; + return contractDocumentHash(contractDocumentHtml($row, $as_of)) === $hash + || contractDocumentHash(contractDocumentHtml($row, $as_of, true)) === $hash; +} + /* ---------------------------------------------------------------- rounds of signing */ /** The columns a round is read with, and the contract and client it belongs to. */ @@ -813,7 +829,7 @@ function contractSignatureCheckChanged(array $row) { return null; } $as_of = date('Y-m-d', strtotime((string) $round['contract_signature_sent_at'])); - if (contractDocumentHash(contractDocumentHtml($row, $as_of)) === (string) $round['contract_signature_document_hash']) { + if (contractDocumentIs($row, $as_of, $round['contract_signature_document_hash'])) { return null; } return contractSignatureWithdraw($round, 'The contract was changed after it was sent') ? $round : null; @@ -825,7 +841,7 @@ function contractSignatureOutdated(array $row, array $round) { return false; } $as_of = date('Y-m-d', strtotime((string) $round['contract_signature_sent_at'])); - return contractDocumentHash(contractDocumentHtml($row, $as_of)) !== (string) $round['contract_signature_document_hash']; + return !contractDocumentIs($row, $as_of, $round['contract_signature_document_hash']); } /** A contract as a PDF - the copy of a round ($round) when given, else the document as it is today. ['name', 'data']. */ diff --git a/functions/sla.php b/functions/sla.php index 3230820d7..6d5421839 100644 --- a/functions/sla.php +++ b/functions/sla.php @@ -565,7 +565,10 @@ function applyTicketSla($ticket_id, $forced_sla_id = null) // in the email, so the wording only has to give the right impression - a // remainder under five minutes is dropped rather than rendering the likes of // "1 business hour 1 minute". -function formatSlaMinutes($minutes) +// +// $exact drops nothing - "1 business day 7 hours 30 minutes" - for where the +// words stand alone: a contract's response times, and Admin > SLAs. +function formatSlaMinutes($minutes, $exact = false) { $minutes = intval($minutes); @@ -592,8 +595,8 @@ function formatSlaMinutes($minutes) $remainder = $minutes % 60; $text = $hours . ' ' . $qualifier . 'hour' . ($hours == 1 ? '' : 's'); - if ($remainder >= 5) { - $text .= ' ' . $remainder . ' minutes'; + if ($remainder >= 5 || ($exact && $remainder > 0)) { + $text .= ' ' . $remainder . ' minute' . ($remainder == 1 ? '' : 's'); } return $text; @@ -601,11 +604,15 @@ function formatSlaMinutes($minutes) $days = intdiv($minutes, $day_minutes); $hours = intdiv($minutes % $day_minutes, 60); + $remainder = $minutes % $day_minutes % 60; $text = $days . ' ' . $qualifier . 'day' . ($days == 1 ? '' : 's'); if ($hours > 0) { $text .= ' ' . $hours . ' hour' . ($hours == 1 ? '' : 's'); } + if ($exact && $remainder > 0) { + $text .= ' ' . $remainder . ' minute' . ($remainder == 1 ? '' : 's'); + } return $text; }