PranavNagrecha/AwesomeSalesforceSkills / skills/admin/classic-email-template-migration
classic-email-template-migration
VerifiedMigrating Classic email templates (Text, HTML with Letterhead, Custom HTML, Visualforce email) to Lightning Email Templates (LET) and the Email Template Builder. Covers merge-field translation, Letterhead-to-Enhanced-Letterhead conversion, Visualforce email retention strategy, folder reorganization, sender-context (OrgWideEmailAddress) preservation, and downstream Email Alert / Process Builder / Flow rewiring. NOT for transactional Apex email sending (use apex/apex-outbound-email-patterns) or marketing email broadcasts (use Marketing Cloud / Account Engagement).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.7 KB |
| references/examples.md | markdown | 7.3 KB |
| references/gotchas.md | markdown | 7.2 KB |
| references/llm-anti-patterns.md | markdown | 7.0 KB |
| references/well-architected.md | markdown | 6.8 KB |
| scripts/check_classic_email_template_migration.py | script | 4.8 KB |
| templates/classic-email-template-migration-template.md | markdown | 2.9 KB |
references/llm-anti-patterns.md
View on GitHub# LLM Anti-Patterns — Classic Email Template Migration
Common mistakes AI coding assistants make when generating or advising on Classic-to-Lightning email template migrations.
## Anti-Pattern 1: Verbatim Copy of `{!IF()}` and `{!CASE()}` Merge Formulas
**What the LLM generates:** A migrated Lightning template that retains `{!IF(Contact.Email != null, Contact.Email, 'fallback@x.com')}` in the body, assuming Lightning supports the same merge engine.
**Why it happens:** Merge formulas look like inline expressions; the model doesn't recognize that Lightning's merge engine is a strict subset.
**Correct pattern:** Lightning supports straight field interpolation only. Pre-compute conditional values as formula fields on the merge record (Contact, Account, etc.) and merge the formula field. The migration is the moment to factor expressions into the data model.
## Anti-Pattern 2: Assuming `TemplateType` Distinguishes Classic from Lightning
**What the LLM generates:** Migration script with `WHERE TemplateType IN ('text', 'html', 'custom', 'visualforce')` to "find all Classic templates."
**Why it happens:** `TemplateType` is the more obvious axis; `UiType` is a less-known field.
**Correct pattern:** Use `WHERE UiType = 'Aloha'` for Classic and `WHERE UiType = 'SFX'` for Lightning. `TemplateType` describes content format, not vintage. Lightning Email Templates also have `TemplateType='html'` — a script filtering by `TemplateType` will mix Classic and Lightning rows.
## Anti-Pattern 3: Translating `{!Account.Name}` to `{{Account.Name}}` Without Recipient Scoping
**What the LLM generates:**
```
Hello {{Contact.FirstName}}, your account {{Account.Name}} has been updated.
```
**Why it happens:** Mechanical bracket substitution.
**Correct pattern:** Lightning merge fields are scoped to Recipient / Sender / Related. The correct form:
```
Hello {{Recipient.FirstName}}, your account {{Recipient.Account.Name}} has been updated.
```
The Recipient object IS the Contact when the email targets a Contact; field paths span from there. Without the scope prefix, the merge engine cannot resolve the field.
## Anti-Pattern 4: Re-creating Per-Department Letterheads Instead of One Centralized Enhanced Letterhead
**What the LLM generates:** A migration plan that recreates one Enhanced Letterhead per Classic Letterhead, preserving the proliferation.
**Why it happens:** Treating the migration as a 1:1 port without re-architecting the brand.
**Correct pattern:** Classic Letterheads often proliferated because the editor was clunky and copying was easier than maintaining one. Migration is the chance to consolidate. Build 1–3 Enhanced Letterheads per org (typically: corporate, transactional/no-reply, support). Templates reference the shared Letterhead. Future brand updates touch one record, not 30.
## Anti-Pattern 5: Re-implementing Visualforce Templates as Hand-Coded Apex String Builders
**What the LLM generates:** For every Classic VF email template, a new Apex class that builds the body via `String.format()` and sets `Messaging.SingleEmailMessage.setHtmlBody()` instead of `setTemplateId()`.
**Why it happens:** Goal of "no remaining VF" pushes the model to find an Apex equivalent for every template.
**Correct pattern:** Visualforce email templates are still supported. Keep the simple ones; rewrite only the ones whose Apex logic is excessive for what they do. Hand-coded string builders lose the admin-editable surface (admins can no longer tweak the email; only developers can) and are harder to test. Default: keep VF unless the migration plan specifically justifies the rewrite.
## Anti-Pattern 6: Skipping the Folder-Sharing Replication Step
**What the LLM generates:** A script that creates Lightning Email Templates in a single new folder (e.g., "Migrated Templates") without recreating the original folder structure or sharing rules.
**Why it happens:** Folder structure feels like an admin concern, not a migration step.
**Correct pattern:** Replicate folders BEFORE creating templates. For each Classic folder, create a Lightning folder with the same name and `FolderShare` rules. Place migrated templates in the corresponding folder. Without this, users who relied on Classic folder permissions lose access to migrated templates and their Email Alerts fail at send time.
## Anti-Pattern 7: Editing Email Alerts in the Setup UI for Bulk Updates
**What the LLM generates:** A step-by-step plan that says "Open each Email Alert in Setup; replace template; save." for 100+ alerts.
**Why it happens:** Setup UI is the obvious admin tool.
**Correct pattern:** Use Metadata API for any update touching more than ~10 alerts. Retrieve all `WorkflowAlert` metadata, transform the `<template>` references via the old → new mapping, deploy as a single change set. Setup-UI editing is per-alert and error-prone at scale; one missed alert silently sends the wrong template.
## Anti-Pattern 8: Forgetting to Re-set OrgWideEmailAddress on Downstream Consumers
**What the LLM generates:** Migration plan that focuses entirely on template content, with no step to verify or re-set the OWA on Email Alerts and Apex calls.
**Why it happens:** OWA was attached to the Classic template; the model doesn't know it must move to the consumer in Lightning.
**Correct pattern:** For every Classic template that was paired with an OrgWideEmailAddress, the migration plan must include "set the OWA on each downstream Email Alert" (and on each Apex `setOrgWideEmailAddressId()` call). Lightning templates have no sender field — the sender lives on the consumer. Omitting this step results in alerts sending from the running user's address instead of the no-reply (or branded) address recipients expect.
## Anti-Pattern 9: Trusting the Salesforce Preview for Cross-Client Rendering
**What the LLM generates:** A workflow that says "Preview the template in the Email Template Builder; if it looks right, mark migrated."
**Why it happens:** Preview is the easiest verification.
**Correct pattern:** The Salesforce preview uses a modern browser engine that hides Outlook rendering issues. Always test on real email clients (Outlook, Gmail web, Apple Mail mobile) before declaring migration complete for any visually-complex template. Outlook's HTML engine is the lowest common denominator — table-based layouts and inline styles are required, modern CSS (flexbox, grid, custom fonts) silently degrades.
## Anti-Pattern 10: Deleting Classic Templates Immediately After Migration
**What the LLM generates:** A migration script that, after confirming Lightning templates are created, deletes the Classic source templates.
**Why it happens:** "Cleanup" instinct.
**Correct pattern:** Set Classic templates to `IsActive = false` instead of deleting. Reasons: (a) audit trail — you may need to compare original vs migrated content; (b) Email Alerts that haven't been rewired yet may suddenly fail when the template disappears; (c) historical Activity records reference the original template. Schedule deletion only after a documented soak period (typically 90+ days) and a confirmation that no downstream consumer still references the old IDs.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |