Skip to content

Catalogue Card PR Review

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

The catalogue card: a picture, a short description and a price - PR review

PR #349 by vsc55 Β· Slice 1 of #348 Β· Design: Catalogue as a shop Β· Verdict: merge, with fixes Β· 5.4.0

The first of four slices of the catalogue as a shop. A catalogue item can have a picture, a one-line description and a price (one-off or a month, in the install's currency unless changed), set in a new Catalogue tab of the form editor beside Fields, Preview and What happens next, with the card drawn live as the portal will show it and saved by the form's own Save. Each portal request keeps the price it was made at. An item people just request - a mouse at a price - may ask no questions. Your requests on the portal lists every catalogue request, not only those awaiting approval, and the requester can cancel one still waiting for approval, giving a reason the approver sees. User pages: Portal Request Catalogue and Catalogue Request Approvals. Internals: Catalogue approvals - Developer Guide Β§9.

vsc55 wrote the design on #348 and asked two questions before building past the first slice. An item with no card is exactly as it was, and nothing runs before Database Verification adds the columns - the two things that usually go wrong with a new per-form setting did not.

What was checked

Question Result
Does an existing item change? No. Every new column is NULL by default, and NULL is the card as before - title and description. catalogueCardAvailable() is the one check; before Database Verification every item saves, versions and submits as 5.3.0 did, and the tab says verification is needed
Does saving the title clear a price? No - catalogueCardFromInput() touches only the keys sent, so the REST API or an older page saving a form never clears the card
Does a new version keep the card? Yes - catalogueCardCopy() runs in createVersion(). That copy is the trap every per-form setting has: one left out is one Save deletes (it is how approval gating was once lost)
Is the picture served by path? No. api/forms/card_image.php takes a form id, reads the path from the row and checks it again before a byte is read: its shape (<formId>/<32 hex>.<ext>), an extension from our whitelist, and that it was uploaded for this form or an earlier version of it (catalogueImageBelongs()). The upload is upload_image.php, the image-block rules: no SVG, 4 MB
Who sees the picture? A portal user only for an item in their catalogue - visible, active, the current version, in its audience - with the gate in the query; an analyst only with the Forms module. Anything else is the same 404
Does the portal leak the stored path? No - get_catalogue.php sends only what the card shows, and no longer echoes exception text
A later price change Rewrites no request. form_submissions.catalogue_* is a snapshot taken at submit time; a blank currency on the item is fixed to the install's currency on the request, so a later change of the install currency cannot turn last year's Β£40 into €40
An item with no questions Saved once it has a price, a picture or a short description; any other form still needs a question. The portal shows no Save draft for it, and its ticket has no empty answer table
A cancel and an approval at the same moment Cannot both win: the cancel locks the row FOR UPDATE, as a decision does, and the second finds it no longer pending
Cancelling somebody else's request Not found, never not yours. POST only, CSRF checked, no exception text
When may a requester cancel? As submitted, a request waiting for approval or sent with no approval and no ticket. Changed on merge to awaiting approval only (decided below)
Is the approver told about a cancel? Not as submitted. Built on merge (fix 2)
The REST API GET /forms did not return the card and the writable keys were not documented. Fixed (fix 5)

On the test install: vsc55's tests/catalogue-card.php - an item with no card unchanged, every check on what is sent, versions, the price snapshot, labels, the inbox and the ticket body, an item with no questions saved, requested, approved and ticketed, no approval no ticket, cancelling by the requester only - extended on merge from 46 to 71 checks with the event and its payload, the refusals, the REST serializer, and over HTTP card_image.php (a portal user outside the audience, an analyst without Forms and nobody signed in all get 404) and get_catalogue never carrying the stored path. vsc55 also ran catalogue-group-approvals, form-audiences, forms-lookup-portal-submit, form-webhook-full-record, get-must-not-write, module-access-coverage and security-report-2026-10, all unchanged and passing, and looked at the editor tab, the forms list, the portal cards and the cancel dialog in a browser.

A real gap found on the way, by vsc55, fixed in the PR: a request with no approval disappeared. Your requests listed only requests that carried an approval state, so a catalogue request with no approval was saved and then shown nowhere - while the portal had told the person "the IT team has received your request". It now lists every catalogue request, Sent for one with no approval.

What was changed on merge

  1. Cancel only while a request waits for approval (decided below). A request sent with no approval is still listed on Your requests as Sent, with no Cancel, and the server refuses it with its own message - as it does a decided one (This request has already been decided...).
  2. A cancel fires catalogue_request.cancelled, after the cancel commits (catalogueAfterCancel()), carrying the form, the request id, the reason as request.reason (and as request.comment, so a template written for .rejected reads it too), the answers, and who was to approve it (approver.id / approval_team.id). Registered in WorkflowEngine::availableTriggers() with its fields and described in the Workflows triggers help - a dispatch() with no catalogue entry is an event nobody can hear, the fault the first three catalogue events shipped with.
  3. Create a ticket refuses a cancelled request, with its own message, so a rule on the new event can never raise the ticket the requester withdrew.
  4. Your requests leaves out forms filled in inside a task as well as on a ticket, using the cached TaskForms::columnsReady() / TicketForms::columnsReady() checks instead of an information_schema query on every dashboard load.
  5. REST: GET /forms and /forms/{id} return the card - catalogue_summary, catalogue_price, catalogue_currency, catalogue_price_period, catalogue_has_image - never the stored path. The four writable keys are documented in spec.json and the Form / FormSummary schemas; catalogue_image_path is ignored on writes (apiFormsWritableBody()), as the API has no upload.
  6. One-word buttons in the cancel dialog: Keep and Cancel.
  7. form-pdf.js?v=4 on the two pages that load it - the file learnt the Cancelled status and a cached copy would not have.
  8. service_context.php loaded in includes/catalogue_card.php and cancel_request.php, which throw ServiceError; a stray docblock put back on loadFormRow().
  9. Tests: tests/catalogue-card.php 46 -> 71 checks, as above.
  10. Changelog ids #2944 (the feature) and #2945 (the merge fixes); this write-up, the user pages, the developer guide section, a Forms help topic (A catalogue item's card), a Feature Bingo card (forms.catalogue_card) and vsc55's entry on the Contributors page.

Merged with git merge --no-ff under the contributor's name; the fixes are in the merge commit (ce998062a).

Decided

The design and the decisions are on Catalogue as a shop - design. Ed's answers on #348, 15 November 2026:

  • Yes to the design and all four slices - the card (this PR), the manager as approver, the item's responsible team, the cost centre - one PR each.
  • The manager approves in the portal, with an email link as well (vsc55's suggestion). Slice 2.
  • The cost centre goes in now, as slice 4. Reporting and charging stay with #160.
  • Cancel only while a request is awaiting approval, and a cancel fires a catalogue_request.cancelled workflow event with the reason, so the approver can be told. Old sent requests - often handled long ago by email or a webhook - stay listed but without Cancel; once approved there is a ticket, and the ticket is where to say so. Both made on merge.

Worth knowing

  • Nothing to do before Database Verification, and nothing breaks without it. The columns are forms.catalogue_summary / catalogue_price / catalogue_currency / catalogue_price_period / catalogue_image_path and form_submissions.catalogue_price / catalogue_currency / catalogue_price_period. A cancelled request uses the existing approval_status (cancelled), approval_comment (the reason) and approval_decided_datetime; approval_decided_by_id stays NULL, because it names an analyst.
  • A cancelled request is never deleted. It leaves the approvers' inbox, can no longer be decided, and shows as Cancelled by the requester in Forms -> Submissions and its PDF.
  • Tickets are unchanged. A ticket is raised only when a request is approved; with no approval there is none, as before.
  • The price is shown, not charged. It appears on the card, in Forms -> Approvals, on Your requests and in the ticket an approval raises (a Price line under "Submitted via"). Reporting and charging are #160.
  • Telling the approver is a workflow, not a notification. No email goes out on a cancel unless a rule on catalogue_request.cancelled sends one - see Workflows.
  • Next: slice 2, the requester's manager as approver (portal To approve list and email link, the fallback approver, the rejection notice) - see the design's slices.

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally