consumer-goods-tpe-dashboard-custom-kpi-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Customize TPE Dashboard KPIs

自定义TPE仪表盘KPI

Headlessly clones the base TPE Analytics semantic-model parameters, visualizations, and dashboards under a customer-chosen suffix, so a customer's own KPI measure codes appear on the Promotion/Tactic Analysis dashboards without ever mutating the shipped base model. Driven entirely by

sf

CLI + REST against an already-authenticated org. Requires

consumer-goods-tpe-dashboard-configure

to have already installed the TPE Analytics app and the Extended TPM Analytics SDM — this skill never installs those, only customizes on top of them.

Persona: a Salesforce TPM System Admin customizing TPE dashboards for their org's own KPIs.

There is no native "clone" endpoint for any of the three artifact types this skill touches (semantic-model parameters, visualizations, dashboards) — every clone is the same three-step pattern: GET the base artifact, deep-copy its JSON and apply overrides, POST the copy as a new artifact. Base-model artifacts are never mutated in place.

在不依赖界面的情况下，以客户选定的后缀克隆基础TPE Analytics语义模型参数、可视化组件和仪表盘，使客户自有KPI度量代码显示在促销/策略分析仪表盘上，且不会修改已交付的基础模型。完全通过

sf

CLI + REST API对已认证的组织进行操作。要求

consumer-goods-tpe-dashboard-configure

已安装TPE Analytics应用和Extended TPM Analytics SDM——本技能不会安装这些组件，仅在其基础上进行自定义。

角色：Salesforce TPM系统管理员，为其组织自有KPI自定义TPE仪表盘。

本技能涉及的三类工件（语义模型参数、可视化组件、仪表盘）均无原生“克隆”端点——所有克隆操作均遵循相同的三步模式：GET基础工件、深度复制其JSON并应用覆盖配置、POST副本作为新工件。基础模型工件永远不会被原地修改。

The 5 KPI slots — two artifacts per slot, not one

5个KPI插槽——每个插槽对应两个工件，而非一个

The shipped Extended TPM Analytics SDM exposes 5 generic List-type parameters that the standard dashboards bind to: Promotion Measure 1-3 (

Promotion_Measure_{1,2,3}_prm

_value

) and Tactic Measure 1-2 (

Tactic_Measure_{1,2}_prm

_clc

). Never assume Tactic mirrors Promotion's
_value
naming — resolve both slots' measurement apiNames from the live model per slot, never by pattern. See

references/payload-shapes.md

for the confirmed apiNames and JSON shapes.

Each slot is two SDM artifacts: the parameter (

*_prm

, a

List

type with

allowedValues

menu entries and a

defaultValue

) and the calculated measurement (what visualizations actually query; its

expression

links back to the parameter by apiName). Customizing a slot means cloning both — the parameter gets the customer's KPI as a new/selected

allowedValues

entry, and the measurement's

expression

is rewritten to reference the cloned parameter's new apiName.

This skill always produces clones of all 5 slots (10 artifacts), whether or not a given slot has a requested override — an unmentioned slot is still cloned as an exact copy of the base artifacts (only apiName/label suffixed).

Two override modes per slot (see

references/procedure.md

for exact

--overrides

shapes):

APPEND mode (default): upserts one
```
{measureCode, displayName}
```
entry into the base menu by measure code — same code relabels in place, new code appends.
REPLACE mode: a full
```
allowedValues
```
array supplied by the customer becomes the entire menu.

Either way this skill assumes the underlying measure data is already populated by prior

setup-rtr-datacloud-export

/data-kit setup — it does not create that underlying data itself.

已交付的Extended TPM Analytics SDM暴露了5个通用的列表类型参数，供标准仪表盘绑定：Promotion Measure 1-3（

Promotion_Measure_{1,2,3}_prm

_value

）和Tactic Measure 1-2（

Tactic_Measure_{1,2}_prm

_clc

）。切勿假设Tactic参数的命名与Promotion的
_value
模式一致——需根据每个插槽从实时模型中解析其度量apiName，切勿依赖固定模式。请查看

references/payload-shapes.md

获取已确认的apiName和JSON结构。

每个插槽对应两个SDM工件：参数（

*_prm

，一种带有

allowedValues

菜单选项和

defaultValue

的

List

类型）和计算度量（可视化组件实际查询的对象；其

expression

通过apiName关联回参数）。自定义插槽意味着同时克隆这两个工件——参数会将客户的KPI作为新的/选中的

allowedValues

条目添加，而度量的

expression

会被重写为引用克隆后参数的新apiName。

无论某个插槽是否有请求的覆盖配置，本技能始终会生成**全部5个插槽（10个工件）**的克隆——未提及的插槽仍会被克隆为基础工件的精确副本（仅apiName/标签添加后缀）。

每个插槽支持两种覆盖模式（有关

--overrides

的精确结构，请查看

references/procedure.md

）：

追加模式（默认）：按度量代码将一个
```
{measureCode, displayName}
```
条目插入基础菜单——相同代码会原地重命名，新代码则追加到菜单中。
替换模式：客户提供的完整
```
allowedValues
```
数组将成为整个菜单。

无论哪种模式，本技能均假设底层度量数据已通过之前的

setup-rtr-datacloud-export

/data-kit设置完成填充——本技能不会自行创建这些底层数据。

Inputs to collect first

需先收集的输入信息

Ask before starting. Do not guess.

TPM System Admin username — verify connectivity via
```
node ./scripts/sf-rest.js org-status --target-org <username>
```
(never
```
sf org display --json
```
directly — that leaks a live
```
accessToken
```
). Non-
```
Connected
```
⇒ stop, ask the user to log in.
Dry-run? — offer by default.
Suffix — distinguishes cloned metadata from the base model (e.g.
```
Cust
```
). Suggest
```
Cust
```
as a default. Applied to every new artifact's API name/label — never reuse a base-model API name.
Per-measure overrides — walk the customer through the 5 measures via
```
AskUserQuestion
```
, batched by dashboard (Promotion Measure 1-3 in one call, Tactic Measure 1-2 in a second call — never all 5 in one call, the tool caps at 4 questions per call), never using the internal term "slot" toward the user. Never ask a separate plain free-text follow-up question to collect the list — a plain-text message doesn't block the next tool call, so if you fire another
```
AskUserQuestion
```
for the next measure before the customer's reply lands, their answer races ahead and lands on the wrong question. Instead, collect the full list inside the same blocking question: every
```
AskUserQuestion
```
question automatically gets a "Type Something" free-text option appended after your listed options — no need to add your own placeholder option for it, and never rely on a bare canned option label (e.g. "Replace with custom list") to actually carry the list, since selecting it only returns that label text, not the customer's data. Word the question and its second option's description to point the customer at "Type Something" explicitly, e.g. option 2 = "Replace with custom list", description: "Select Type Something (last option, below) and type comma-separated
```
{measureCode}: {displayName}
```
pairs, plus which one should be default." A menu can have more than one entry — always collect the full array, never just one pair (a single-pair answer is still an array of length 1). This collected array maps directly to that slot's REPLACE-mode override (
```
{"allowedValues":[...], "defaultValue": "<first displayName unless the customer says otherwise>"}
```
) — see
```
references/procedure.md
```
's override-mode shapes. Confirm the resolved list per measure back to the user before Phase 0.
Which dashboards to produce — Promotion Analysis, Tactic Analysis, or both. Default to both if any measure on either has an override; otherwise ask explicitly.

开始前请询问用户，切勿猜测。

