# Approval Email Notifications — template catalog & design

Reference package for the **approval email notification** work. The deliverable is
the **email template catalog**: seed the shared approval/notification templates
into NexusCRM, categorized by object, so an admin can add an **Email Alert**
action to **any** approval process and select a template.

> **Design / scope-reference drop (docs + scaffolding).** It does **not** integrate
> the records into `deployments/offline/runtime/seeds/` or open a delivery PR — that
> follows once the scope is approved.
>
> **Approval processes are NOT touched.** No WorkflowAlert or ProcessAction is
> seeded. Admins add the Email Alert action + pick a template themselves.

## Start here
- **Design doc:** [`docs/design/approval-email-notifications.md`](../../../docs/design/approval-email-notifications.md)
  — BF/AF, what NexusCRM already has (L0 picker/engine) vs what to seed (L2 catalog),
  L0/L1/L2, per-object folders, merge-field translation, phasing.
- **Deck:** [`docs/design/NexusCRM-Approval-Email-Notifications.pptx`](../../../docs/design/NexusCRM-Approval-Email-Notifications.pptx)

## Tracking issues
- **#3530** — pack ships no approval email.
- **#3556** — port the remaining approval processes + emails (other objects) / HTML templates.
- **#2267** — upstream: empty template catalog + dynamic-text / merge-field rendering.

## The deliverable — template catalog
- **74** `_System_EmailTemplate` records — the complete Unfiled Public **text** approval/notification set (all objects), merge fields translated to native `{{Record.*}}`, `IsActive=true`.
- **11** `ReportFolder` (Type='Email') per-object folders — Quote, Account, Lead, PoC/Cloud, Order, Invoice, Support, Opportunity, Contract, Contact, General.
- The picker (`EmailAlertForm.tsx`) lists **all active** templates (no object filter), so seeding active records = selectable everywhere; folders + SFDC names organize them.
- **Excluded:** the 40 Public **HTML** templates (marketing/event: conferences, webinars, SFDC samples) — not approval-related.

## Contents
| Path | What |
|---|---|
| `build_template_catalog.py` | **Primary.** Generates the catalog: 74 `_System_EmailTemplate` + 11 `ReportFolder` (Email) records. |
| `migrated/email_template_catalog.records.json` | The 74 template records (each with `FolderKey`). |
| `migrated/email_folders.records.json` | The 11 per-object folder records. |
| `migrated/TEMPLATE_CATALOG.md` | Per-object catalog listing + merge-field flags. |
| `sfdc_source/catalog/email/` | Original SFDC export of the 74 text templates (provenance). |
| `build_migrated_records.py` + `migrated/{email_templates,workflow_alerts,approval_alert_process_actions}.*` | **Reference only — NOT seeded.** Documents how SFDC wired the Quote+Account approvals (6 templates / 21 alerts / 98 actions), for the optional pack-owned wiring follow-up (#3530). |
| `sfdc_source/email/`, `sfdc_source/workflows/` | Provenance for that Quote/Account reference. |

## Merge-field translation
`{!Obj.Field}` → `{{Record.Field}}` · `{!$User.Field}` → `{{User.Field}}` ·
`{!Obj.Link}` → `{{Record.Link}}` (record-URL, unconfirmed) ·
`{!ApprovalRequest.Internal_URL}` → `{{Approval.RequestUrl}}` (#2267) ·
cross-object `{!OtherObj.Field}` → `{{Record.Field}}` (blank until flattened / #2267).
Flags are render caveats, **not** selection blockers.

## Delivery
- **D1 (L2, done):** `integrate_reference_data.py` emits the 74 templates + 10 folders as a
  governed reference-data source
  (`deployments/offline/runtime/reference-data/email-template-catalog.json`, registered in
  `manifest.json`). The `pack_reference_data` Catalog module is selected through the Seed
  Dispatcher for local, test, watchdog, EXP, staging, and **production**; its reviewed adapter
  delegates to `apply_pack_reference_data.sh`. No final-pack rebuild is required. The governed
  Account approval set stays in `approval-email-templates.json`; the catalog excludes its
  `folder_account_email_templates` to avoid a duplicate reference-data key.
- **D2 (L0 front-end):** `upstream-fe-email-alert.md` — PR-ready draft for the upstream NexusCRM
  front-end "Email Alert" action that scaffolds a Flow (per-lifecycle-event template picker).

## Regenerate
```bash
python build_template_catalog.py     # the catalog (primary deliverable)
python integrate_reference_data.py   # emit the catalog reference-data source (D1)
python build_migrated_records.py     # Quote+Account wiring reference (not seeded)
```
Source of truth is the SFDC export under `sfdc_source/`; regenerate — don't hand-edit `migrated/`.