sales-call-scoring-configure

セールスコールのスコアリング — 設定

Salesforce 組織でコールコーチング（別名：AI コールスコアリング／コーチングコンピテンシー）を 設定します。組織の現在の状態を検出し、権限のある依存機能を有効にしてから、SOAP Metadata API を使用して ECICallScoringEnabled 組織設定を切り替えます。

対象範囲

対象

• ECI が有効な組織のみ。 このスキルは ECI（Einstein Conversation Insights）系統の組織をサポートします（スパイクの対象範囲：MVP では ECI のみ）。
• PRD で対象としている 4 つの組織状態のうち、組織がどの状態にあるかを検出します。
• オフの場合、Einstein Generative AI Platform を有効にします（PRD で許可された依存機能）。
• SOAP Metadata API v68 を使用して、enableECICallScoring を true に切り替えます。
• 変更が反映されたことを確認します。
• 冪等です。状態 3 と 4（すでに有効）では、問題なく終了します。

対象外

• River Rush／Momentum の検出。 この系統が稼働するまで保留します。詳しくは「重要な考慮事項」を参照してください。現時点では、Momentum のみの組織は、他の ECI オフの組織と区別されません。Phase 3 では Momentum 固有のメッセージではなく、汎用的な「ECI が有効ではありません」というメッセージが表示されます。
• ECI または Momentum 自体の有効化。 PRD で明示的に対象外とされています。このスキルは ECI を検出し、Setup から有効にするよう管理者に案内します。
• ライセンスのプロビジョニング。 基本ライセンス（Agentforce for Sales、ECI ライセンス）が不足している場合は、アカウントチームにチケットを申請する必要があります。
• コンピテンシーの CRUD。 同じスキル内の別スクリプトで処理します。以下の「コンピテンシー CRUD ワークフロー」（§S3-§S10）と「実行順序」マトリックスを参照してください。

前提条件

1. sf CLI で認証済み — sf org login web --alias <org-alias>。
2. ECI 系統のライセンスがあり、有効になっていること：ConversationPilot 組織権限（Phase 0 の購入ゲート）と enableCallCoaching 設定（Phase 1 の ConversationPilotPref 設定）。（River Rush／Momentum は同じサーバー側ゲートで制御される別の系統ですが、現時点ではこのスキルでは確認しません。詳しくは「重要な考慮事項」を参照してください。）
3. 組織のポッドでサイトゲート com.salesforce.eci.callScoringEnabled が開いていること（RelEng が管理し、管理者は切り替えできません）。

Einstein GenAI Platform はソフトな前提条件です。無効の場合、このスキルが自動的に有効にします。

確認事項

管理者に尋ねてください：対象の組織エイリアスは何ですか？サンドボックスの更新シナリオですか？（この設定には disableOnSandboxCopy=true が指定されているため、更新のたびに再度切り替える必要があります。これは正常な動作であり、失敗ではありません。）

管理者とのコミュニケーションガイドライン

重要：このスキルの対象は開発者ではなく、管理者です。各ルールの根拠を含む 13 項目の完全な仕様は references/admin-communication.md にあります。このスキルで最初に応答する前に確認してください。特に重要なルールの概要は次のとおりです。

1. すべての bash コマンドをバックグラウンドで実行する（run_in_background: true）。
2. エンティティ名ではなく管理者向けの用語を使う — 「コールコーチング」「コーチングコンピテンシー」「有効／無効」を使います。ユーザーとの会話の主要なテキストでは、EnablementCompetencyDef、enableECICallScoring、EvaluationInstructions、SourceCompetencyTemplate は使いません。
3. 技術的な詳細は表示しない — レコード ID、DeveloperName、Template の列挙値キー、HTTP コード、SOAP 応答、curl／jq の内部情報、スクリプトのパス、フェーズ番号は含めません。例外は S9 の検証用 Markdown テーブルです（references/competency-crud.md §S9 を参照）。
4. 自動的に次へ進む — スクリプトに Next: <script> と表示されたら、確認を求めず、同じターン内で実行します。例外：状態 3 → ルール #13。
5. OOTB かカスタムかを一度だけ確認する — 初回のコンピテンシー設定時（状態 3 で、意図が明確に指定されていない場合）に、install-ootb-competencies.sh --list を表示し、管理者に選択してもらいます。このスキルで、書き込み前に Claude が確認するのはこのチェックポイントだけです。
6. 冪等性は簡潔に伝える — すでに有効／インストール済みの場合は、簡潔に伝えて先へ進みます。

