Redirects — Reference
The Redirects surface is the URL rewriting plane of the SGEN platform. It owns the redirect record, the distinction between permanent and temporary forms, the bulk import path for migrating from another platform, the regex pattern matcher for one-to-many redirects, and the simulator that lets an operator preview how a candidate URL would resolve before saving the rule.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or planning a migration cutover. 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
Redirects live under the Redirects module in SG-Admin, inside the SEO sub-tree. The module renders three primary views — the redirect list, the create / edit form (which doubles as the simulator), and the bulk import view — and exposes a small set of write operations for create, edit, soft delete, restore, and bulk import.
The redirect record is conceptually simple — a source pattern and a destination URL with a type flag — but several details matter at the platform level: the source can be a literal path or a regex pattern; the type flag controls whether the redirect is permanent (search engines drop the source) or temporary (search engines keep the source); the matcher resolves in a defined order so that more-specific rules win over wildcards.
The simulator is integrated into the create / edit form. Operators paste a candidate visitor URL into the simulator field and the platform shows which redirect rule (if any) would match, where it would send the visitor, and whether any subsequent rule would chain. The simulator is read-only — it does not write or save.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → SEO → Redirects
- URL prefix:
/sg-admin/redirects/ - View templates:
application/views/Admin/Redirects/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → SEO → Redirects [+ New redirect] │├──────────────────────────────────────────────────────────────────────┤│ Source Destination Type Hits State ││ ────────────────────── ────────────────── ────── ───── ─────────││ /old-pricing /pricing 301 1,420 Active ││ /blog/2024/(.+) /blog/$1 301 8,891 Active ││ /promo-summer-2025 / 302 317 Active ││ /shop /products 301 24,005 Active ││ /docs/old-section/* /docs/section/* 301 44 Active ││ /experimental / 302 — Disabled ││ ││ Type filter: [All ▼] [Bulk import] [Export] │└──────────────────────────────────────────────────────────────────────┘Actions
The Redirects surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List and search
Returns the redirect records visible to the current operator, paginated, with source, destination, type, hit-count, and state columns. Supports column sort, free-text filter (matches source or destination), type filter, state filter, and per-page count. Driven by the data-table contract used across SG-Admin modules.
Create redirect
Opens the create / edit form in empty state. Required at minimum: source, destination, type (permanent or temporary). Optional fields cover the regex flag, query-string handling mode, and an operator note. The form runs three validations before persist:
- Loop detection — rejects a rule that would create a redirect loop (source → destination where destination matches an existing rule's source pointing back).
- Conflict detection — flags a rule whose source already matches an active rule. The operator chooses to override (the new rule wins by priority) or cancel.
- Self-redirect detection — rejects source == destination.
Edit redirect
Loads an existing record into the same form shape used for create. Edits to source, destination, type, or the regex flag re-run the three validations above. Edits to the operator note and the state toggle bypass validation.
Toggle active state
Moves the redirect between active and disabled. Disabled redirects remain in the database and visible in the list view but do not participate in the matcher. Used to quickly suspend a rule during migration debugging without losing the rule definition.
Bulk import
Loads the bulk import view. Operators paste or upload a flat list of source-destination-type rows (CSV format) or an export from another platform (the import recognizes the common export shapes for the two most-common upstream platforms). The import runs row-by-row validation, presents a preview with accepted + rejected rows broken out, and only persists on operator confirmation.
Engineering note: bulk import is the highest-risk path on this surface — a 5,000-row import with one regex error can cascade. The import always dry-runs first; it never writes without the explicit confirmation step.
Simulator
The simulator field on the create / edit form accepts a candidate URL and shows the resolution trace — which rule (if any) matched, the matcher's reasoning (literal vs regex, which capture groups bound), the destination it would produce, and whether the destination itself would chain into another redirect. Read-only — the simulator never writes.
Regex pattern authoring
Source patterns can be marked as regex. The regex form supports capture groups in the source and $1-style backreferences in the destination. The form provides a regex syntax helper, a list of commonly-used patterns (e.g., /old-path/(.+) → /new-path/$1), and the simulator catches obvious mistakes (unbalanced parens, no possible match) before save.
Engineering note: regex patterns are evaluated AFTER all literal patterns. A literal path always wins over a wildcard. Within the regex set, evaluation order is bypriority(descending) thencreated_at(ascending).
Export
Generates a flat-file export of the current redirect set. Supported formats: CSV (suitable for re-import into this platform or another), JSON, and a server-config snippet (suitable for a reverse proxy as a temporary measure during migration).
Soft delete
Marks the record archived without removing it from the database. Soft-deleted redirects leave the matcher and the default list view but remain queryable via the archive filter. Hit-count history is preserved for retroactive reporting.
Restore
Reverses a soft delete. The record returns to the active list in disabled state — never auto-enabled, to prevent surprise reactivation of a rule that may now conflict with newer rules.
Permanent delete
Hard-removes the record. Available only after a soft delete. Hit-count history is detached. This path is irreversible.
Data model
A redirect 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. |
source | string | Literal path or regex pattern (depending on is_regex flag). |
is_regex | boolean | Marks source as a regex pattern. |
destination | string | Target URL — absolute or relative. May contain $1-style backreferences. |
type | enum | permanent (301) or temporary (302). |
query_handling | enum | pass_through, strip, replace. How query strings are handled. |
state | enum | active, disabled, archived. |
priority | integer | Tie-breaker when multiple rules match the same URL. |
hit_count | integer | Cumulative match count since last reset. |
last_hit_at | timestamp | Timestamp of the most recent match. |
note | text | Optional operator note. Visible only in admin. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
state = archived is the soft-deleted state. Soft-deleted redirects leave the matcher and retain all other fields. Permanent delete removes the row entirely.Type-flag semantics: the type field maps to the platform's response on a match — permanent emits the "moved permanently" response (search engines drop the source); temporary emits the "found, redirecting" response (search engines keep the source). The default is permanent — operators creating a redirect during migration should leave the default.
Match-order resolution: for a given incoming URL, the matcher evaluates in this order — literal-path rules (sorted by priority desc, then created_at asc), then regex rules (sorted by priority desc, then created_at asc). The first match wins. Chained redirects (the destination of a match is itself a source of another rule) are followed up to a configurable hop limit (default 3) before the matcher gives up and serves a structured error page.
INCOMING REQUEST│▼┌──────────────────────────────────────┐│ Match against LITERAL rules first ││ (sorted: priority desc, then ││ created_at asc) │└─────────────┬────────────────────────┘│┌─────┴──────┐│ match? │▼ ▼YES NO│ ││ ▼│ ┌──────────────────────────┐│ │ Match against REGEX rules ││ │ (same sort order) ││ └─────────────┬────────────┘│ ││ ┌─────┴──────┐│ ▼ ▼│ YES NO│ │ ││ │ ▼│ │ pass through│ │ (no redirect)▼ ▼Build destination URL(regex backrefs expanded)│▼Check chain depth ≤ 3│▼Emit response with `type` (301 or 302)│▼Increment hit_count + last_hit_atPermissions
Access to the Redirects 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 Redirects surface.
Layer 2 — per-action capability. Within SG-Admin, each Redirects action checks a capability associated with the calling operator's role. The default role configuration uses the platform's base roles augmented with an SEO Operator role. The capability map is:
| Capability | Administrator | SEO Operator | Editor | Viewer |
|---|---|---|---|---|
| List redirects | ✔ | ✔ | ✔ | ✔ |
| View detail / simulator | ✔ | ✔ | ✔ | ✔ |
| Create redirect | ✔ | ✔ | — | — |
| Edit redirect | ✔ | ✔ | — | — |
| Toggle active / disabled | ✔ | ✔ | — | — |
| Bulk import | ✔ | ✔ | — | — |
| Export | ✔ | ✔ | ✔ | ✔ |
| Soft delete | ✔ | ✔ | — | — |
| Restore | ✔ | ✔ | — | — |
| Permanent delete | ✔ | — | — | — |
| Reset hit-count statistics | ✔ | ✔ | — | — |
Self-protection rules. Loop-forming rules are rejected at create + edit time (validated against the entire active rule set). Self-redirect rules (source == destination) are rejected. Bulk import operations require explicit confirmation after the dry-run step. Permanent delete of a rule with non-zero hit-count emits an extra confirmation prompt.
Audit. Every write — create, edit, state change, bulk import, soft delete, restore, permanent delete — emits an Activity Log entry. Bulk imports emit one entry plus a row-level summary attachment. The log records the acting operator, the target rule (or rule set), and the change shape. Activity Log retention is governed by the site's general settings.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Loop + conflict + self │ rule would form│ guards (write paths only) │ loop / self-redirect → reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry(bulk import: + row summary)Related references
- Pages — Reference. Pages whose slug changes leave behind the old URL; the platform offers (but does not auto-create) a redirect from the prior slug. Operators who rename a page slug should create a matching redirect.
- Products — Reference. Same — products whose slug changes leave behind the old URL.
- SEO — Reference. Global SEO defaults shape canonical URL behavior. Canonical URLs and redirects can disagree — the SEO reference documents the resolution order.
- Settings — Reference. Owns the redirect chain hop limit, the default type flag, and the structured error page that serves when the matcher gives up.
- Sitemap — Reference. Sitemap entries respect the redirect set — soft-deleted pages still in the sitemap will resolve via redirect if a rule exists.
- Custom Codes — Reference. Operators with deeper rewriting needs (header-based routing, geo-based routing) can layer additional rules through the platform's template surfaces; the Redirects surface covers URL-level rules only.
/docs/redirects.