Skip to content

Catalogue Answer Edits Developer Guide

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

Approvers change a request's answers - Developer Guide

Discussion #298, asked for by @Shadowtech87 · 5.8.0 · user guide: Catalogue request approvals → Changing the answers

In plain words

While a catalogue request waits for approval, the people who can decide it can now change its answers - correct a site, fill in the username, move a start date - and every change is recorded: which answer, the old and new value, who, when and an optional reason. The requester sees what changed on their portal, and the ticket raised on approval uses the corrected answers and lists the changes.

Decided (20 November 2026, Ed): working the username out automatically was suggested first and turned down - "a road to nowhere as that is a symptom of a deeper problem. Any other fields could have problems. The proper solution is to let the approver make edits but there to be an audit trail."

The files

File What
🟣 includes/catalogue_approvals.php catalogueCanEditAnswers(), catalogueEditableFields(), catalogueEditAnswers(), catalogueAnswerChanges(), CATALOGUE_EDITABLE_TYPES; can_edit / edit_fields in catalogueApprovalsList(); the change list in catalogueSubmissionBodyHtml()
🟣 includes/services/forms.php FormsService::checkPlainAnswer() - the plain-answer rules, lifted out of submitForm() so the edit uses the very same ones
🔌 api/forms/edit_submission_answers.php POST { submission_id, answers: { fieldId: value }, reason? }
🔌 api/self-service/get_dashboard.php changes[] on each of Your requests - no reason
🟡 forms/approvals.php Edit on a waiting card, the inline panel, the change lines
🟡 self-service/index.php the folded Answers changed after you sent it (n) under a request
📄 forms/help/approvals.php Changing the answers before you decide
🌐 lang/*/forms.php, lang/*/self-service.php forms.approval.edit* / changed_* (13), self-service.dashboard.req_changed* (3), 9 languages
🧪 tests/catalogue-answer-edits.php 26 checks, against a throwaway install

No schema change. The audit trail is the existing form_submission_approval_events table (added for team approvals' overrides and moves) with a new action, 'answer_changed', and the answers stay in form_submission_data.

Who may edit

function catalogueCanEditAnswers(PDO $conn, int $analystId, array $sub): bool {
    if (($sub['approval_status'] ?? '') !== 'pending' || $analystId <= 0) return false;
    if (catalogueAnalystIsRequester($conn, $analystId, $sub)) return false;      // never your own
    if (function_exists('sessionIsAdmin') && sessionIsAdmin()) return true;
    $policy = catalogueApprovalPolicy($sub);
    if ($policy['mode'] === 'team') return in_array($analystId, catalogueEligibleMembers($conn, $sub), true);
    return $policy['approver_id'] === $analystId;
}

The people who could decide it - and never the requester, even where they could approve (the cannot approve their own switch is off by default; editing your own request is never allowed). Only while it is pending: catalogueLockSubmission() (SELECT … FOR UPDATE) refuses anything else, so an edit racing an approval loses cleanly.

The edit

// catalogueEditAnswers() - one transaction; any refusal rolls back every change in the call
$sub = catalogueLockSubmission($conn, $submissionId);
foreach ($answers as $fid => $value) {
    // stored exactly as submitForm() stores it: bool -> '1'/'0', array -> json_encode(array_values())
    FormsService::checkPlainAnswer($field, $value);        // required, email, number, date shape, choices
    if ($old === $value) continue;                         // unchanged: no row, no event
    // UPDATE (or INSERT, for a question never answered) form_submission_data
    catalogueApprovalEvent($conn, $submissionId, $actorId, 'answer_changed',
        json_encode(['field_id', 'label', 'old', 'new', 'old_raw', 'new_raw']), $reason);
}
  • The same rules as a submission. checkPlainAnswer() is the block that used to sit inside submitForm()'s loop, moved into a function both call - submitForm()'s behaviour is unchanged (the Forms suites - logic, lookups, drafts, audiences, grids, webhooks, team approvals - pass before and after). An edit can never be held to looser rules than the request was.
  • Atomic. {Username: 'jsmith2', Site: 'East'} with East not on the list changes neither.
  • Editable types: text, multi-line text, email, number, date/time, dropdown, radio, one tick, several ticks (CATALOGUE_EDITABLE_TYPES). A lookup keeps its answer (it is checked against the submitter's own scope, which an approver does not share) and so does a table; both are listed, marked cannot be changed here.
  • Questions the requester left empty are listed and can be filled - the "AD username" case.
  • old / new are the readable text (catalogueAnswerText(): Yes / No, VPN, Email); old_raw / new_raw the stored form, kept so a change could be reversed.

Where the changes show

Who Where What
Approvers the request's card in Forms → Approvals Administrator changed Site: North → South · 20 Nov 2026 21:41 · Checked AD for clashes
The desk the body of the ticket raised on approval Changed during approval, one line each, with the reason
The requester portal → Your requests Answers changed after you sent it (3), folded; field, old, new, when - no reason (it may be an internal note)

The ticket and any on approval workflow read form_submission_data at decision time, so they get the corrected answers with nothing extra to do.

The screen

toggleEdit(id) builds the panel from the card's edit_fields (catalogueEditableFields() - every answerable question, with its current stored value, choices and date mode). editedValue() compares each control with the stored value and only changed answers are sent; nothing changed → Nothing was changed. and no request.

Checked

  • tests/catalogue-answer-edits.php: 26 checks - who may and may not (someone else, the requester even as approver, a non-member; a team member and an administrator may), each change an event with old/new/who/reason, an unchanged answer records nothing, every rule refused, the refused-edit-keeps-nothing case, a table refused, a foreign question refused, the inbox flags and locked table, the ticket body, decided requests locked, cleanup.
  • On the test install, headless, in the real inbox: Edit beside Approve / Reject / Move; the panel with all five questions; AD username, Site and Access changed with a reason; the card's answers and three change lines updated. The portal's Your requests, as the requester, folded the three changes with no reason.
  • Not covered: a request that is decided through the REST API is unaffected; there is no REST endpoint for editing answers yet.

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally