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

TPE ダッシュボードの KPI をカスタマイズする

ベースとなる TPE Analytics のセマンティックモデルのパラメーター、ビジュアライゼーション、ダッシュボードを、顧客が指定したサフィックスを付けてヘッドレスで複製します。これにより、出荷時のベースモデルを一切変更することなく、顧客独自の KPI 測定コードを Promotion/Tactic Analysis ダッシュボードに表示できます。認証済みの組織に対して sf CLI と REST のみを使用して実行します。TPE Analytics アプリと Extended TPM Analytics SDM のインストールには、事前に consumer-goods-tpe-dashboard-configure が実行されている必要があります。このスキルはそれらをインストールせず、既存のものをカスタマイズするだけです。

ペルソナ：組織独自の KPI に合わせて TPE ダッシュボードをカスタマイズする Salesforce TPM システム管理者。

このスキルが扱う 3 種類のアーティファクト（セマンティックモデルのパラメーター、ビジュアライゼーション、ダッシュボード）には、ネイティブの「複製」エンドポイントがありません。複製にはすべて、GET でベースアーティファクトを取得し、その JSON をディープコピーしてオーバーライドを適用し、コピーを新しいアーティファクトとして POST する、同じ 3 ステップのパターンを使用します。ベースモデルのアーティファクトをその場で変更することはありません。

5 つの KPI スロット — 各スロットに 1 つではなく 2 つのアーティファクト

出荷時の Extended TPM Analytics SDM は、標準ダッシュボードがバインドする汎用の List 型パラメーターを 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 をそれぞれ特定し、パターンから推測しないでください。確認済みの apiName と JSON 構造については、references/payload-shapes.md を参照してください。

各スロットは 2 つの SDM アーティファクトで構成されます。パラメーター（*_prm。allowedValues メニュー項目と defaultValue を持つ List 型）と、計算済み測定（ビジュアライゼーションが実際にクエリするもの。expression が apiName によってパラメーターにリンクします）です。スロットをカスタマイズするには両方を複製します。パラメーターには顧客の KPI を新しい、または選択済みの allowedValues 項目として追加し、測定の expression は複製したパラメーターの新しい apiName を参照するように書き換えます。

このスキルは、指定されたオーバーライドがあるかどうかにかかわらず、**5 つのスロットすべて（10 個のアーティファクト）**の複製を常に作成します。指定されていないスロットも、ベースアーティファクトの完全なコピーとして複製されます（apiName/ラベルにサフィックスが付くだけです）。

スロットごとに 2 つのオーバーライドモードがあります（--overrides の正確な形式については references/procedure.md を参照してください）。

• APPEND モード（デフォルト）：測定コードを基準に、{measureCode, displayName} 項目を 1 つベースメニューにアップサートします。同じコードならその項目のラベルを変更し、新しいコードなら追加します。
• REPLACE モード：顧客が指定した allowedValues 配列でメニュー全体を置き換えます。

いずれの場合も、このスキルでは、基盤となる測定データが事前の setup-rtr-datacloud-export／データキットのセットアップによってすでに投入されていることを前提とします。基盤となるデータ自体は作成しません。

最初に確認する入力

開始前に質問します。推測しないでください。

1. TPM システム管理者のユーザー名 — 次のコマンドで接続を確認します。 node ./scripts/sf-rest.js org-status --target-org <username>（直接 sf org display --json を実行してはいけません。実際の accessToken が漏えいします）。Connected 以外の場合は作業を中止し、ユーザーにログインを依頼します。
2. ドライランにしますか？ — デフォルトで提案します。
3. サフィックス — クローンしたメタデータをベースモデルと区別するために使います（例：Cust）。デフォルトとして Cust を提案します。新しく作成するすべてのアーティファクトの API 名／ラベルに適用します。ベースモデルの API 名を再利用してはいけません。
4. 測定項目ごとの上書き — AskUserQuestion を使い、ダッシュボードごとに分けて（Promotion Measure 1～3 は1回目、Tactic Measure 1～2 は2回目。ツールは1回あたり最大4問のため、5問すべてを一度に尋ねてはいけません）、5つの測定項目についてユーザーと確認します。ユーザーには内部用語の「スロット」を使ってはいけません。一覧を集めるための、単独の自由入力の追加質問は絶対にしてはいけません — 通常のテキストメッセージでは次のツール呼び出しがブロックされないため、ユーザーの回答が届く前に次の測定項目について AskUserQuestion を実行すると、回答が別の質問に紐付いてしまいます。その代わり、同じブロッキング質問の中で一覧全体を集めます。各 AskUserQuestion の質問には、指定した選択肢の後に「Type Something」という自由入力の選択肢が自動で追加されます。独自のプレースホルダー選択肢を追加する必要はありません。また、一覧を実際に入力してもらうために、「カスタムリストに置き換える」のような定型の選択肢ラベルだけに頼ってはいけません。それを選ぶと、ユーザーのデータではなく、そのラベルのテキストだけが返されるためです。質問文と2番目の選択肢の説明で、「Type Something」を明示するよう促します。例：選択肢2 =「カスタムリストに置き換える」、説明：「Type Something（一番下の最後の選択肢）を選び、カンマ区切りの {measureCode}: {displayName} ペアと、デフォルトにする項目を入力してください。」メニューには複数の項目を指定できます。必ず配列全体を集め、ペアを1つだけ集めてはいけません（1ペアの回答でも、長さ1の配列になります）。収集した配列は、そのまま該当するスロットの REPLACE モードの上書きに対応します（{"allowedValues":[...], "defaultValue": "<first displayName unless the customer says otherwise>"}）。上書きモードの形式については references/procedure.md を参照してください。フェーズ0の前に、解決した各測定項目の一覧をユーザーに確認します。
5. 作成するダッシュボード — Promotion Analysis、Tactic Analysis、または両方。いずれかのダッシュボードの測定項目に上書きがある場合は、デフォルトで両方を選択します。それ以外の場合は、必ず明示的に尋ねます。