エラーの伝え方、結果と手順の報告、S9 の例外の根拠を含む 13 項目の完全な仕様については、references/admin-communication.md を参照してください。

ワークフロー

フェーズ 0 — 認証

すべてのスクリプトが読み込む共通の scripts/shared/auth.sh ヘルパー （resolve_org_auth "$ORG_ALIAS"）を使って、組織の認証情報を解決します。 このヘルパーは、エイリアスの形式を検証し、sf org display を呼び出して instanceUrl と accessToken を取得します（CLI がトークンを 伏せている場合は、sf org auth show-access-token にフォールバックします）。 HTTPS ではないインスタンス URL は拒否し、組織に到達できない場合や トークンを抽出できない場合は、sf org login web --alias <alias> の 明示的な指示とともにフェイルクローズします。ACCESS_TOKEN／INSTANCE_URL が同じエイリアス用にすでにエクスポートされている場合（たとえば、親シェルで 認証情報をすでに解決しており、同じセッションでこれらのスクリプトを 複数連続して実行している場合）は、解決をスキップし、キャッシュされた値を 再利用します。orgId はこのヘルパーの対象外です。enable-call-scoring.sh は ステータスバナー専用に、独自の sf org display を通じて別途取得します。

フェーズ 0 — ECI 購入確認

状態検出の前に、Tooling API（フェーズ 3 の ECICallScoringAI 確認と 同じパターン）を使って ConversationPilot の OrgPermission を照会します。 これはライセンス／購入の確認であり、以下の enableCallCoaching とは 異なります。後者は、すでにライセンスを持つ組織に対する管理者の Setup トグルです。

• 無効： 次のメッセージを表示して終了します。「この組織には Einstein Conversation Insights がなく、Call Coaching の利用に必要なため、 Call Coaching を有効にできませんでした。続行するには、管理者が Setup → Salesforce Go → Einstein Conversation Insights に移動するか、営業担当者に連絡して、 ECI の購入方法を確認してください。」ゼロ以外の終了コードで終了します。
• 有効： フェーズ 1 の enableCallCoaching 確認に進みます。

フェーズ 1 — 状態の検出

2 種類の設定に対して、/services/Soap/m/68.0 で SOAP の readMetadata を 実行します。

1. ConversationalIntelligenceSettings → enableCallCoaching（ECI の有効化） と enableECICallScoring（現在の Call Coaching の状態）を読み取ります。
2. EinsteinGptSettings → enableEinsteinGptPlatform を読み取ります。

（RiverRushSettings／riverRushEnabled（Momentum）は読み取りません。 この検出は River Rush の有効化時まで保留されています。再追加する場所については、 「主な考慮事項」を参照してください。）

Tooling API を使って、既存のコンピテンシーを照会します。 SELECT COUNT() FROM EnablementCompetencyDef

組織を次の 4 つの状態に分類します。

状態	検出条件
1a. 利用不可（ECI ライセンスなし）	ConversationalIntelligenceSettings を読み取れない
2. 利用可能、未有効	enableCallCoaching=true AND enableECICallScoring=false
3. 有効、コンピテンシーなし	enableECICallScoring=true AND 件数 = 0
4. 有効、コンピテンシーあり	enableECICallScoring=true AND 件数 > 0

フェーズ 2 — 状態に応じた分岐

• 状態 1a： PRD の文言どおりのメッセージを表示して終了します。「この組織では AI コールコーチングを利用できません。Agentforce for Sales が必要です。」 ゼロ以外の終了コードで終了します。
• 状態 3／状態 4： コンピテンシーのセットアップを開始できる旨の メッセージを表示して、終了コード 0 で終了します。
• 状態 2： 続行します。

フェーズ 3 — 前提条件の有効化（State 2 のみ）

