From 206d13b80ded921225996470527015a7afa729a3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 6 Aug 2026 07:54:22 +0000 Subject: [PATCH] docs(automation): spell the merge-field example with this app's real names (#863) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Email templates" section illustrated merge fields with `{{Opportunity.Name}}` and `{{Account.Owner.Email}}` — Salesforce-style PascalCase naming nothing in this app, against AGENTS.md's name-parity rule (source = runtime = DB = URL = docs). HotCRM's objects are `crm_opportunity` and `crm_contact`; its fields are `name`, `owner_id`, `email`. The `{{path.to.value}}` syntax itself was correct and stays: spec 17.0.0-rc.3's `EmailTemplateDefinitionSchema` documents subject/body placeholders rendered against a per-send `data` payload, with variable names as snake_case or dotted paths. The replacement does not invent a payload shape. Whether a template reads `{{name}}`, `{{record.name}}` or `{{crm_opportunity.name}}` depends on the payload the caller passes to `sendTemplate()`, and this repo has no caller (`sendTemplate` / `email_template`: zero occurrences under `src/`). The bullet gives the real spellings, states that the root of the path is the sender's choice, and points authors at the template's own `variables` list. Three language files, one bullet each. Documentation only. --- .../automation-docs-merge-field-spelling.md | 35 +++++++++++++++++++ content/docs/administration/automation.mdx | 2 +- .../administration/automation.zh-Hans.mdx | 2 +- .../administration/automation.zh-Hant.mdx | 2 +- 4 files changed, 38 insertions(+), 3 deletions(-) create mode 100644 .changeset/automation-docs-merge-field-spelling.md diff --git a/.changeset/automation-docs-merge-field-spelling.md b/.changeset/automation-docs-merge-field-spelling.md new file mode 100644 index 000000000..010b9f601 --- /dev/null +++ b/.changeset/automation-docs-merge-field-spelling.md @@ -0,0 +1,35 @@ +--- +'hotcrm': patch +--- + +Spell the Automation page's merge-field example the way this app spells names, in +all three languages. The "Email templates" section on +`content/docs/administration/automation.mdx` (and its `.zh-Hans` / `.zh-Hant` +siblings) opened its bullet list with `{{Opportunity.Name}}` and +`{{Account.Owner.Email}}` — Salesforce-style PascalCase that names nothing here. +HotCRM's objects are `crm_opportunity` and `crm_contact`; its fields are `name`, +`owner_id`, `email`. AGENTS.md holds that parity as a hard rule — *the name in +source = the name at runtime = the name in DB = the name in URL = the name in +docs. No translation layer* — and the rest of the same page already keeps it +(`end_date`, `expiration_date`, `owner_id`). Only this bullet was borrowing +another product's vocabulary, which an admin authoring a template under +**Setup → Email Templates** would have copied into paths that resolve to nothing. + +The placeholder *syntax* was never the problem and is unchanged. +`EmailTemplateDefinitionSchema` in `@objectstack/spec` 17.0.0-rc.3 documents +subject and body as carrying simple `{{path.to.value}}` placeholders rendered +against a per-send `data` payload, and describes each declared variable's `name` +as "snake_case or dotted path". + +What the bullet deliberately does *not* do is invent a payload shape. Whether a +template reads `{{name}}`, `{{record.name}}` or `{{crm_opportunity.name}}` depends +on the `data` payload the caller passes to `sendTemplate()`, the caller decides +that shape, and this repo has no caller to measure it from — `sendTemplate` and +`email_template` have zero occurrences under `src/`, consistent with the compiled +artifact carrying no email-template metadata (#834). So the bullet now gives the +real spellings, says plainly that where the path is rooted is the sender's choice, +and points template authors at the template's own `variables` list rather than at +a shape nobody in this repo has exercised. + +Documentation only — one bullet per language file. No metadata, behaviour or field +changes. Fixes #863. diff --git a/content/docs/administration/automation.mdx b/content/docs/administration/automation.mdx index 12be1680b..dd562b6c1 100644 --- a/content/docs/administration/automation.mdx +++ b/content/docs/administration/automation.mdx @@ -119,7 +119,7 @@ Understanding this order helps debug *"why didn't my flow fire?"* questions. Most automation actions send email. Templates live in **Setup → Email Templates** and support: -- **Merge fields** — `{{Opportunity.Name}}`, `{{Account.Owner.Email}}`. +- **Merge fields** — `{{path.to.value}}` placeholders, rendered against the `data` payload passed on that send. Spell every segment the way HotCRM spells it — objects are `crm_opportunity` and `crm_contact`, fields are `name`, `owner_id`, `email` — never Salesforce-style `Opportunity.Name`. What the path is rooted at depends on the payload shape the sender passes, and this app ships no `sendTemplate()` caller to copy one from, so declare the names your template reads in its `variables` list and agree the shape with whoever sends the mail. - **Conditional blocks** — show only if a condition is true. - **HTML + plain text** versions. - **Attachments** — quote PDFs, contract PDFs. diff --git a/content/docs/administration/automation.zh-Hans.mdx b/content/docs/administration/automation.zh-Hans.mdx index fffde1b9e..5c647f643 100644 --- a/content/docs/administration/automation.zh-Hans.mdx +++ b/content/docs/administration/automation.zh-Hans.mdx @@ -119,7 +119,7 @@ HotCRM 内置的 **商机审批** 流程串联两个 approval 节点实现分级 大多数自动化操作会发送电子邮件。模板位于 **设置 → 电子邮件模板**，并支持： -- **合并字段** —— `{{Opportunity.Name}}`、`{{Account.Owner.Email}}`。 +- **合并字段** —— `{{path.to.value}}` 占位符，按每次发送传入的 `data` 载荷渲染。路径的每一段都写 HotCRM 自己的拼写 —— 对象是 `crm_opportunity`、`crm_contact`，字段是 `name`、`owner_id`、`email` —— 而不是 Salesforce 式的 `Opportunity.Name`。路径从哪一层写起，取决于发送方传入的载荷形状；本应用没有任何 `sendTemplate()` 调用方可供照抄，所以请把模板要读的名字声明在它的 `variables` 列表里，并与发送方约定好载荷形状。 - **条件块** —— 仅在条件为真时显示。 - **HTML + 纯文本** 版本。 - **附件** —— 报价 PDF、合同 PDF。 diff --git a/content/docs/administration/automation.zh-Hant.mdx b/content/docs/administration/automation.zh-Hant.mdx index c058cfab0..596b57a2d 100644 --- a/content/docs/administration/automation.zh-Hant.mdx +++ b/content/docs/administration/automation.zh-Hant.mdx @@ -119,7 +119,7 @@ HotCRM 內建的 **商機審批** 流程串聯兩個 approval 節點實作分級 大多數自動化操作會傳送電子郵件。範本位於 **設定 → 電子郵件範本**，並支援： -- **合併欄位** —— `{{Opportunity.Name}}`、`{{Account.Owner.Email}}`。 +- **合併欄位** —— `{{path.to.value}}` 佔位符，依每次傳送傳入的 `data` 酬載渲染。路徑的每一段都寫 HotCRM 自己的拼寫 —— 物件是 `crm_opportunity`、`crm_contact`，欄位是 `name`、`owner_id`、`email` —— 而不是 Salesforce 式的 `Opportunity.Name`。路徑從哪一層寫起，取決於傳送方傳入的酬載形狀；本應用沒有任何 `sendTemplate()` 呼叫方可供照抄，因此請把範本要讀取的名稱宣告在它的 `variables` 清單裡，並與傳送方約定好酬載形狀。 - **條件區塊** —— 僅在條件為真時顯示。 - **HTML + 純文字** 版本。 - **附件** —— 報價 PDF、合約 PDF。