Skip to content

Reply Cleanup Prompt History Developer Guide

Ed Mozley edited this page Nov 19, 2026 · 1 revision

πŸ› οΈ Reply Cleanup prompt and its history - Developer Guide

(#396, 5.7.0, #3008.) For someone changing the Reply Cleanup prompt, its editor, or adding the same "editable with a history" to another AI prompt.

User side: Tickets - AI Reply Cleanup.

πŸšͺ Front door

Tickets β†’ Settings β†’ Reply Cleanup shows the system prompt in an editor. It is a template: {greeting_name} and {tone} are filled in on every cleanup. Every save is a new row in ticket_reply_cleanup_prompts, and the newest row is the one in use. Nothing ever updates or deletes a row - Reset and Restore add one too - so whatever somebody does to the prompt, the version before it is one Restore away.

That rule is the whole design. Ed, 19 November 2026: editable, "but can we allow versioning so if someone messes it up they can revert back to the previous version."

πŸ“ Files

File What it does
🟣 includes/reply_cleanup_prompt.php The built-in template, the builder, and the version functions
🟣 api/tickets/reply_cleanup_prompt.php GET the prompt and history, GET one version, POST save / reset / restore
🟣 api/tickets/ai_cleanup_reply.php Sends replyCleanupActiveTemplate($conn) to the builder
βšͺ api/tickets/get_reply_cleanup_settings.php Its preview follows the version in use
🟑 tickets/settings/index.php The editor, Save / Reset, History with View / Restore (rcPrompt* ids)
βšͺ includes/db_verify_schema.php, database/freeitsm.sql The table
βšͺ includes/analyst_lifecycle.php created_by is history, kept when an analyst leaves
βšͺ lang/*/tickets.php settings.reply_cleanup.*, help.ai.cleanup_prompt
🟒 tests/reply-cleanup-prompt-history.php 30 checks, endpoint over HTTP

🧱 The table

CREATE TABLE ticket_reply_cleanup_prompts (
    id               INT NOT NULL AUTO_INCREMENT,
    prompt_text      MEDIUMTEXT NULL,          -- NULL = the built-in default
    action           VARCHAR(20) NOT NULL,     -- 'edit', 'reset' or 'restore'
    restored_from    INT NULL,                 -- for a restore: the version it copied
    created_by       INT NULL,                 -- FK analysts, ON DELETE SET NULL
    created_datetime DATETIME NOT NULL,
    PRIMARY KEY (id)
);

Install-wide, like the rest of the Reply Cleanup settings in system_settings.

πŸ”‘ NULL means "the built-in prompt", not a copy of it

A Reset stores NULL, never the built-in text. And saving the built-in text unchanged as an "edit" is stored as NULL too:

if ($text === replyCleanupDefaultTemplate()) $text = null;

Why: a copy would freeze the install on today's built-in prompt. If a later release improves it, an install showing "built-in prompt" would still be sending the old copy. With NULL, "built-in" always means the current one.

🧩 The builder

$system = buildReplyCleanupSystemPrompt($greetingName, $toneDescription, $customInstructions,
                                        replyCleanupActiveTemplate($conn));
  • replyCleanupActiveTemplate() returns the newest row's text, or null for the built-in one - also when the table does not exist yet, so an install that has not run Database Verification keeps working.
  • The builder replaces REPLY_CLEANUP_PLACEHOLDERS ({greeting_name}, {tone}) and then appends the custom instructions under their own heading, as before. Custom instructions still always come after the prompt.
  • TRAP: the built-in template is a nowdoc (<<<'PROMPT'). It used to be a heredoc interpolating {$greetingName}; as a template it must not be interpolated. The refactor was checked byte for byte against the old builder: all three tones, with and without custom instructions, two names - identical.

The endpoint

Call Does
GET text (in use), is_default, default_text, placeholders, max, versions (newest first)
GET ?version=N That version's text (the built-in text for a NULL row); 404 if none
POST {action:'save', text} New version; 422 if empty or over 20,000 characters
POST {action:'reset'} New NULL version
POST {action:'restore', id} New version copying N, restored_from = N; 404 if none

Writes return changed: false and add nothing when the result is what is already in use. Gate: Tickets module + Cap::TICKETS_REPLY_CLEANUP, CSRF on POST - the same as the rest of the tab.

The screen

  • A save without {greeting_name} or {tone} asks first (it is allowed - somebody may not want a greeting).
  • TRAP: the tab used to reload itself when the tone changed, to refresh the read-only preview. With an editor that would throw away unsaved edits, so the listener is gone; the editor shows {tone}, not the tone's text.
  • History shows the newest first, marked In use; every other row has Restore.

Adding this to another prompt

Copy the shape, not the table: one table per prompt, newest row in use, NULL = built-in, every action an insert. Add the created_by column to analystReferenceRegistry().

Related: AI providers Β· Tickets settings - Developer Guide Β· Ticket AI reading - Developer Guide

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally