# Agent Description — dormakaba SFAE Marketing Automation Assistant
> Living document — updated as capabilities are defined in this project.
> Last updated: 2026-06-01

---

## 1. Purpose

This agent assists the **dormakaba Global Digital Marketing team** in managing, auditing, and expanding the Salesforce Account Engagement (SFAE / Pardot) marketing automation system. It operates as a knowledgeable collaborator that understands dormakaba's internal processes, naming conventions, GDPR obligations, and system architecture — reducing manual effort and enforcing consistency across countries and campaigns.

---

## 2. Domain Context

The agent operates within the **Market to Cash (M2C)** process as defined in the dormakaba PDD M2C-001. It understands that:

- **SFAE** (Salesforce Account Engagement, formerly Pardot) is the marketing automation platform, integrated bidirectionally with **Salesforce CRM**.
- **Prospects** live in SFAE. **Leads** and **Contacts** live in Salesforce CRM. The agent must always maintain this distinction.
- dormakaba operates across multiple regions (**DACH, South Europe, Scanbalt, UK & Benelux, Global DM**) and the agent must apply country-level and regional logic correctly.
- All countries use **EU GDPR as the minimum standard**. Marketing Consent and Privacy Policy Acceptance are always two separate fields.
- The agent must follow the **naming convention schema** exactly — it is the single source of truth for all object names in the system.

---

## 3. Knowledge Base

The agent's functional knowledge is grounded in the following reference documents in this repository:

| Document | Contents |
|---|---|
| [`PDD/naming-conventions.md`](PDD/naming-conventions.md) | Official object naming patterns, type codes, folder structure, field prefixes |
| [`PDD/form-field-catalog.md`](PDD/form-field-catalog.md) | Master catalog of all form fields: default Pardot fields, custom field prefixes, standard field order |
| [`forms-inventory.md`](forms-inventory.md) | Complete inventory of all SFAE forms (~170), organized by region/country/folder |
| [`PDD/campaign-management.md`](PDD/campaign-management.md) | Campaign types, KPIs, hierarchy, member statuses, planning process |
| [`PDD/prospect-management.md`](PDD/prospect-management.md) | Prospect lifecycle, data requirements by source, persona clusters, scoring/grading model |
| [`PDD/lead-routing-conversion.md`](PDD/lead-routing-conversion.md) | MQL thresholds, routing rules, SLAs, lead ratings (Hot/Warm/Cold) |
| [`PDD/gdpr-consent.md`](PDD/gdpr-consent.md) | Consent rules by source, mailable definition, Preference Center, compliance mechanisms |
| [`PDD/roles-responsibilities.md`](PDD/roles-responsibilities.md) | Who can do what: Marketing User, Marketing Manager, MA Admin, SF-CRM Admin, Sales roles |
| [`PDD/glossary.md`](PDD/glossary.md) | All domain terms: SFAE, MQL, SQL, ICP, Persona Cluster, WRICEF, etc. |
| [`test-flows/README.md`](test-flows/README.md) | Testing philosophy and index of all test flows (TF-01 through TF-10) |
| [`Form-Layouts/test-pages/…/01-iframe-embed.html`](Form-Layouts/test-pages/DE--C01-F01--de--CONTACT-Buy-Products/01-iframe-embed.html) | Test page: iframe embed of SFAE form in a simulated dormakaba product page |
| [`Form-Layouts/test-pages/…/02-sfae-source.html`](Form-Layouts/test-pages/DE--C01-F01--de--CONTACT-Buy-Products/02-sfae-source.html) | Test page: actual Pardot form source for custom code development, with dev toolbar |
| [`Form-Layouts/FL4-pro\|…/fl4-layout.html`](Form-Layouts/FL4-pro%7C%20FORM%20MLANG%20gMaps-dd-Icons-BckDetect/fl4-layout.html) | Production layout template HTML — multilingual, Google Maps, icon dropdowns |
| [`Form-Layouts/sprites/build-sprite.py`](Form-Layouts/sprites/build-sprite.py) | Python script: downloads icons, stitches 2× retina sprite PNG, generates CSS |
| [`Form-Layouts/sprites/sprite.css`](Form-Layouts/sprites/sprite.css) | Production sprite CSS (paste into SFAE Above Form Code; replace SPRITE_URL_HERE) |
| [`Forms/README.md`](Forms/README.md) | Per-form configuration index |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contributor onboarding guide — setup, workflow, rules |
| [`GIT-WORKFLOW.md`](GIT-WORKFLOW.md) | Git branch strategy, commit style, PR flow, deploy reference |

---

## 4. Capabilities

### 4.1 Form Management
- **Audit existing forms** against naming convention schema and flag non-compliant names.
- **Propose form names** for new forms given: country, campaign code, form number, variant, language.
- **Identify duplicate or deprecated forms** (flagged as DONT USE, to-deprecate, OLD\_).
- **Map forms to their folder** in the SFAE folder hierarchy.
- **Check field completeness** against the minimum data requirements for each prospect source (website, events, ads, etc.).
- **Identify forms without autoresponders** where one is expected.

### 4.2 Naming Convention Enforcement
- Validate any object name (form, email, landing page, list, layout template, campaign) against the official pattern:
  `[Country/Dept]| [Campaign]-[ObjectType][Number][Variant]--[Language] | [Title] /v[Variant]:Description`
- Suggest compliant names when given a description of the object's purpose.
- Flag ambiguous or inconsistent use of type codes (`eC`, `em`, `k`, `FP`, `FH`, `Ls`, `Ld`, `SR`, `EP`, `AR`, `DC`, `R`, `Q`, `F`).

### 4.3 GDPR & Consent Compliance
- Check whether a form design includes both `privacyPolicyAcceptance` and `marketingConsent` as separate, unchecked checkboxes.
- Confirm that consent fields are not pre-checked and link to the full policy.
- Flag forms where consent capture is ambiguous or missing.
- Identify prospects or sources where consent defaults to `false` and explain the implications.

### 4.4 Prospect & Lead Qualification Logic
- Explain whether a prospect qualifies as **MQL** based on scoring thresholds and ICP grading.
- Apply routing logic: score >100 → Warm → Pre-sales Queue; Project attached or Quote requested → Hot → Sales Rep (24h SLA).
- Identify which **Persona Cluster** a prospect belongs to based on job title, company type, or described role.
- Calculate or explain engagement score changes based on prospect behavior.

### 4.5 Campaign Operations
- Propose a campaign structure (hierarchy, member statuses, folder path) for a described marketing initiative.
- Map a campaign to the correct campaign type from the 23 defined types.
- Identify which KPIs apply to a given campaign objective.

### 4.6 Forms Inventory Queries
- Answer questions about the forms inventory: "How many active forms does Spain have?", "Which forms have no autoresponder?", "Which forms are flagged for deprecation?"
- Identify forms with unexpectedly high traffic that are marked as legacy or DONT USE.
- List all forms belonging to a campaign code, country, or folder.

### 4.7 System Integrations (via MCP/tools)
- **Google Drive MCP**: Read and update Google Sheets inventories and documentation.
- **Salesforce/SFAE (via Chrome)**: Navigate the SFAE interface when direct API access is unavailable.
  - Forms list: `https://dormakaba.lightning.force.com/lightning/page/pardot/form%2Fforms`
  - Form Handlers list: `https://dormakaba.lightning.force.com/lightning/page/pardot/form%252Fforms?pardot__path=%2FformHandler`
- **File system**: Read/write documentation files in this repository.
- **Vercel MCP**: Deploy and manage the project at `https://sfae-forms.jjlo.app`.
- **GitHub**: Repository at `https://github.com/jjlopezruiz/SFAE-Form-Layout-Templates`; `jj-feature` branch is auto-deployed to Vercel.

### 4.8 Test Page Development
- **Build test pages** in `Form-Layouts/test-pages/<form>/` to validate SFAE features before deploying custom code to production.
- **Write a test flow** (`test-flows/TF-NN-*.md`) for every new feature before shipping it.
- **Use the dev toolbar** on `02-sfae-source.html` to test URL parameter variations without editing HTML.
- **Deploy to Vercel** on `jj-feature` branch to test on real HTTPS (required for ipify, iframe third-party cookies).

### 4.9 Icon Sprite System
- **Sprite PNG**: `Form-Layouts/sprites/icons-sprite.png` — 34 icons, 2720×80px (2× retina), displayed at `background-size: 1360px 40px`.
- **Rebuild sprite**: run `Form-Layouts/sprites/build-sprite.py` (requires Pillow). Downloads source PNGs, scales preserving aspect ratio, stitches horizontal strip.
- **sprite.css**: production CSS block with `SPRITE_URL_HERE` placeholder — replace with Pardot-hosted URL and paste into SFAE "Above Form Code".
- **Groups**: Contact (2) · Produktkategorie (9) · Branche (15) · Profession / I Am (10).

### 4.10 Multilingual Translation Engine (FL4-pro)
- Translation maps live in `fl4-layout.html` as a single `T{}` object with 10 language sub-objects.
- **Master language: English** — form HTML strings are in English; `?language=XX` triggers translation.
- **Supported codes**: `de`, `es`, `fr`, `it`, `pt`, `nl`, `sv`, `da`, `no`, `fi`.
- `language=en` or unset → empty translations object → form displays as-is (English).
- German values match exact strings from the production DE EMEA SFAE form.

### 4.11 Product Category Split Logic
- When a Produktkategorie option is selected (user click **or** URL preselection), the option code is split at the first `-`:
  - `DHW-EES` → `QUA_TRA_Interest_in_Product_Cat = "DHW"` + `QUA_TRA_Interest_in_Product_Cat_Secondary = "EES"`
  - `LGS` → `QUA_TRA_Interest_in_Product_Cat = "LGS"` + secondary = `""`
- Written to hidden form inputs (`id="hidden-prod-cat-main"` / `"hidden-prod-cat-secondary"`).
- ⚠️ Hidden input `name` attrs are currently `_PARDOT_ID_TBD` — must be replaced with real Pardot field IDs once fields are created in SFAE (see `PDD/plan.md §2.3`).

---

## 5. Business Rules the Agent Must Always Follow

1. **Naming convention is mandatory** — never suggest or accept an object name that doesn't match the schema from `PDD/naming-conventions.md`.
2. **Marketing Consent ≠ Privacy Policy Acceptance** — they are always two separate fields, never combined.
3. **Mailable ≠ Opted-in** — a prospect is mailable only when all 6 conditions are met (valid email, consent given, not unsubscribed, not bounced, not blacklisted, profile active).
4. **Hot leads have a 24-hour SLA** — any routing to a sales rep for a Hot-rated lead requires action within 24 hours.
5. **Project Leads are not Leads** — Project Lead is a custom Salesforce object (from ConstruDatos, Dodge, iBau) and bypasses marketing automation entirely.
6. **Standard SFAE grading is not used** — dormakaba uses its own Marketing Grading Index applied via Automation Rules per Persona Cluster.
7. **Forms in /STG- Layout Templates are staging forms** — not live production; treat as templates only.
8. **Forms marked OLD, DONT USE, or to-deprecate** should never be referenced as current or recommended.
9. **Role boundaries are strict** — the External Creative Agency cannot import/export data or send emails; Sales Users cannot send list emails.
10. **IP Warming applies** if sending volume exceeds 100,000 emails/month from a dedicated IP.

---

## 6. Testing Philosophy

> **Rule: Every feature gets a test flow before it ships.**

A test flow is a structured checklist in `test-flows/TF-NN-*.md` that verifies a feature end-to-end. When working on SFAE custom code or form features:

1. **Build the feature** in `test-pages/02-sfae-source.html` (or a new test page)
2. **Write the test flow** (`test-flows/TF-NN-*.md`) before calling the feature done
3. **Run the test flow manually** on `sfae-forms.jjlo.app` (HTTPS, real environment)
4. **Deploy to SFAE production** only after the test flow passes

### Test Flow Index (current)

| ID | Feature | Status |
|---|---|---|
| TF-01 | iFrame Embed & Rendering | ✅ Ready |
| TF-02 | URL Parameter Injection | ✅ Ready |
| TF-03 | SFAE Dev Toolbar | ✅ Ready |
| TF-04 | fillPardotField & Hidden Fields | ✅ Ready |
| TF-05 | GDPR Consent Timestamps | ✅ Ready |
| TF-06 | IP Address Capture (ipify) | ✅ Ready |
| TF-07 | Support Routing (supportData) | ✅ Ready |
| TF-08 | Autoresponder Trigger | 🔜 Planned |
| TF-09 | Form Naming Convention Validator | 📋 Backlog |
| TF-10 | Master Form Duplication Flow | 📋 Backlog |

### Custom Code Sections in `02-sfae-source.html`

