orchestrating-datacloud

orchestrating-datacloud：Salesforce Data Cloud オーケストレーター

単一のコマンドファミリーに限定されない、製品レベルの Data Cloud ワークフローガイダンス（パイプラインの設定、フェーズ横断のトラブルシューティング、データスペース、データキット、またはタスクが Connect、Prepare、Harmonize、Segment、Act、Retrieve のどれに属するかの判断）が必要な場合に、このスキルを使用します。

このスキルは、実行時には外部の sf data360 コマンドを使用しながら、sf-skills のハウススタイルに従うよう意図されています。このリポジトリにはプラグインは含まれていません。

---

このスキルが担当するタスク

次の作業には orchestrating-datacloud を使用します。

• Data Cloud の複数フェーズにわたる設定や修復
• データスペース（sf data360 data-space *）
• データキット（sf data360 data-kit *）
• ヘルスチェック（sf data360 doctor）
• CRM から統合プロファイルへのパイプライン設計
• データ取り込み → ハーモナイズ → セグメンテーション → アクティベーションの進め方の判断
• 根本原因がまだ明らかでない、フェーズ横断のトラブルシューティング

ユーザーが特定の領域に重点を置いている場合は、フェーズ固有のスキルに委任します。

フェーズ	使用するスキル	一般的な対象範囲
Connect	connecting-datacloud	接続、コネクタ、ソースの検出
Prepare	preparing-datacloud	データストリーム、DLO、変換、DocAI
Harmonize	harmonizing-datacloud	DMO、マッピング、ID 解決、データグラフ
Segment	segmenting-datacloud	セグメント、計算済みインサイト
Act	activating-datacloud	アクティベーション、アクティベーションターゲット、データアクション
Retrieve	retrieving-datacloud	SQL、検索インデックス、ベクトル検索、非同期クエリ

ユーザーが次の作業を行う場合は、ファミリー外のスキルに委任します。

• Session Tracing / STDM のテレメトリを抽出する → observing-agentforce
• CRM SOQL のみを記述する → querying-soql
• CRM ソースデータを読み込む → handling-sf-data
• 不足している CRM スキーマを作成する → generating-custom-object または generating-custom-field
• 下流の Apex または Flow ロジックを実装する → generating-apex、generating-flow

---

最初に収集する必要があるコンテキスト

次の情報を尋ねるか、推測します。

• 対象組織のエイリアス
• プラグインがすでにインストールされ、リンクされているか
• ユーザーが設計ガイダンス、読み取り専用の確認、ライブ環境への変更のどれを希望しているか
• 関連するデータソース：CRM オブジェクト、外部データベース、ファイル取り込み、ナレッジなど
• 期待する成果：統合プロファイル、セグメント、アクティベーション、ベクトル検索、分析、またはトラブルシューティング
• ユーザーがデフォルトのデータスペースとカスタムのデータスペースのどちらを使用しているか
• 組織が scripts/diagnose-org.mjs で分類済みか
• 現在、失敗しているコマンドファミリーがあれば、その名前

プラグインの利用可否や組織の準備状況が不明な場合は、次から始めます。

• references/plugin-setup.md
• references/feature-readiness.md
• scripts/verify-plugin.sh
• scripts/diagnose-org.mjs
• scripts/bootstrap-plugin.sh

---

基本的な運用ルール

• 外部の sf data360 プラグインランタイムを使用し、コマンドレイヤーを再実装したり、同梱したりしないでください。
• タスクの範囲が絞り込めたら、フェーズ固有の最小限のスキルを優先してください。
• 変更を伴う作業の前に、準備状況を分類してください。失敗したコマンドを一つだけ見て推測するより、scripts/diagnose-org.mjs を優先してください。
• sf data360 コマンドでは、デバッグに標準エラー出力が必要な場合を除き、2>/dev/null を付けてリンク済みプラグインの警告を抑制してください。
• Data Cloud SQL と CRM SOQL を区別してください。
• sf data360 doctor を製品全体の準備状況を確認する手段として扱わないでください。現在のアップストリームコマンドが確認するのは、検索インデックスの範囲のみです。
• query describe をテナント全体の汎用プローブとして扱わないでください。より広範な準備状況を確認した後、既知の DMO／DLO テーブルに対してのみ使用してください。
• 重要な場合は、Data Cloud 固有の API バージョン回避策を維持してください。
• 組織固有のワークショップ用ペイロードより、汎用的で再利用可能な JSON 定義ファイルを優先してください。

---

推奨ワークフロー

1. ランタイムと認証を確認する

次の項目を確認します。

• sf がインストールされている
• コミュニティ版 Data Cloud プラグインがリンクされている
• 対象の組織が認証済みである

推奨する確認コマンド：

sf data360 man
sf org display -o <alias>
bash ./scripts/verify-plugin.sh <alias>

sf data360 doctor は全般的なヘルスシグナルとして扱い、唯一の判定基準にしないでください。一部しかプロビジョニングされていない組織では、コネクター、DMO、セグメントなどの読み取り専用コマンドが引き続き動作していても、失敗することがあります。

2. 変更を加える前に準備状況を分類する

まず、共通の分類スクリプトを実行します。

