Reviews — Reference
The Reviews surface is the moderation and aggregation plane for visitor-submitted ratings and written feedback attached to SGEN content — products, blog posts, knowledge-base entries, or any other record type a site chooses to open for review. It owns the captured submissions, the moderation queue, the operator reply thread, the spam disposition, and the aggregate rating that downstream surfaces (product detail pages, listing pages, structured-data exports) read from.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or wiring a moderation workflow. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Reviews live under the Reviews module in SG-Admin. The module renders three primary views — the all-reviews list, the per-record review thread, and the moderation queue — and exposes write operations for approve, hide, mark spam, reply, edit operator reply, and permanent delete.
The module is paired by convention: one half renders the views and prepares the data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
Reviews attach to a parent record by record-type and record-id. The same module surface serves every record type that opts in — by default product pages, blog posts, and knowledge-base entries. Sites that add custom record types register them through Settings and inherit the review surface automatically.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Reviews
- URL prefix:
/sg-admin/reviews/ - View templates:
application/views/Admin/Reviews/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Reviews → Moderation queue │├──────────────────────────────────────────────────────────────────────┤│ Filter: [Pending ▾] Record type: [All ▾] Rating: [All ▾] │├──────────────────────────────────────────────────────────────────────┤│ Submitted Record Rating Author State ││ ─────────────── ────────────────── ────── ─────────── ───── ││ 2 min ago SG-Core (product) ★★★★★ Maria R. Pending││ 18 min ago Onboarding (article) ★★★ anonymous Pending││ 43 min ago SG-Modules (product) ★ bot.host Spam? ││ 1 hour ago Pricing (article) ★★★★ James C. Pending││ ││ [⋯ Approve] [⋯ Hide] [⋯ Mark spam] [⋯ Reply] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘Actions
The Reviews surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List and filter
Returns the submitted reviews visible to the current operator, paginated, with submitted-at, parent record, rating, author, state, and excerpt columns. Supports column sort and filter on state (pending, approved, hidden, spam), record type, rating value, and author identity (registered operator vs anonymous visitor). Driven by the data-table contract used across SG-Admin modules.
Open the moderation queue
A filtered view restricted to submissions in the pending or flagged-as-spam states. The queue is the default landing view for operators whose role is scoped to moderation only; it surfaces the work that requires a decision and hides the already-decided history.
Open a review thread
Expands a single submission and shows the original review body, the rating, the author identity (if any), the captured submission context, and the operator reply thread. Replies appear inline below the original submission in chronological order.
Approve
Moves a pending submission to the approved state. Approved reviews appear on the public surface of their parent record and contribute to the aggregate rating shown on listings and on structured-data outputs.
Hide
Moves an approved submission out of public view without deleting it. Hidden reviews remain in the moderation history and continue to be visible to operators; they do not contribute to the aggregate rating and do not appear on the live site.
Mark spam
Tags a submission as spam. Spam submissions are excluded from the public surface, excluded from the aggregate rating, and surfaced under the spam filter in the moderation queue. The platform's spam classifier may pre-flag submissions; operator confirmation moves them to the terminal spam state.
Reply
Attaches an operator-authored reply to the submission. The reply carries the operator identity, a timestamp, and a body. Replies are publicly visible alongside the parent review on the live site, presented as the platform's response.
Edit operator reply
Replaces the body of an existing operator reply with the posted values. The edit history is retained internally — the reply record carries created_at and a separate updated_at — but the live surface shows only the most recent body.
Permanent delete
Hard-removes the submission and its associated reply thread. Available to administrators only. Use sparingly — once removed, the submission is gone, the aggregate is recomputed, and any external reference to the review (for example, a structured-data snapshot served from cache) no longer resolves.
Data model
A review record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
record_type | string | Slug of the parent record type (for example product, post, kb-article). |
record_id | integer | Identifier of the parent record. Resolves through the relevant record-type surface. |
author_type | enum | registered (the submitter was an authenticated visitor or operator) or anonymous. |
author_id | integer | Optional. Populated when author_type = registered. |
author_name | string | Captured display name. Required for anonymous submissions. |
rating | integer | One through five. Required. |
body | text | The written review. Optional — a rating-only submission is permitted. |
state | enum | pending, approved, hidden, spam. |
submission_context | structured | Captured at submission — visitor identifier, source URL, locale. |
created_at | timestamp | Set on submission, immutable. |
updated_at | timestamp | Touched on state change. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
review_id | integer | Foreign key to the parent review. |
operator_id | integer | The replying operator. Required. |
body | text | The reply body. |
created_at | timestamp | Set on send, immutable. |
updated_at | timestamp | Touched on edit. |
Author semantics: registered authors are resolved through the Users surface or the visitor-account surface at display time, so a renamed account shows its current name on past reviews. Anonymous authors carry only the captured name field — they cannot be retroactively edited from the operator side.
PARENT RECORD (product / post / article)││ 1 ── *▼REVIEW├── rating integer 1-5├── body text (optional)├── author registered | anonymous├── state pending | approved | hidden | spam└── submission_ctx visitor + url + locale││ 1 ── *▼REPLY (operator-authored)├── operator_id required├── body text└── timestamps created / updatedAGGREGATE RATINGderived from approved reviews onlyrecomputed on every state changeinvalidates downstream cachesPermissions
Access to the Reviews surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Reviews surface. Visitor-submitted reviews enter through a separate visitor-facing endpoint that is not gated by the admin check.
Layer 2 — per-action capability. Within SG-Admin, each Reviews action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List reviews | ✔ | ✔ | ✔ |
| Open moderation queue | ✔ | ✔ | — |
| Approve | ✔ | ✔ | — |
| Hide | ✔ | ✔ | — |
| Mark spam | ✔ | ✔ | — |
| Reply | ✔ | ✔ | — |
| Edit own reply | ✔ | ✔ | — |
| Edit another operator's reply | ✔ | — | — |
| Permanent delete | ✔ | — | — |
Self-protection rules. An operator cannot edit a reply attributed to a deleted operator account (the reply is preserved but read-only). An operator cannot delete a review thread that contains a reply authored by another active operator unless they hold the administrator role.
Audit. Every write — state transition, reply send, reply edit, permanent delete — emits an Activity Log entry. The log records the acting operator, the target review identifier, and the change shape. Activity Log retention is governed by the site's general settings.
SUBMITTED ──pending──▶ MODERATION QUEUE│┌────────────┼────────────┐▼ ▼ ▼approve hide mark spam│ │ │▼ ▼ ▼APPROVED HIDDEN SPAM(public) (internal) (filtered)│└─▶ contributes to aggregate ratingany state ──permanent-delete──▶ REMOVED(administrators only,aggregate recomputed)Related references
- Settings — Reference. Owns the role definitions, the spam classifier configuration, the registered record-type list, and the aggregate-rating cache window.
- Users — Reference. Operator identifiers on replies and on registered-author reviews resolve through the Users surface.
- Pages — Reference. Pages that surface product or article content read the aggregate rating from this surface and render it in their template.
- Posts — Reference. Blog posts opt into reviews on a per-record basis; the post record carries a flag that controls whether the visitor-facing submission form renders.
- Logs — Reference. Spam classifier decisions and reply send actions surface on the appropriate channels for operator investigation.
- Tools — Reference. The Activity Log search surface lives under Tools and is the canonical place to investigate "who changed this review's state and when."
/docs/reviews.