Developer onboarding SGEN
How to onboard as a developer working in SGEN
You have been handed access to a SGEN site — your business in this walkthrough — and your brief is to set up tracking, lock in brand overrides, clean up legacy URLs, and extend a few SG-Builder components with scoped styles. This guide covers the six surfaces you will reach for most, in the order that minimises risk. Read each section before you click.
Who this is for. In-house developers and contracted vendors working inside a customer's SGEN admin — not SGEN platform engineers. The sections below describe what each tool does, when to use it, and what to verify before moving on.
What is this for?
SGEN gives developers and contractors several code-level surfaces that sit between the design layer (themes + SG-Builder) and the raw database. This workflow walks all six in a safe sequence:
- Custom CSS — global stylesheets that override the active theme and survive theme switches.
- Custom Codes — global HTML snippet injection for tag managers, structured data, and third-party widgets.
- Redirects — path-to-path rules for legacy URL migration and page renames.
- Search & Replace — bulk string swap across all stored content and settings.
- Post export and import — content backup before risky bulk operations.
- SG-Builder Additional CSS — per-component scoped rules that do not pollute global stylesheets.
Each surface is independent. You can use any of them without the others. This guide sequences them in the order that gives you a safe restore point before each destructive step.
Good use cases
Scenario A — New site onboarding. Contracted developer a developer is brought in to set up your business from a fresh SGEN instance. He adds brand tokens in Custom CSS (priority 1), GTM and structured data in Custom Codes, 23 legacy-path redirects, and then does a dry-run Search & Replace to verify no staging URLs remain in stored content. He takes a Blog export before the Search & Replace run.
Scenario B — Pre-sprint backup and domain migration. Before every sprint deploy, the in-house developer exports all posts, runs a dry-run Search & Replace to count how many places reference the old staging domain, then executes the replace and spot-checks three pages on the live site.
Scenario C — Component-level brand extension. A vendor team uses SG-Builder Additional CSS for every component-specific override — a dark hero overlay, a tighter card-grid gap, a custom button radius on one landing page — keeping the Custom CSS list clean and limited to brand tokens that the whole site shares.
What NOT to use this for
Custom CSS accepts style rules only. Anything with a <template data-safe="script" data-attrs=""></code> tag goes in Custom Codes.</p></div><div class="sdp-rule-card"><div class="sdp-rule-title">Custom Codes for page layout</div><p>Custom Codes injects into the page shell (<code><head></code> or <code><body></code>). Page HTML, images, and product blocks belong in SG-Builder.</p></div><div class="sdp-rule-card"><div class="sdp-rule-title">Search & Replace for surgical edits</div><p>The string match is naive — it replaces every occurrence, including partial matches inside HTML attributes. If you need to change one specific paragraph, edit it in SG-Builder or the page editor.</p></div><div class="sdp-rule-card"><div class="sdp-rule-title">Redirects for query-string routing</div><p>SGEN Redirects match on path only. Query strings are ignored.</p></div><div class="sdp-rule-card"><div class="sdp-rule-title">Export/Import as a full site migration tool</div><p>Blog Export covers posts only — not pages, products, media, or settings. Take a hosting-level database snapshot for full-site backup.</p></div></div>
<h3 class="sdp-h3">How this connects to other features</h3>
<div class="sdp-grid-2"><div class="sdp-card"><p><a href="././custom-css/01-create-a-custom-css-snippet.md"><strong>Custom CSS →</strong></a> covers the create-snippet path in depth. This workflow uses the same form; the reference doc explains every field.</p></div><div class="sdp-card"><p><a href="././custom-codes/01-create-and-manage-custom-codes.md"><strong>Custom Codes →</strong></a> covers add-new, placement options, and the status toggle in detail.</p></div><div class="sdp-card"><p><a href="././redirects/01-manage-site-redirects.md"><strong>Manage site redirects →</strong></a> covers bulk import via CSV, the 301 vs 302 distinction, and the test-URL preview tool.</p></div><div class="sdp-card"><p><a href="././search-replace/01-bulk-search-and-replace-content.md"><strong>Search & Replace →</strong></a> covers dry-run output, table selection, and when to abort.</p></div><div class="sdp-card"><div class="sdp-card-title">Appearance → Theme Editor</div><p>sets foundational color and font tokens. Custom CSS overrides sit above these — your brand tokens win even if the owner switches the active theme.</p></div><div class="sdp-card"><div class="sdp-card-title">SG-Builder Additional CSS trait</div><p>scopes rules to one component instance. Do not confuse it with Custom CSS, which is site-wide.</p></div></div>
<h3 class="sdp-h3">Before you start</h3>
<p>Before touching any tool that writes to the site:</p>
<ol><li><strong>Export a content backup.</strong> Go to <strong>Blog → Export</strong> and download the full post archive. Save the file with a date in the name (e.g. <code>acmecoffee-posts-2026-05-05.xml</code>) before any bulk operation.</li><li><strong>Open the public site in a second tab.</strong> After every save, reload it and confirm the change is visible. The admin save flash confirms the write reached the database — it does not confirm the public page updated.</li><li><strong>Work in a single browser session.</strong> Some admin write actions share session state. Two simultaneous admin tabs on bulk operations like Search & Replace can produce unexpected results.</li><li><strong>Confirm your admin role.</strong> All six surfaces require an Administrator role. Editor and Author roles cannot access Custom CSS, Custom Codes, Redirects, or Tools.</li></ol>
<h3 class="sdp-h3">Where to go</h3>
<p>All six surfaces are in the SGEN admin at <code>/sg-admin/</code>:</p>
<table style="width:100%;border-collapse:collapse;margin:14px 0;font-size:14px"><thead><tr><th style="border:1px solid #e5e7eb;padding:8px 10px;background:#f9fafb;text-align:left;font-weight:600">Surface</th><th style="border:1px solid #e5e7eb;padding:8px 10px;background:#f9fafb;text-align:left;font-weight:600">Admin path</th></tr></thead><tbody><tr><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Custom CSS</td><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Dashboard → Custom → CSS</td></tr><tr><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Custom Codes</td><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Dashboard → Custom → Codes</td></tr><tr><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Redirects</td><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Dashboard → Redirects</td></tr><tr><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Search & Replace</td><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Dashboard → Tools → Search & Replace</td></tr><tr><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Blog Export</td><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Dashboard → Blog → Export</td></tr><tr><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Blog Import</td><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">Dashboard → Blog → Import</td></tr><tr><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">SG-Builder Additional CSS</td><td style="border:1px solid #e5e7eb;padding:8px 10px;vertical-align:top">SG-Builder → select component → Style tab → Additional CSS</td></tr></tbody></table>
<h3 class="sdp-h3">Steps</h3>
<p>The steps below follow a safe sequence: take a backup first, add styles, add scripts, add redirects, run the domain fix, then verify everything.</p>
<div class="sdp-steps"><div class="sdp-step"><div class="sdp-step-num">1</div><div class="sdp-step-body"><div class="sdp-step-title">Export a content backup before anything else</div><p>Go to <strong>Blog → Export</strong>. Click <strong>Export Posts</strong>. A download starts automatically — save the file before proceeding. This is your restore point for steps 4 and 5.</p><p>If you need to restore: go to <strong>Blog → Import</strong>, upload the saved file, and SGEN will re-import the posts. Import does not duplicate posts that already exist with the same slug — it skips them.</p></div></div><div class="sdp-step"><div class="sdp-step-num">2</div><div class="sdp-step-body"><div class="sdp-step-title">Add brand CSS tokens in Custom CSS</div><p>Go to <strong>Custom → CSS → Add New</strong>. Create one snippet that holds your <code>:root</code> custom properties at priority 1. This snippet needs to exist before you start SG-Builder work — components pick up the tokens automatically.</p><p>After saving, open the public homepage in a new incognito tab. Right-click → <strong>View page source</strong>. Confirm your <code>:root</code> block appears inside <code><head></code> before <code></head></code>.</p></div></div><div class="sdp-step"><div class="sdp-step-num">3</div><div class="sdp-step-body"><div class="sdp-step-title">Add tracking scripts and structured data in Custom Codes</div><p>Go to <strong>Custom → Codes → Add New</strong>. Add one snippet per purpose — GTM at <code></body></code> End, structured data at <code><head></code>. Keep them separate so you can toggle each independently.</p><p><strong>Structured data example.</strong> For a product page, add a second snippet at <code><head></code> named "Structured data — Canvas Tote Bag":</p><pre><code><script type="application/ld+json">
{ "@context": "https://schema.org", "@type": "Product", "name": "Canvas Tote Bag", "brand": { "@type": "Brand", "name": "your business" }, "offers": { "@type": "Offer", "price": "30.00", "priceCurrency": "USD", "availability": "https://schema.org/InStock" }
}
</template>
After saving, reload the public product page and check view-source — confirm the <script type="application/ld+json"> block appears inside <head>.
Go to Dashboard → Redirects → Add New. Enter paths (not full URLs) — /old-page, not https://yourdomain.com/old-page. Use 301 Permanent for any change you intend to keep; use 302 Temporary for migration windows you will revert.
After saving each rule, test it in an incognito tab — open the source path and confirm your browser lands on the destination. Do not test from the same authenticated session you used to save; cached state in an admin session can mask a misconfigured rule.
301 vs 302. Use 301 when the change is permanent and you want search engines to transfer ranking signals. Use 302 for time-boxed detours — a migration window, a maintenance hold, a seasonal sale page — that you will revert.
After redirects are in place, fix the stored internal links with Search & Replace. Go to Dashboard → Tools → Search & Replace.
Always run the dry run first. The form has a Dry Run checkbox. Enable it, submit, read the counts per table — then disable it and submit again to execute.
Search for: acmecoffee.staging.sgen.com
Replace with: yourdomain.com
Tables: All available
Dry run: ON → run first, read counts → OFF → executeDry-run output for your business showed: Pages 14 matches / Posts 6 matches / Settings 3 matches / Redirects 0 matches. After confirming the counts, Alan unchecked Dry Run and submitted. He then opened three pages on the live public site and confirmed internal links pointed to yourdomain.com, not the staging host.
After executing, spot-check at least three public pages and one settings-dependent page (e.g. the homepage) to confirm no residual references to the old string remain.
For styles that belong to one specific component on one page — a dark hero overlay, a custom card gap, a one-off button radius — use SG-Builder Additional CSS instead of the global Custom CSS list.
Open SG-Builder, select the component, open the Style tab in the right-hand panel, and scroll to Additional CSS. Enter your rules there.
/* Scoped to this Section component only */
.hero-overlay { position: absolute; inset: 0; background: rgba(74, 44, 10, 0.55); pointer-events: none;
}These rules render only on that component's wrapper element. The same class name on a different component will not carry the same styles — every component has its own Additional CSS scope.
After entering Additional CSS, click the SG-Builder Publish button to push the change to the public page. The style panel auto-saves to the builder state, but the public page does not update until you publish.
What success looks like
After completing all six steps on your business: Public homepage view-source shows a <style> block in <head> with :root custom properties. Structured data snippet is Active at <head>. View-source on the public homepage confirms both are present. Opening an old URL in an incognito tab lands on the correct new page without a 404. Three spot-checked public pages show no references to the old staging domain. Import path confirmed: Blog → Import → upload file → posts restored without duplicates. No site-wide rules buried in component scope.
- Custom CSS — the list shows "Brand tokens — your business" as Active, priority 1.
What to do if it does not work
Custom CSS is not appearing on the public page. Open the snippet from the Custom CSS list and confirm its status is Active (not Inactive or Trash). Confirm the priority is a number, not blank. Hard-reload the public page (Ctrl+Shift+R) to bypass browser cache. If the snippet is Active and the block still does not appear in view-source, try creating a second test snippet with a trivially visible rule (e.g. body { outline: 2px solid red; }) to confirm Custom CSS is working on this site.
Custom Code is not firing. Open the code from the list and confirm the placement field is set to what you intended. Check the Status field — if it shows Inactive, the snippet is saved but not rendered. For body-placed snippets: SGEN strips HTML comments from the body output, but the <script> tag itself is preserved — confirm the script tag is present in view-source, not just the surrounding comments.
A redirect is not working. Test in an incognito browser tab — not the authenticated admin session. Open the source path and watch where the browser ends up. Confirm you entered a path (/old-page) not a full URL (https://yourdomain.com/old-page) in the Source field. The Redirects admin has a test-URL preview tool, but always confirm on the live public page — the admin preview has a known edge case on exact-match rules.
Search & Replace changed something it should not have. Restore from the Blog Export you took in step 1. Go to Blog → Import, upload the backup file, and SGEN will restore the posts. For pages and settings (not covered by Blog Export), contact your hosting provider for a database snapshot restore. This is why the dry-run step is mandatory — if the counts look wrong, abort before executing.
SG-Builder Additional CSS is not showing on the public page. Confirm you clicked Publish after entering the CSS in the style panel. Auto-save writes to the builder state only — the public page does not update until you publish. If you published but the change is not visible, do a hard reload of the public page.
A note on confirming your saves
SGEN admin write forms process each save immediately upon submission. Because of this, re-opening the record after every save is the most reliable way to confirm what was stored. The save flash confirms the request reached the admin — it does not always confirm the stored value matches exactly what you entered.
The habit to build:
- Custom CSS — re-open the snippet and confirm the CSS body and priority stored correctly.
- Custom Codes — re-open the code and confirm the placement field matches what you entered.
- Redirects — after saving, open the Redirects list and confirm the source and destination appear as entered.
- Search & Replace — after executing, spot-check two or three pages on the public site to confirm the replacement took effect.
Re-opening the record is a one-click habit that catches the rare case where a write did not persist cleanly.
Examples
Example 1: a developer onboards your business from a fresh SGEN instance. Alan is contracted for a two-day handover. He starts by exporting the blog (12 posts, downloaded acmecoffee-posts-2026-05-05.xml). He adds a single Custom CSS snippet — "Brand tokens — your business" at priority 1 — so the :root tokens are live before he opens SG-Builder. He adds GTM at </body> End and a Product structured data block at <head>, each in its own Custom Code snippet. He checks view-source on the homepage and the Canvas Tote Bag product page to confirm all three are present. He then enters 23 redirects for the old site structure, tests five of them in incognito, and hands back a Redirects list showing 23 Active rules. Final step: dry-run Search & Replace for the staging domain — counts come back clean (zero matches), so no execute is needed. Total session: 4 hours.
Example 2: Bulk domain migration after moving from a staging host. your business approved the production domain. Alan runs a dry-run Search & Replace: staging host → yourdomain.com, All tables. Dry run returns: Pages 14 / Posts 6 / Settings 3 / Redirects 0. He confirms the count looks right and executes. He opens the homepage, the Canvas Tote Bag product page, and the Blog index — internal links and canonical tags all reference yourdomain.com.
Example 3: Vendor adds a dark-overlay hero and a custom card grid without polluting global CSS. A vendor team is asked to style one landing page differently from the rest of the site. They open SG-Builder, select the hero Section, and enter the overlay rule in Additional CSS. They select the card Row and enter a tighter gap override in its Additional CSS. They do not add anything to the Custom CSS list — global brand tokens are already set and do not need touching. After entering both Additional CSS blocks, they click Publish. The landing page has the overlay and the tighter cards. Every other page on the site is unchanged.