Exports — Reference
The Exports surface is the platform's data-egress plane. It owns every operator request to pull a structured copy of site data — content (pages / posts / media manifests), users, orders, analytics — into a downloadable artifact. Anything that leaves SGEN as a file the operator can take elsewhere traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping an egress 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
Exports live under the Tools module in SG-Admin. The module renders two primary views — the export-job list and the export-create wizard — and exposes a small set of write operations for create, cancel, download, schedule (one-shot or recurring), and delete the resulting artifact.
The module is paired by convention: one half renders the views and prepares the data, the other half handles async job execution and returns AJAX responses. Engineers reading the source will see this split across two controller files plus an async worker; the reference below describes the combined surface as it appears to a calling integration.
A second surface — scheduled exports — lives implicitly via Cron Jobs. A recurring export is a Cron Jobs row whose task target is an export task slug. Operator-driven exports created from this module run once and finish; scheduled exports run on a recurring schedule and post their artifacts back into this surface's artifact list.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Tools → Exports
- URL prefix:
/sg-admin/exports/ - View templates:
application/views/Admin/Exports/
┌────────────────────────────────────────────────────────────────────────────┐│ SG-Admin → Tools → Exports [+ New export] │├────────────────────────────────────────────────────────────────────────────┤│ Subject Format Created Status Size ││ ──────────── ──────── ──────────────── ────────────── ───────────── ││ Users CSV 2 min ago ready (◐ 5d) 1.2 MB ││ Posts JSON 14 min ago building 64% — ││ Orders CSV 1 hr ago ready (◐ 5d) 8.7 MB ││ Analytics XML yesterday ready (◐ 4d) 412 KB ││ Posts CSV 3 days ago expired (purged) ││ Media JSON 4 days ago failed — ││ ││ [⋯ Download] [⋯ Cancel] [⋯ Re-run] [⋯ Delete artifact] │└────────────────────────────────────────────────────────────────────────────┘Actions
The Exports 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 export jobs visible to the current operator, paginated, with subject / format / created / status / size columns. Supports column sort, free-text filter across subject, status filter (building / ready / expired / failed / cancelled), and per-page count. Each row carries an expiry countdown — artifacts auto-purge after a configurable retention window (default 7 days).
Create export
Opens the create wizard. Required fields: subject (one of content / users / orders / analytics), scope (all / filtered subset), format (csv / json / xml), notification preference (email-on-complete / none). Optional fields cover field selection (the wizard surfaces the subject's full field set with per-field include / exclude), date range, and recurring schedule (if set, the export becomes a Cron Jobs row). On submit, the surface validates the scope, validates the field set against the subject schema, enqueues the async job, and returns the job identifier.
Job execution (async)
Exports run as background jobs to keep the request thread free. The worker streams the selected scope into the chosen format, writes to a temporary artifact, computes the size, and transitions the job to ready. Long-running exports (orders for a multi-year window, full content with media metadata) can take minutes; the operator does not need to keep the page open.
Engineering note — the worker streams rather than buffers. Memory footprint stays bounded regardless of the row count. A 10 million-row order export uses the same memory as a 100-row export — only the wall-clock time differs.
Cancel export
Stops an in-flight job. The worker checks for the cancel signal between streamed rows and exits at the next checkpoint. The partial artifact is discarded; the job transitions to cancelled. Useful when the operator realizes the scope was wrong and wants to re-create with a corrected filter.
Download artifact
Streams the artifact to the operator's browser. The artifact lives on the server until its retention window expires; downloads can be repeated as many times as needed within the window. Downloads do not extend the window — the expiry is from artifact creation, not last download.
Schedule (recurring)
When the create wizard's recurring-schedule field is set, the surface registers a Cron Jobs row whose task target is an exports task slug and whose payload carries the saved scope, format, and notification preference. Each scheduled run produces a new artifact in this surface's list, attributed to the original creator. Editing the recurrence happens under Cron Jobs; editing the export definition happens here.
Delete artifact
Removes a ready artifact ahead of its expiry. The job record stays in the list with a deleted status; the artifact file is purged. Useful when an export carried sensitive data and the retention window is longer than desired.
Re-run
Creates a fresh export job using the same scope, format, and field set as a prior job. Issued from the row's action menu. Equivalent to opening the wizard with all fields pre-filled and clicking submit. Used when the prior artifact expired and the same shape is needed again.
Data model
An export job 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 re-runs. |
subject | enum | content, users, orders, analytics. |
scope | json | Filter expression — date range, status, role, category, etc. Subject-dependent. |
fields | array | List of subject field slugs to include. Empty = subject default field set. |
format | enum | csv, json, xml. |
status | enum | pending, building, ready, failed, expired, cancelled, deleted. |
progress | integer | 0-100. Touched during building. |
size_bytes | integer | Artifact size after completion. Null until ready. |
artifact_path | string | Internal path. Resolves through a signed download URL, never exposed directly. |
notify_email | string | Notification target on completion. Optional. |
expires_at | timestamp | When the artifact auto-purges. |
schedule_id | integer | Cron Jobs row identifier when the export is recurring. Null for one-shot. |
created_by | integer | User id of the requesting operator. |
created_at | timestamp | Set on enqueue, immutable. |
completed_at | timestamp | Set on transition to ready / failed / cancelled. |
pending → building → ready on success, pending → building → failed on error, * → cancelled on operator cancel, ready → expired on retention expiry, and ready → deleted on operator delete. The transitions are append-only — a job never moves backward.Field selection. Each subject carries a default field set (the columns shown in its native list view). Operators can include additional fields (audit metadata, joined references) or exclude default fields (PII, internal-only) before submitting. The selection is captured at create time; subsequent re-runs use the same set unless the operator opens the wizard and changes it.
Format semantics. CSV emits a header row plus one row per record, with nested fields flattened by dot notation (profile.phone). JSON emits an array of objects with nested structure preserved. XML emits a root element wrapping per-record elements, with field names as child tags. Choice is operator preference; the schema is identical across all three.
EXPORT JOB├── id integer primary key├── subject enum content | users | orders | analytics├── scope json filter expression (subject-dependent)├── fields array field slugs (empty = subject default)├── format enum csv | json | xml├── status enum pending | building | ready | failed |│ expired | cancelled | deleted├── progress integer 0-100 (touched during 'building')├── size_bytes integer artifact size (null until ready)├── artifact_path string internal path (never exposed)├── notify_email string optional, fires on completion├── expires_at timestamp auto-purge time├── schedule_id integer Cron Jobs row id if recurring (else null)├── created_by integer requesting operator user.id├── created_at timestamp enqueue time└── completed_at timestamp ready/failed/cancelled time↓ on completion (ready)signed download URL issued+ optional email to notify_email↓ on retention expiryartifact file purged, status → expired(record stays for audit)Permissions
Access to the Exports 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 Exports surface.
Layer 2 — per-action capability. Within SG-Admin, each Exports 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 own exports | ✔ | ✔ | ✔ |
| List all exports | ✔ | — | — |
| Create export — content | ✔ | ✔ | — |
| Create export — users | ✔ | — | — |
| Create export — orders | ✔ | — | — |
| Create export — analytics | ✔ | ✔ | — |
| Cancel own export | ✔ | ✔ | ✔ |
| Cancel any export | ✔ | — | — |
| Download own artifact | ✔ | ✔ | ✔ |
| Download any artifact | ✔ | — | — |
| Schedule recurring | ✔ | — | — |
| Delete artifact (own) | ✔ | ✔ | ✔ |
| Delete artifact (any) | ✔ | — | — |
Subject-floor rule. An operator cannot export a subject they cannot list. A Viewer who cannot list users cannot export users; the create wizard hides the users subject from their dropdown. A custom role that grants list-users without grant-create-export-users likewise hides it.
PII gate. Exports of subjects that carry PII (users, orders, analytics with identified visitors) emit a heightened Activity Log entry tagged egress.pii and route a notification to operators subscribed to the security event family. The export still proceeds; the surface does not block PII egress from a capable operator, but the audit trail is louder.
Audit. Every write — create, cancel, download, schedule, delete — emits an Activity Log entry. The log records the acting operator, the subject, the scope summary, the format, and the artifact size when known. The download action also emits an entry per download, so repeated downloads against the same artifact are individually traceable.
CREATE REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-subject per-action) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Subject-floor rule │ can't list subject →│ │ subject hidden in wizard└─────────────┬─────────────┘│ visible▼┌───────────────────────────┐│ PII gate │ subject carries PII →│ │ egress.pii event tagged└─────────────┬─────────────┘│ tagged▼job enqueued│▼async worker streams artifact│▼Activity Log entry perwrite + per downloadRelated references
- Settings — Reference. Owns the artifact retention window, the PII subject list, the security notification routing, and the worker concurrency ceiling. Changes there reshape the Exports surface behavior.
- Cron Jobs — Reference. Recurring exports are Cron Jobs rows. Edit the schedule there; edit the export shape here. A scheduled export run posts a new artifact back into this surface's list.
- Activity Log — Reference. Source of the export audit trail. Every create, cancel, download, and delete emits an entry there. PII exports are tagged for downstream notification routing.
- Backups — Reference. Full-site backup lives on a separate surface — it is a snapshot of the platform state, not a structured data export. The two surfaces share retention concepts but not artifact format.
- Users — Reference. The
userssubject draws from the Users data model. Field selection in the export wizard surfaces the same fields documented there. - Orders — Reference. The
orderssubject draws from the Orders data model. Multi-year exports stream — there is no memory ceiling on row count. - Analytics — Reference. The
analyticssubject draws from the platform's first-party analytics store. Identified-visitor analytics carry PII and trigger the heightened audit path. - Notifications — Reference. The
notify_emailfield at create time resolves through the notification template surface. The default email body cites the artifact identifier and the signed download URL.
/docs/exports.