From e12ab543e81dee10930d21aed5d578c1d98eff04 Mon Sep 17 00:00:00 2001 From: Mark Gregory Date: Tue, 23 Jun 2026 10:53:20 +0100 Subject: [PATCH] closure updates --- Modules/Helpdesk/README.md | 169 ++++++++++++++++++++++++++++++++ Modules/Helpdesk/changelog.yaml | 10 ++ Modules/Helpdesk/module.json | 2 +- 3 files changed, 180 insertions(+), 1 deletion(-) create mode 100644 Modules/Helpdesk/README.md diff --git a/Modules/Helpdesk/README.md b/Modules/Helpdesk/README.md new file mode 100644 index 00000000..6eea33ec --- /dev/null +++ b/Modules/Helpdesk/README.md @@ -0,0 +1,169 @@ +# Helpdesk Module + +Professional Livewire-first Helpdesk module for ticket management, public/internal responses, SLA tracking, time logging, audit history, and operational support workflows. + +## Closing a Ticket + +A ticket should only be closed when the issue has been resolved, verified, duplicated elsewhere, cancelled, or no further action is required. + +The recommended closure workflow is: + +1. Open the ticket detail page. +2. Review the latest public and internal responses. +3. Confirm the ticket can be closed. +4. Add a closure comment explaining why the ticket is being closed. +5. Set the ticket status to `Closed`. +6. Save the change. +7. Confirm the closure appears in the conversation or audit trail. + +## Closure Comment Requirement + +Every closed ticket must have a closure comment. The comment should explain the reason for closure clearly enough that another agent, manager, auditor, or customer can understand the decision later. + +A good closure comment should include: + +- What was resolved or confirmed. +- Any action that was taken. +- Whether the customer/user needs to do anything else. +- Whether the ticket can be reopened if the issue returns. + +Example closure comment: + +```text +Issue resolved and verified. + +The requested work has been completed and no further action is currently required. This ticket is now being closed. + +If the issue reoccurs or additional information becomes available, please reopen the ticket or create a new support request referencing this ticket number. +``` + +## Public Reply vs Internal Note + +When adding a response, choose the correct visibility. + +### Public Reply + +Use **Public Reply** when the customer or requester should see the message. + +Public replies are used for: + +- First-response SLA tracking. +- Customer-visible updates. +- Resolution explanations. +- Closure comments that the requester should see. + +### Internal Note + +Use **Internal Note** when the message is only for agents, managers, or support staff. + +Internal notes are used for: + +- Investigation notes. +- Technical diagnostics. +- Private handover comments. +- Internal escalation context. + +Internal notes should not count as a customer response or first-response SLA event. + +## Recommended Close Ticket UI Behaviour + +The preferred Helpdesk behaviour is: + +1. Agent clicks **Close Ticket**. +2. A close panel or modal opens. +3. The agent must enter a closure comment. +4. The agent chooses **Public Reply** or **Internal Note**. +5. The system validates the comment. +6. The system saves the response. +7. The ticket status changes to `Closed`. +8. The activity/audit trail records the status change and closure reason. + +Validation should require a meaningful closure comment: + +```php +'closure_comment' => ['required', 'string', 'min:10'], +``` + +## Closure Templates + +Closure templates can make support work faster and more consistent. Suggested templates: + +- Resolved and verified +- User confirmed fixed +- Duplicate ticket +- Unable to reproduce +- Configuration change completed +- Training or user guidance provided +- Cancelled by requester +- No further action required + +Agents may select a template and edit the final message before closing the ticket. + +## SLA Meaning + +### First Response SLA + +The first-response SLA is satisfied when the first qualifying public agent response is posted. + +Typical states: + +| State | Meaning | +| --- | --- | +| Awaiting public reply | No qualifying public agent response has been posted yet. | +| Due soon | The first-response target is close to its deadline. | +| SLA met | The first public response was posted on time. | +| Responded late | The first public response was posted after the SLA deadline. | +| Breached | The SLA deadline passed without a qualifying public response. | + +### Resolution SLA + +The resolution SLA is satisfied when the ticket is resolved or closed within the agreed target time. + +Typical states: + +| State | Meaning | +| --- | --- | +| Awaiting resolution | The ticket has not yet been resolved or closed. | +| Due soon | The resolution target is close to its deadline. | +| SLA met | The ticket was resolved or closed on time. | +| Breached | The resolution deadline was missed. | + +## Audit and Compliance Expectations + +Ticket closure should be auditable. The system should preserve: + +- Previous status. +- New status. +- User who closed the ticket. +- Closure timestamp. +- Closure comment. +- Visibility of the closure comment. +- SLA state at the time of closure. + +Do not delete historical responses or SLA records when a ticket is closed. + +## Reopening a Ticket + +If a closed ticket needs further work: + +1. Open the closed ticket. +2. Click **Reopen** or change the status back to `Open` / `In Progress`. +3. Add a reopen reason. +4. Save the change. +5. Continue the conversation using public replies or internal notes as appropriate. + +The reopen reason should be stored in the ticket activity/audit trail. + +## Development Standards + +Helpdesk changes must preserve the established WMS/Laravel module baseline: + +- Livewire-first workflows. +- Module files remain under the existing `Modules/Helpdesk` structure. +- Livewire components remain under `Modules/Helpdesk/Livewire`. +- No unused JavaScript files. +- No duplicate Blade paths such as `Resources/views/views`. +- No `.DS_Store`, `__MACOSX`, or generated rubbish files in deliverables. +- `changelog.yaml` must be append-only. +- `module.json` version must match the latest `changelog.yaml` version. +- Tests must be added or updated for workflow changes. diff --git a/Modules/Helpdesk/changelog.yaml b/Modules/Helpdesk/changelog.yaml index f487bc59..be19972f 100644 --- a/Modules/Helpdesk/changelog.yaml +++ b/Modules/Helpdesk/changelog.yaml @@ -72,3 +72,13 @@ - Added a compact SLA audit trail showing recorded SLA events, due times, breach/met state, and actor details where available. - Updated public reply counting to include threaded public replies as well as root comments. - Preserved append-only changelog history. + +- version: 1.9.37 + date: 2026-06-23 + type: documentation + summary: Add Helpdesk module README instructions for closing tickets and SLA response handling. + changes: + - Added a base module README documenting how to close tickets with a mandatory closure comment. + - Documented Public Reply versus Internal Note usage for responses and SLA handling. + - Documented recommended close-ticket UI behaviour, closure templates, SLA meanings, audit expectations, reopening guidance, and Helpdesk development standards. + - Preserved append-only changelog history. diff --git a/Modules/Helpdesk/module.json b/Modules/Helpdesk/module.json index 790dc941..c83390ce 100644 --- a/Modules/Helpdesk/module.json +++ b/Modules/Helpdesk/module.json @@ -22,5 +22,5 @@ "Modules\\Helpdesk\\Providers\\HelpdeskServiceProvider" ], "files": [], - "version": "1.9.36" + "version": "1.9.37" }