• ライセンスゲート（最初に確認）： OrganizationSettingsDetail（Tooling API）を照会し、ECICallScoringAI の OrgPermission を確認します。明示的な false の場合のみ拒否し、「この組織では AI コールコーチングを利用できません。組織には Agentforce for Sales ライセンスが必要です。」と出力して終了します（ゼロ以外の終了コード）。権限を読み取れない場合（INVALID_TYPE で照会が拒否される（一部の組織エディション、たとえば Developer Edition）か、結果が空の場合）は、不明として処理を続行します。読み取り不能なシグナルを理由に、フェイルクローズしてはなりません。Einstein GenAI の TYPE_UNAVAILABLE 事前チェックで、ライセンスのない組織の大半を検出できます。updateMetadata による有効化の書き込みが最終確認となります。これは、結論が出ない読み取りの場合は処理を保留する Phase 0 の ConversationPilot ゲートと同じ動作です。 enableCallCoaching／enableECICallScoring の読み取り結果がすでに有効を示している場合でも、必ず実行します。これらの設定だけでは、組織にライセンスがあることを確認できないためです。**以下の ECI オフ確認より先に実行してください。**ライセンスがない組織と、ライセンスはあるものの設定がオフの組織は、どちらも enableCallCoaching=false と読み取られます。そのため、先に ECI を確認すると、ライセンス不足をセルフサービスの設定トグルの問題と誤診します（NoLicense 評価データセットが防止する回帰です）。
• ECI がオフの場合： Setup の案内を示して拒否し、ゼロ以外の終了コードで終了します。このスキルでは ECI を有効にしません（PRD で明示されています）。Momentum のみの組織もここに該当します。Momentum は個別に検出されないため、Momentum 固有のメッセージではなく、同じ一般的なメッセージが表示されます。
• Einstein GenAI がオフの場合： EinsteinGptSettings に対して SOAP updateMetadata を実行し、enableEinsteinGptPlatform=true に設定します。PRD で明示的に許可されています。すでにオンの場合は updateMetadata の呼び出しを省略し、有効化済みであることを管理者に伝えます。組織に EinsteinGptSettings のライセンスがないために更新が失敗した場合（または fault がなく明示的に拒否された場合）は、AI コールスコアリングの有効化には Agentforce for Sales が必要であり、ライセンスがなくても Salesforce Go の設定から 手動のコールスコアリング を設定できることを管理者に伝えます。認証／権限エラー、またはネットワーク／タイムアウトエラーはライセンス不足ではないため、ライセンスに関するメッセージではなく、それぞれに応じたメッセージ（CLI セッションの確認／再試行）を表示します。

フェーズ 4 — コールコーチングの有効化（State 2 のみ）

enableECICallScoring がすでに true と読み取られる場合（たとえば、Phase 1 で読み取ってからここに到達するまでの間に、別の方法で変更された場合）は、更新を省略し、有効化済みであることを管理者に伝えます。それ以外の場合は、ConversationalIntelligenceSettings に対して SOAP updateMetadata を実行し、enableECICallScoring=true に設定します。<success>true</success> を必須とします。

フェーズ 5 — 検証（State 2 のみ）

enableECICallScoring を再読み取りします。true であることを必須とします。失敗した場合は SOAP 応答を出力します。

主な考慮事項