仕組み — フェーズ一覧

1. 名前空間の検出 — 同じ階層のスキルとの一貫性を保つため、sf package installed list を使用して NS を解決します。ただし、/services/data/... のパスには適用しません（これらのパスに名前空間は付きません）。
2. フェーズ 0 — 事前確認と検出：接続を確認し、API バージョンを v67.0 に固定して、アプリのアセット一覧をたどりながら、インストール済みアプリとアセット（モデル、両方のダッシュボード、ビジュアライゼーション）の ID を解決します。ID をハードコードしてはいけません。前提条件が満たされていない場合は、consumer-goods-tpe-dashboard-configure を案内して処理を中断します。詳細：references/procedure.md。
3. フェーズ 1 — 5 スロットのプランを解決：各ベースのパラメーター／計測値にオーバーライドを適用してディープコピーし、プランを表示してから、書き込みを行う前にユーザーから明示的な確認を得ます。
4. フェーズ 2～4 — パラメーター、計測値、ビジュアライゼーション、ダッシュボードのクローン作成：個別の REST 呼び出しを手動で行うよりも、scripts/clone-tpe-dashboards.js の実行を推奨します。CLI の使用方法、オーバーライドモードのペイロード形式、スクリプトに組み込まれた実際の書き込み時の注意点（ラベルの一意性、dataSource の .type を削除するルール、「指定された」ビジュアライゼーションだけでなく、KPI に紐づくすべてのビジュアライゼーションをクローンすること、表示ラベルテキストの置換、計測コードによる upsert）については、references/procedure.md を参照してください。
5. フェーズ 5 — 検証：作成したすべてのアーティファクトを GET で取得し直し、パラメーター、計測値、ビジュアライゼーション、ダッシュボードがすべて、新しいサフィックス付きのクローンを正しく参照し、ベースの apiName を参照していないことを確認します。詳細：references/procedure.md。

主なルール（完全な一覧は references/procedure.md を参照）

• ベースモデルのアーティファクトは変更しないでください。書き込みはすべて、サフィックス付きコピーの新規 POST とします。
• フェーズ 1 のプランについてユーザーから明示的な承認を得る前に、何も作成しないでください。
• オーバーライドがなくても、5 スロット分のクローンをすべて作成してください。
• クローンした計測値の expression が、ベースのパラメーター apiName を参照したままにならないようにしてください。
• org 間でアーティファクト ID、api-name、名前空間をハードコードしないでください。
• ダッシュボードごとにクローンが必要なビジュアライゼーションは 1 つだけだと想定しないでください。スロットの計測値を参照する viz を持つすべてのウィジェットをクローンしてください。

リファレンスマップ

トピック	ファイル
フェーズごとの詳細な手順、スクリプトの CLI 使用方法、実際の書き込み時の注意点のすべて、ルールの完全な一覧	references/procedure.md
パラメーター、計算済み計測値、ビジュアライゼーション、ダッシュボードの確認済み実 JSON 形式、および 4 つの作成エンドポイントすべての POST 本文形式	references/payload-shapes.md
org REST ヘルパー（accessToken を除去、org-status サブコマンド）	scripts/sf-rest.js
フェーズ 2～4 用の決定論的ドライバー	scripts/clone-tpe-dashboards.js

レポート

実行の最後に、フェーズごと（0～5）のステータス（成功／ブロック／保留）と、該当する場合は具体的なブロック理由を構造化してユーザーに提示します。また、作成したアーティファクトの最終一覧（スロット → 新しいパラメーター、ベース viz → 新しい viz、ベースダッシュボード → 新しいダッシュボード）も提示します。ドライランまたは確認の辞退によりスキップしたものがあれば明記してください。

委任を通じて呼び出された場合（ユーザーが直接このファイルを呼び出したのではなく、呼び出し元のスキルが Skill ツールを使ってこのファイルを呼び出した場合。例：consumer-goods-tpe-dashboard-configure のカスタマイズ手順）：このレポートは中間結果です。呼び出し元のスキルに返し、そのスキルが独自のレポートを続けられるようにしてください。このスキルが単独で呼び出された場合を除き、ユーザーへの最終回答として提示しないでください。