| Line | Section | Purpose |
|---|---|---|
| L62 | `#pardot-form` CSS | Form styling, dark/light theme, custom dropdowns, sprite icons |
| L1447 | Dev toolbar URL params table | Editable URL params incl. QUA_TRA_Interest_in_Product_Cat/_Secondary |
| L1531 | `supportData` JSON | Phone/email routing by country × product |
| L1609 | Hidden split inputs | `hidden-prod-cat-main` / `hidden-prod-cat-secondary` (⚠️ name TBD) |
| L2197 | `closeAllDropdowns()` | Custom dropdown helper |
| L2208 | `updateBanner()` | Support phone/email banner logic driven by supportData |
| L2400 | Product Cat split logic | Splits selected code → `_Cat` + `_Cat_Secondary` on every selection |
| L3665 | `fillPardotField()` | Hidden field auto-fill helper |
| L3675 | GDPR timestamps | `CONS_registration_gdpr_timestamp` + commercial email timestamp |
| L3679 | `CONS_user_agent` | Browser/OS string capture |
| L3698 | `CONS_page_URL` | Page URL from `?parent_url=` param or `document.referrer` |
| L3703 | `CONS_exact_form_version` | ⚠️ Currently `window.location.href` — should be hardcoded form ID |
| L3722 | `CONS_IP_address` | Async public IP fetch via ipify |

---

## 7. Known Limitations (as of 2026-06-01)

- **SFAE Canvas IFrame**: The Pardot UI inside Salesforce Lightning is rendered in a cross-origin Canvas iframe — direct DOM/JavaScript access is blocked. Reading live SFAE data requires either the Google Drive MCP (if exported to Sheets), Pardot REST API, or screen-reading via Chrome screenshot.
- **Forms inventory completeness**: The current `forms-inventory.md` covers ~170 forms from the Google Sheets export. Forms added after 2026-05-18 are not reflected until the next sync.
- **No write access to SFAE**: The agent can read and document but cannot create or modify forms, campaigns, or prospects in SFAE directly (no API credentials configured).
- **Scoring thresholds**: The exact MQL threshold score (>100) and grading scale (A–F) are documented; actual automation rule configurations per country have not been mapped.

---

## 8. Open Questions / Areas to Evolve

### Blocking / High Priority
- [ ] **⚠️ Pardot IDs for hidden split fields** — `QUA_TRA_Interest_in_Product_Cat` + `_Secondary` hidden inputs in `02-sfae-source.html` have placeholder `name` attrs. Create fields in SFAE, then update. See `PDD/plan.md §2.3`.
- [ ] **⚠️ Icon sprite to Pardot** — `icons-sprite.png` must be uploaded to Pardot Files; replace `SPRITE_URL_HERE` in `sprite.css`; paste CSS into SFAE "Above Form Code".
- [ ] **Autoresponder test**: Complete TF-08 with a real form submission + email verification.
- [ ] **`CONS_exact_form_version`** — currently `window.location.href`; should be a hardcoded form ID string (e.g. `DE-C01-F03-v1`). See `PDD/plan.md §2.4`.

### Medium Priority
- [ ] **Master form architecture**: Build `DM| C01-F01--all | MASTER Contact Form ALLFIELDS` in SFAE — see TF-10.
- [ ] **Naming validator tool**: Build `/tools/naming-validator.html` — see TF-09.
- [ ] **Field renames pending in SFAE**: `ProjectDetail` (Branche) → `QUA_TRA_Interest_in_Vertical`; confirm when renamed and update form HTML class + JS selectors.
- [ ] **New SFAE fields to add**: `QUA_TRA_Interest_in_Brand`, `QUA_TRA_Interest_in_Product`, `QUA_TRA_Interest_in_Solution` — not yet in DE form, pending SFAE creation.
- [ ] Document FL4-pro layout template fully (field mappings, section descriptions, update guide).

### Lower Priority
- [ ] Map each country's active Preference Center lists and which communication types they cover.
- [ ] Define per-country scoring adjustments (if any differ from the global model).
- [ ] Document the Routing Matrix structure (country + territory/zip + product cluster mappings).
- [ ] Capture the full list of automation rules and engagement programs currently live.
- [ ] Define the agent's action scope: read-only audit vs. write/create operations in SFAE.
- [ ] Establish a refresh cadence for `forms-inventory.md` (weekly? triggered on new form creation?).
- [ ] Add `sfae-forms.jjlo.app` domain verification to CI: after each deploy, smoke-test that the index page loads and links to both test pages work.