• API バージョンは v68.0 であり、v64.0 ではありません。 一部のビルドでは、低い API バージョンの ConversationalIntelligenceSettings スキーマに enableECICallScoring が存在しません。v68 が安全な最小バージョンです。Pipeline スキルでは、対象フィールド（SalesDealAgentSettings.enableDealAgent）がそのバージョンに存在するため v64 を使用していますが、Call Scoring は存在しません。
• この設定に sf mdapi deploy を使用しないでください。 CLI は成功を報告する一方で、設定が切り替わらないサイレント失敗が発生することがあります。SOAP の updateMetadata を直接使用してください。応答の <success> ブール値が確定的な結果です。
• サーバー側のゲートは、このスキルの対象範囲より広いものです。 orgHasCallScoring アクセスチェックでは、ECI と River Rush（Momentum）のいずれかの条件を満たす必要があります。CoachingCompetenciesFeature.isFeatureAvailableInOrg() を参照してください。このスキルでは、スパイクで定めた MVP の対象範囲に従い、意図的に ECI の条件のみに絞っています。
• River Rush（Momentum）の検出は、見落としではなく、現時点では意図的に含めていません。 この条件はまだ有効ではありません。以前の enable-call-scoring.sh は RiverRushSettings.riverRushEnabled を読み取り、Momentum のみが有効な組織に対して個別の「State 1b」メッセージを表示して処理を拒否したり、Momentum は利用可能だがオフであることを通知したりしていましたが、どちらも削除されました。River Rush の提供開始後に再追加してください（読み取り、State 1b の分岐、Phase 3 の通知）。削除されたコードは、このファイルの Git 履歴から復元できます。
• disableOnSandboxCopy=true です。 サンドボックスを更新するたびに、この設定は無効になります。更新後に管理者がスキルを再実行するのが想定される手順です。冪等性チェックにより、安全に再実行できます。
• 組織のポッドでサイトスイッチ com.salesforce.eci.callScoringEnabled が開いている必要があります。このスイッチは管理者が切り替えることはできず、SOAP でも読み取れません。閉じている場合、updateMetadata は <success>false</success> と <errors><statusCode>…</statusCode></errors> ブロックを含む、形式上は正しい応答を返します。SOAP の <Fault> は発生しません。parse_soap_response が statusCode を抽出し、WRITE_ERROR:… 分類で提示します。
• ECI のプロビジョニングは非同期です。 enableCallCoaching が有効になってからしばらくの間、依存する enableECICallScoring フィールドはサーバー側で読み取り専用となり、updateMetadata は INSUFFICIENT_ACCESS_OR_READONLY を返します。enable-call-scoring.sh はこれを最終的な失敗として扱わず、「有効化の処理がまだ完了していません。数分待ってから再実行してください」という一時的なメッセージに変換します。
• すべての SOAP 呼び出しには 30 秒のタイムアウトが設定されています（enable-call-scoring.sh の CURL_TIMEOUT。このリポジトリで既存のタイムアウト設定がある Pipeline スキルの setup-all.sh に合わせています）。また、shared/soap.sh の parse_soap_response を通じて true／false／AUTH_ERROR:...／TYPE_UNAVAILABLE:...／WRITE_ERROR:…／NETWORK_ERROR に分類されます。これにより、「この設定のライセンスが組織にない」場合、「認証／権限エラー」の場合、「サーバーが特定の statusCode で書き込みを拒否した」場合、「ネットワーク／タイムアウトエラー」の場合を区別できます。空文字列にまとめたり、生の SOAP XML を管理者に表示したりすることはありません。
• enable-call-scoring.sh は sf api request rest ではなく、生の SOAP を使用します。 このスキルのほかのすべてのスクリプトでは、認証を CLI が一貫して管理するよう sf api request rest を使用しています。enable-call-scoring.sh だけが例外です。ConversationalIntelligenceSettings などの SOAP Metadata API の読み取り／書き込みを公開する Salesforce CLI コマンドが、ベータ版を除いて存在しないこと、また、この特定のフィールドに対して sf mdapi deploy では前述のサイレント失敗が発生することが理由です。これは意図的に範囲を限定した例外であり、見落としではありません。

参考資料

• 参考スキル（標準的な単一 OrgPref パターン）： skills/sales-agentforce-pipeline-management-configure/
• SOAP ヘルパー：scripts/shared/soap.sh（Pipeline スキルからコピーした redact_token、parse_soap_response）
• サーバー側ゲート（宣言的なアクセスチェック）： ConversationalIntelligence.accessChecks.xml — orgHasCallScoring = ECI アームまたは River Rush アーム。orgHasECICallScoringWithAI は Einstein GenAI と ECICallScoringAI ライセンス権限を追加で要求します。
• 設定宣言： ConversationalIntelligence.settings.xml — <orgPreference name="ECICallScoringEnabled" mdApiName="enableECICallScoring" ...>
• Java 機能登録（SetupDiscoveryService の REST/MCP ラッパーが存在すれば、エントリーポイントとなるもの）：CoachingCompetenciesFeature.java

コンピテンシーの CRUD ワークフロー

Phase 5 で Call Coaching が有効であることを確認したら（または Phase 1 で State 3/4 を検出したら）、Claude は同じターン内で Next: スクリプトを直接実行します。レコードは、Tooling API を介して EnablementCompetencyDef（セットアップエンティティ、keyPrefix 1nA、モジュール conversation-udd）で管理します。組織ごとの上限は、同時に有効なものが8 件です（CoachingCompetenciesFeature.MAX_ACTIVE_COMPETENCIES）。

すべてのスクリプトは shared/auth.sh / resolve_org_auth を共有し、認証トークンは連続した呼び出しの間で引き継がれるため、再認証は不要です。Tooling API の書き込みには、実用上可能な場合は sf api request rest を使用します。一部のスクリプト（カスタム CRUD の各種スクリプト、ベストプラクティスのインストーラー）では、リクエスト形式をより細かく制御するために、生の curl を使用します。