TPM系统管理员用户名——通过
```
node ./scripts/sf-rest.js org-status --target-org <username>
```
验证连通性（切勿直接使用
```
sf org display --json
```
——该命令会泄露有效的
```
accessToken
```
）。若状态非
```
Connected
```
，则停止操作，请用户登录。
是否试运行？——默认提供该选项。
后缀——区分克隆后的元数据与基础模型（例如
```
Cust
```
）。建议默认使用
```
Cust
```
。该后缀会应用于每个新工件的API名称/标签——切勿重复使用基础模型的API名称。
按度量的覆盖配置——通过
```
AskUserQuestion
```
引导客户完成5个度量的配置，按仪表盘分批进行（一次收集Promotion Measure 1-3的配置，第二次收集Tactic Measure 1-2的配置——切勿一次性收集全部5个，工具限制每次调用最多4个问题），切勿向用户使用内部术语“插槽”。切勿单独通过纯文本后续问题收集列表——纯文本消息不会阻止下一次工具调用，若在客户回复前触发另一个
```
AskUserQuestion
```
以收集下一个度量的配置，客户的回复可能会错位到错误的问题上。相反，应在同一个阻塞性问题中收集完整列表：每个
```
AskUserQuestion
```
问题会自动在您列出的选项后追加“输入内容”的纯文本选项——无需自行添加占位符选项，且切勿仅依赖预设选项标签（例如“替换为自定义列表”）来传递客户数据，因为选择该选项仅会返回标签文本，而非客户的数据。请措辞问题及其第二个选项的描述，明确引导客户使用“输入内容”选项，例如选项2 = “替换为自定义列表”，描述：“选择输入内容（下方最后一个选项），并输入逗号分隔的
```
{measureCode}: {displayName}
```
对，同时指定默认选项。” 菜单可包含多个条目——始终收集完整数组，切勿仅收集一对（单个条目对仍需作为长度为1的数组）。收集到的数组将直接映射到该插槽的替换模式覆盖配置（
```
{"allowedValues":[...], "defaultValue": "<若客户未另行指定则为第一个显示名称>"}
```
）——请查看
```
references/procedure.md
```
中的覆盖模式结构。在第0阶段开始前，请向用户确认每个度量的解析后列表。
要生成的仪表盘——促销分析仪表盘、策略分析仪表盘，或两者都要。若任一仪表盘上的度量有覆盖配置，则默认生成两者；否则请明确询问用户。

How it works — phase list

工作流程——阶段列表

Namespace detection — resolve
```
NS
```
via
```
sf package installed list
```
for consistency with sibling skills, but never apply it to any
```
/services/data/...
```
path (those are never namespaced).
Phase 0 — Preflight & discovery: verify connectivity, pin API version
```
v67.0
```
, resolve the installed app + asset ids (model, both dashboards, visualizations) by walking the app's asset list — never hardcode an id. Block with a pointer to
```
consumer-goods-tpe-dashboard-configure
```
if prerequisites are missing. Full detail:
```
references/procedure.md
```
.
Phase 1 — Resolve the 5-slot plan: deep-copy each base parameter/measurement with overrides applied, print the plan, get explicit user confirmation before any writes.
Phases 2-4 — Clone parameters, measurements, visualizations, dashboards: run
```
scripts/clone-tpe-dashboards.js
```
(preferred over hand-rolling individual REST calls) — see
```
references/procedure.md
```
for the full CLI usage, override-mode payload shapes, and every real-write gotcha the script encodes (label uniqueness, dataSource
```
.type
```
stripping rules, cloning every KPI-bound visualization not just one "designated" viz, cosmetic label-text replacement, upsert-by-measure-code).
Phase 5 — Verify: GET every created artifact back and confirm parameters, measurements, visualizations, and dashboards all correctly reference the new suffixed clones, never a base apiName. Full detail:
```
references/procedure.md
```
.

命名空间检测——通过
```
sf package installed list
```
解析
```
NS
```
，以保持与同类技能的一致性，但切勿将其应用于任何
```
/services/data/...
```
路径（这些路径永远不会带有命名空间）。
第0阶段——预检与发现：验证连通性，固定API版本为
```
v67.0
```
，通过遍历应用的资产列表解析已安装的应用+资产ID（模型、两个仪表盘、可视化组件）——切勿硬编码ID。若缺少先决条件，则阻止操作并指向
```
consumer-goods-tpe-dashboard-configure
```
。详细信息请查看
```
references/procedure.md
```
。
第1阶段——确定5个插槽的计划：深度复制每个基础参数/度量并应用覆盖配置，打印计划，在执行任何写入操作前获取用户的明确确认。
第2-4阶段——克隆参数、度量、可视化组件、仪表盘：运行
```
scripts/clone-tpe-dashboards.js
```
（优先于手动编写单个REST调用）——请查看
```
references/procedure.md
```
获取完整的CLI用法、覆盖模式负载结构，以及脚本包含的所有实际写入注意事项（标签唯一性、dataSource
```
.type
```
剥离规则、克隆所有绑定KPI的可视化组件而非仅“指定”组件、标签文本的美化替换、按度量代码更新插入）。
第5阶段——验证：重新获取所有已创建的工件，确认参数、度量、可视化组件和仪表盘均正确引用新的带后缀克隆件，而非基础apiName。详细信息请查看
```
references/procedure.md
```
。

Key rules (see

references/procedure.md

for the complete list)

核心规则（完整规则列表请查看

references/procedure.md

）