node ./scripts/diagnose-org.mjs -o <org> --json

テーブル名が実在すると確認できてから、クエリプレーンのプローブを使用してください。

node ./scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json

分類スクリプトを使って、次の状態を区別します。

• 有効だが空のモジュール
• 機能が制限されているモジュール
• クエリプレーンの問題
• ランタイム／認証の失敗

3. 読み取り専用コマンドで既存の状態を確認する

分類後、対象を絞って調査します。

sf data360 doctor -o <org> 2>/dev/null
sf data360 data-space list -o <org> 2>/dev/null
sf data360 data-stream list -o <org> 2>/dev/null
sf data360 dmo list -o <org> 2>/dev/null
sf data360 identity-resolution list -o <org> 2>/dev/null
sf data360 segment list -o <org> 2>/dev/null
sf data360 activation platforms -o <org> 2>/dev/null

4. フェーズを特定する

タスクを次のように振り分けます。

• ソース／コネクターの問題 → Connect
• 取り込み／DLO／ストリームの問題 → Prepare
• マッピング／IR／統合プロファイルの問題 → Harmonize
• オーディエンスまたはインサイトの問題 → Segment
• 下流へのプッシュの問題 → Act
• SQL／検索／インデックスの問題 → Retrieve

5. 可能な場合は決定性の高い成果物を選ぶ

一度限りの手動操作より、JSON 定義ファイルと再現可能なスクリプトを優先してください。汎用テンプレートは次の場所にあります。

• assets/definitions/data-stream.template.json
• assets/definitions/dmo.template.json
• assets/definitions/mapping.template.json
• assets/definitions/relationship.template.json
• assets/definitions/identity-resolution.template.json
• assets/definitions/data-graph.template.json
• assets/definitions/calculated-insight.template.json
• assets/definitions/segment.template.json
• assets/definitions/activation-target.template.json
• assets/definitions/activation.template.json
• assets/definitions/data-action-target.template.json
• assets/definitions/data-action.template.json
• assets/definitions/search-index.template.json

6. 各フェーズの後に検証する

一般的な検証項目：

• ストリーム／DLO が存在する
• DMO／マッピングが存在する
• ID 解決の実行が完了している
• 統合レコードまたはセグメント数が正しい
• アクティベーション／検索インデックスのステータスが正常である

---

特に注意すべき点

• connection list には --connector-type が必要です。
• 完全なカタログが必要な場合は dmo list --all が便利ですが、準備状況の確認には、最初のページのみを表示する dmo list で十分なことが多く、処理もはるかに高速です。
• セグメントの作成では --api-version 64.0 が必要な場合があります。
• segment members は不透明な ID を返します。人が読める詳細を取得するには、SQL の結合を使用してください。
• 一部の読み取り専用コマンドが引き続き動作していても、プロビジョニングが不完全な組織では sf data360 doctor が失敗することがあります。その場合は、対象を絞ったスモークテストに切り替えてください。
• Couldn't find CDP tenant ID や DataModelEntity ... not found などの query describe エラーは、クエリプレーンに関する手掛かりであり、製品全体が無効であることを自動的に示すものではありません。
• 多くの長時間実行ジョブは、コマンドがすぐに戻る場合でも、実際には非同期で動作します。
• Data Cloud の一部の操作では、CLI ランタイムの外部で UI による設定が引き続き必要です。

---

出力形式

完了時には、次の順序で報告してください。

1. タスク分類
2. 実行時のステータス
3. 準備状況の分類
4. 関与したフェーズ
5. 使用したコマンドまたは成果物
6. 検証結果
7. 次に推奨されるステップ

推奨形式：

Data Cloud task: <setup / inspect / troubleshoot / migrate>
Runtime: <plugin ready / missing / partially verified>
Readiness: <ready / ready_empty / partial / feature_gated / blocked>
Phases: <connect / prepare / harmonize / segment / act / retrieve>
Artifacts: <json files, commands, scripts>
Verification: <passed / partial / blocked>
Next step: <next phase, setup guidance, or cross-skill handoff>

---

スキル間の連携

必要な作業	委任先	理由
CRM のソースデータの読み込みまたはクリーンアップ	handling-sf-data	取り込みの前にソースレコードを準備または修正するため
不足している CRM スキーマの作成	generating-custom-object、generating-custom-field	Data Cloud では既存のオブジェクト／項目が必要なため
権限またはバンドルのデプロイ	deploying-metadata	環境の準備
Data Cloud の出力を使った Apex の記述	generating-apex	コードの実装
セグメント化／アクティベーション後の Flow 自動化	generating-flow	宣言型のオーケストレーション
セッションのトレース／STDM／parquet の分析	observing-agentforce	Data Cloud の別のユースケース

---

リファレンスマップ

まずはこちら

• README.md
• references/plugin-setup.md
• references/feature-readiness.md
• UPSTREAM.md

フェーズ別スキル

• connecting-datacloud
• preparing-datacloud
• harmonizing-datacloud
• segmenting-datacloud
• activating-datacloud
• retrieving-datacloud

決定的なヘルパー

• scripts/bootstrap-plugin.sh
• scripts/verify-plugin.sh
• scripts/diagnose-org.mjs
• assets/definitions/