スクリプトは、並行する2 つのファミリーに分類されます。

• 汎用 — {create,edit,toggle,get}-competency.sh — あらゆるコンピテンシーで動作します。
• カスタム CRUD の各種スクリプト — *-custom-competency.sh — SpecificCallsOnly フィルター JSON と、より詳細な検証により、書き込みパスを強化します。

管理者の意図が明らかにカスタム（S5 で作成）である場合はカスタム版を優先し、OOTB または作成元が不明なレコードには汎用版を使用します。

完全な仕様 — S3 から S10 までのスクリプト契約、S5 の Q1-Q4 対話型ドラフト作成手順、管理者の意図 × 組織の状態の実行マトリックス、連続実行時のチェックポイント — は references/competency-crud.md に記載されています。管理者の依頼がコンピテンシーレコード（一覧表示、インストール、作成・編集、有効化、検証、削除）に関わる場合は、必ず参照してください。

スタンドアロンスクリプト（概要）

スクリプト	目的
enable-call-scoring.sh <alias>	状態を検出し、Einstein GenAI がオフの場合は有効化して、Call Coaching の設定を切り替えます（フェーズ 0～5）。
list-competencies.sh <alias> [--verbose|--json]	すべてのコンピテンシーとステータスを一覧表示します。デフォルトでは管理者に安全な出力となり、--verbose で ID／DeveloperName を追加し、--json は呼び出し元のエージェント専用です。
install-ootb-competencies.sh <alias> [--dry-run]	PRD 準拠の OOTB コンピテンシー 6 件をインストールします。
install-best-practice-competencies.sh <alias> [--dry-run] [--only "Name1,Name2"]	Momentum のベストプラクティス参照プロンプト 7 件をインストールします。--only は MasterLabel で絞り込みます。
create-competency.sh <alias> <payload.json>	コンピテンシーを 1 件作成します（汎用。OOTB とカスタムのどちらにも使用できます）。
create-custom-competency.sh <alias> <payload.json>	カスタムコンピテンシーを 1 件作成します（強化版。S5 ではこちらを推奨します）。
edit-competency.sh <alias> <ident> ...	説明／指示を編集します（汎用）。
edit-custom-competency.sh <alias> <ident> ...	説明／指示を編集します（カスタム CRUD 版）。
toggle-competency.sh <alias> <ident> <activate|deactivate>	有効化／無効化します（汎用）。
toggle-custom-competency.sh <alias> <ident> <activate|deactivate>	有効化／無効化します（カスタム CRUD 版）。
get-competency.sh <alias> <ident> [--field <f>]	レコードまたは単一の項目を取得します（汎用）。
get-custom-competency.sh <alias> <ident> [--field <f>]	レコードまたは単一の項目を取得します（カスタム CRUD 版）。
verify-ootb-competencies.sh <alias> ["Name" ...]	期待されるコンピテンシーが存在し、有効になっていることを確認します。S9 の管理者向け Markdown テーブルを出力します。
削除スクリプトなし（現時点）	sf data delete record --sobject EnablementCompetencyDef --record-id <Id> --use-tooling-api を使用してください。§S10 を参照してください。

管理者による検証

実行が正常に完了した後、管理者は次の方法で個別に検証できます。

UI 経由 — Salesforce Go → Coaching Competencies にアクセスできるようになり、機能が有効で、設定済みのコンピテンシーが表示されていることを確認できます。

CLI 経由 — Tooling API クエリを 2 件実行します。

# Feature enabled?
sf data query --target-org <alias> --use-tooling-api \
  --query "SELECT IsEciCallScoringEnabled FROM ConversationalIntelligenceSettings"

# Competencies configured?
sf data query --target-org <alias> --use-tooling-api \
  --query "SELECT MasterLabel, IsActive, SourceCompetencyTemplate FROM EnablementCompetencyDef ORDER BY MasterLabel"

アセット

• assets/ootb-competencies.json — PRD 準拠の OOTB プロンプト本文 6 件 （install-ootb-competencies.sh でインストールされます）。
• assets/best-practice-competencies.json — Momentum のベストプラクティス プロンプト本文 7 件（S5 の作成時の参考資料。create-competency.sh でも インストールできます）。