Never mutate a base-model artifact — every write is a new POST of a suffixed copy.
Never create anything without explicit user go-ahead on the Phase 1 plan.
Always produce all 5 slots' worth of clones, even with zero overrides.
Never leave a cloned measurement's
```
expression
```
referencing a base parameter apiName.
Never hardcode an artifact id, api-name, or namespace across orgs.
Never assume only one visualization per dashboard needs cloning — clone every widget whose viz references a slot measurement.

切勿修改基础模型工件——所有写入操作均为带后缀副本的新POST请求。
未获得用户对第1阶段计划的明确批准前，切勿创建任何内容。
始终生成全部5个插槽的克隆件，即使没有任何覆盖配置。
切勿让克隆后的度量的
```
expression
```
引用基础参数apiName。
切勿跨组织硬编码工件ID、api名称或命名空间。
切勿假设每个仪表盘仅需克隆一个可视化组件——克隆所有引用插槽度量的小部件对应的可视化组件。

Reference map

参考文档映射

Topic	File
Full phase-by-phase procedure, script CLI usage, all real-write gotchas, complete Rules list	`references/procedure.md`
Confirmed live JSON shapes for parameters, calculated measurements, visualizations, dashboards, and POST body shapes for all 4 create endpoints	`references/payload-shapes.md`
Org REST helper (strips `accessToken` ; `org-status` subcommand)	`scripts/sf-rest.js`
Deterministic driver for Phases 2-4	`scripts/clone-tpe-dashboards.js`

主题	文件
完整的分阶段流程、脚本CLI用法、所有实际写入注意事项、完整规则列表	`references/procedure.md`
参数、计算度量、可视化组件、仪表盘的已确认实时JSON结构，以及所有4个创建端点的POST请求体结构	`references/payload-shapes.md`
组织REST助手（剥离 `accessToken` ； `org-status` 子命令）	`scripts/sf-rest.js`
第2-4阶段的确定性驱动脚本	`scripts/clone-tpe-dashboards.js`

Report

报告

At the end of a run, give the user a structured status per phase (0-5): pass / blocked / pending, with the specific blocking reason where applicable, and the final list of created artifacts (slot → new parameter, base viz → new viz, base dashboard → new dashboard). Call out anything skipped due to dry-run or a declined confirmation.

When invoked via delegation (the calling skill used the

Skill

tool to reach this file, rather than the user directly — e.g.

consumer-goods-tpe-dashboard-configure

's customization step): this report is an intermediate result. Return it to the calling skill and let it continue with its own report — do not present this as the final answer to the user unless this skill was invoked standalone.

运行结束后，向用户提供按阶段（0-5）划分的结构化状态：通过/阻塞/待处理，并注明具体的阻塞原因（如适用），以及最终创建的工件列表（插槽→新参数、基础可视化组件→新可视化组件、基础仪表盘→新仪表盘）。请指出因试运行或用户拒绝确认而跳过的任何操作。

当通过委托调用时（调用技能使用

Skill

工具访问本文件，而非用户直接调用——例如

consumer-goods-tpe-dashboard-configure

的自定义步骤）：本报告为中间结果。请将其返回给调用技能，由调用技能继续生成自己的报告——除非本技能是独立调用的，否则请勿将此报告作为最终答案呈现给用户。",

consumer-goods-tpe-dashboard-custom-kpi-configure

Original

Translation

Customize TPE Dashboard KPIs

自定义TPE仪表盘KPI

The 5 KPI slots — two artifacts per slot, not one

5个KPI插槽——每个插槽对应两个工件，而非一个

Inputs to collect first

需先收集的输入信息

How it works — phase list

工作流程——阶段列表

Key rules (see
`references/procedure.md`
for the complete list)

核心规则（完整规则列表请查看
`references/procedure.md`
）

Reference map

参考文档映射

Report

报告

consumer-goods-tpe-dashboard-custom-kpi-configure

Original

Translation

Customize TPE Dashboard KPIs

自定义TPE仪表盘KPI

The 5 KPI slots — two artifacts per slot, not one

5个KPI插槽——每个插槽对应两个工件，而非一个

Inputs to collect first

需先收集的输入信息

How it works — phase list

工作流程——阶段列表

Key rules (see references/procedure.md for the complete list)

核心规则（完整规则列表请查看references/procedure.md）

Reference map

参考文档映射

Report

报告

Key rules (see
`references/procedure.md`
for the complete list)

核心规则（完整规则列表请查看
`references/procedure.md`
）