consumer-goods-tpe-datakit-deploy

TPE Data Kit Deploy

TPM Accruals Data Kit とその DMO マッピングを Salesforce 組織にデプロイします。単独で完結しており、それ自体で実行することも、consumer-goods-tpe-dashboard-configure（ステップ 7）から呼び出される委任ステップとして実行することもできます。後者の場合、このスキルでユーザー名やドライランフラグを再取得するのではなく、呼び出し元のスキルがすでに収集したものをそのまま受け取ります。

最初に収集する入力

呼び出し元のスキルからすでに提供されている場合を除き、開始前に確認してください。推測しないでください。

1. TPM System Admin のユーザー名 — sf CLI で認証済みであることを確認します。兄弟スクリプトを使って検証してください。sf org display --json を直接実行してはいけません。このコマンドの生の出力には accessToken（有効な認証情報）が含まれますが、このスクリプトは出力前にそれを取り除きます。

   node ./scripts/sf-rest.js org-status --target-org <username>
   

   {"username","alias","connectedStatus","orgId"} が出力されます。終了コードが 0 以外、または connectedStatus != "Connected" の場合は停止し、ユーザー自身にログインを依頼してください。
2. ドライランを実行しますか？ — デフォルトで提案してください。ドライランでは、フェーズ 1（事前チェック）とフェーズ 2 の読み取り／差分確認ステップは実行します。フェーズ 2 の FieldPermissions の書き込みとフェーズ 3～5（デプロイ）はスキップし、pending — not run (dry-run) として記録します。
3. TPM Data Connector がインストール済みで有効であること — プログラムから確認できません。設定名を伝えるだけでなく、正確な移動手順を明示してユーザーに確認してください。"TPM Data Connector が有効になっていることを確認していただけますか？ 1) Setup → Data Cloud Setup に移動します。2) 左側のナビゲーションで、EXTERNAL INTEGRATIONS の下にある Other Connectors をクリックします。3) 一覧から「TPM Data Connector」を見つけ、ステータスを確認します。" 明確な肯定の返答を待ってください。見つからない、または無効な場合は、停止してください。TPM Data Connector が有効でなければ続行できないことを伝え、組織の種類に応じた次の 2 つの異なる対処方法を説明してください。
   • 本番組織 — 組織に Data Cloud ライセンスがあれば、Processing Service のペアリング後、通常は約 24 時間以内に自動インストールされます。前提条件が両方とも満たされている場合は、ユーザーに待ってから再試行するよう依頼してください。いずれかが満たされていない（まだペアリングされていない、または Data Cloud ライセンスがない）場合は、それが先に解決すべき実際のブロッカーです。
   • Sandbox 組織 — 自動インストールされないことがよくあります。通常は EXTERNAL INTEGRATIONS → Other Connectors で手動で有効にする必要があります。Sandbox では想定される動作であることを伝え、そこで有効にしてから、続行前に確認するよう依頼してください。 ユーザーから有効であるとの確認を得たら、このチェックを再実行してください。
4. Salesforce CRM Home 組織の接続 — プログラムから確認できません。正確な移動手順を明示してユーザーに確認してください。"Salesforce CRM Home 組織の接続が有効になっていることを確認していただけますか？ 1) Setup → Data Cloud Setup に移動します。2) 左側のナビゲーションで、SALESFORCE INTEGRATIONS の下にある Salesforce CRM をクリックします。3) Home 組織の接続ステータスが Active であることを確認します。" 明確な肯定の返答を待ってください。接続が見つからない、または無効な場合は、停止してください。この接続が有効でなければ続行できないことを伝えてください（フェーズ 2 のフィールド権限付与には Data Cloud Salesforce Connector 権限セットが必要ですが、この接続が設定されるまでは存在しません）。まず有効化／設定するよう依頼し、その後このチェックを再実行してください。
5. TPM Admin ペルソナ用の権限セットと GenieAdmin 権限セットが割り当て済みであること — consumer-goods-tpe-dashboard-configure から委譲ステップとして呼び出された場合は、先行フェーズですでに確認済みの両方の結果が引き継がれるため、それを再利用し、再確認や再照会はしないでください。単独で呼び出された場合は、それぞれを直接確認してください。
   • TPM Admin ペルソナ用の権限セット — 「TPM Admin ペルソナ」はロールであり、実際の権限セット名ではありません。そのペルソナに対応する組織固有の権限セット（名前／割り当て）はプログラムから確認できません。ユーザーに次のように確認してください。"TPM Admin ペルソナに必要な権限セットは、<username> に割り当てられていますか？" 明確な肯定の返答を待ってください。
   • GenieAdmin — まずその Label を特定してください（API の Name はユーザーに決して表示しないでください）。次に割り当てを確認します。

     sf data query --target-org <username> --query "SELECT Label FROM PermissionSet WHERE Name = 'GenieAdmin'"
     sf data query --target-org <username> \
       --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '<username>' AND PermissionSet.Name = 'GenieAdmin'"
     

     割り当てがない場合は、最初のクエリで取得した Label をユーザーに伝え（例："ユーザー <username> には <Label> 権限セットが割り当てられていません。今すぐ割り当てますか？"）、続行前に割り当ての許可を求めてください。

     sf data create record --sobject PermissionSetAssignment \
       --values "AssigneeId=<userId> PermissionSetId=<psId>" --target-org <username>
     

     許可されなかった場合はスキップし、レポートに記録してください。
6. Namespace（NS） — 委譲ステップとして呼び出された場合、consumer-goods-tpe-dashboard-configure から検出済みの NS（生の namespace 文字列）が引き継がれるため、それを再利用し、再検出しないでください。単独で呼び出された場合は、フェーズ 1 の前に、兄弟スクリプトを使って一度だけ検出してください。

   node ./scripts/detect-namespace.js --target-org <username>
   

   {"NS","NS_SEGMENT","NS_APEX","NS_FIELD"} が 1 行の JSON として出力されます。4 つすべてを保存し、以下のすべての箇所で再利用してください。

フェーズ 1 — 事前確認

2. 後で検証するためのベースライン — フェーズ 5 で CreatedDate の時刻ずれによる誤検知を避けるため、デプロイ作業を始める前に、最新の DataKitDeploymentLog の Id を取得します。

   sf data query --target-org <username> \
     --query "SELECT Id FROM DataKitDeploymentLog ORDER BY CreatedDate DESC LIMIT 1" --json
   

   LAST_ID_BEFORE_DEPLOY として保存します（行が 0 件の場合は空欄）。
3. CGCloudAddons のダウンロードと解凍 — このスキルが自分で取得するため、ユーザーに手動での作業を依頼しません。

   node ./scripts/download-static-resource.js \
     --target-org <username> --name CGCloudAddons
   

   標準出力から STATIC_RESOURCE_PATH=<dir> を <addons_root> として取得します。以下のすべてのパスはこのディレクトリからの相対パスです（例：<addons_root>/TPM/Accruals/TPM Accruals Data Kit）。StaticResource の行が 0 件の場合 ⇒ ブロック：この組織にインストールされているパッケージバージョンには CGCloudAddons が含まれていません。それ以外のスクリプトエラー ⇒ ブロックし、標準エラー出力をそのまま伝えます。

フェーズ 2 — CRM ストリームの項目権限（ダウンロードしたパッケージから導出）

このフェーズでは、相互に関連する 2 つのスクリプトを使用します。解析や権限付与の呼び出しを手作業で行わないでください。スクリプトの動作と理由の詳細は、それぞれの docstring を参照してください。

1. ダウンロードしたパッケージから {sobject, fields[]} リストを抽出します（読み取り専用で、いつでも安全に実行できます）。

   node ./scripts/extract-crm-field-permissions.js \
     --dir "<addons_root>/TPM/Accruals/TPM Accruals Data Kit/force-app/main/default/dataSourceObjects" \
     > /tmp/crm-field-permissions.json
   

   出力にエントリが 0 件の場合 ⇒ ブロックして報告します。フェーズ 1 が成功していれば発生しないはずです。
2. 更新差分をサイレントに取得します（スクリプト独自の --dry-run。読み取り専用：権限セット、sobject/describe、既存の FieldPermissions/ObjectPermissions 行）。まだユーザーには何も表示しないでください。必要な作業があるかどうかを確認するだけです。

   node ./scripts/update-field-permissions.js \
     --target-org <username> --input /tmp/crm-field-permissions.json --dry-run
   

   {"error":"permission_set_not_found",...} ⇒ このフェーズを中止してブロック扱いにし、ユーザーに次のように伝えます："「Data Cloud Salesforce Connector」権限セットが見つかりませんでした。考えられる原因は、Salesforce CRM がまだ設定されていないことです（Setup → Data Cloud → Salesforce CRM）。まず設定してから、このフェーズを再実行してください。"
3. wouldGrant または objectWouldGrant が空でない場合に限り、完全な抽出リストではなく、その差分をそのままユーザーに示し、書き込みを行う前に明示的な許可を得ます。両方が空の場合は、すべての権限がすでに付与されています。ステップ 5 に進み、確認は不要です。
4. 確認を得たら、実際に実行します — 項目レベルとオブジェクトレベルの両方で追加のみを行います（正確な動作はスクリプトの docstring を参照）。

   node ./scripts/update-field-permissions.js \
     --target-org <username> --input /tmp/crm-field-permissions.json
   

   終了コードが 3 の場合（または failed[]/objectFailed[] が空でない場合）⇒ 回避策を推測せず、Setup → Permission Sets → Data Cloud Salesforce Connector → Object Settings から、failed[]/objectFailed[] のリストをそのまま使用して手動で設定するようユーザーに依頼し、それぞれをレポートに記録します。
5. 最終レポート用に、合格／ブロック／保留の状態と、変更した項目／オブジェクトの結果（granted/alreadyGranted/notFlsEligible/failed、objectGranted/objectAlreadyGranted/objectFailed）を記録します。ドライランモードではステップ 4 に進まないでください。権限が更新されます。ステップ 1 とステップ 2 は読み取り専用なので実行できます。
6. permissionsViewAllRecords: false の objectGranted/objectAlreadyGranted エントリは、ライセンスによってそのフラグが制限される、固定の少数の sobject（現在は Product2 のみ）で想定される状態です。これは既知のプラットフォーム制限であり、スクリプトが暗黙的に適用します。ユーザーに報告したり、Setup での手動対応が必要なものとして扱ったりしないでください。

フェーズ 3 — データキットのメタデータを準備してデプロイ

1. <addons_root>/TPM/Accruals/TPM Accruals Data Kit で、プレースホルダー __SF_ORG_ID__ のすべての出現箇所を、組織の 15 桁の Id に置き換えます。以下の関連スクリプトで組織 Id を取得します。

   node ./scripts/sf-rest.js org-status --target-org <username>
   

   出力された JSON の orgId フィールドを取得し、先頭から 15 文字に切り詰めます（この呼び出しは低コストで冪等です。Inputs のステップ 1 の結果がまだコンテキストにあると想定せず、必ずここで再実行してください）。
2. このフォルダーからデプロイします。

   sf project deploy start --target-org <username>
   

フェーズ 4 — DMO マッピングをデプロイし、デプロイスクリプトを実行する

1. DMO マッピング — データキットの DLO を Data 360 DMO にマッピングします。<addons_root>/TPM/Accruals/DmoMappings から実行します。

   sf project deploy start --target-org <username>
   

2. デプロイスクリプト — <addons_root>/TPM/Accruals/Accruals Data Kit Deployment Scripts から実行します。

   SF_ORG_ALIAS=<username> node deploy-tpm-tpe.js
   

   このスクリプトは /services/data/v67.0/actions/custom/flow/sfdatakit__DeployDataKitComponents に POST し、非同期 Flow インタビューの GUID を直ちに返します。この応答だけでは成功を意味しません。必ずフェーズ 5 の DataKitDeploymentLog チェックで確認してください。このスクリプトは、ダウンロードして展開した静的リソース内から実行します。

フェーズ 5 — 検証

sf data query --target-org <username> \
  --query "SELECT Id, DeploymentStatus, ComponentName, DeploymentError, CreatedDate FROM DataKitDeploymentLog WHERE Id > '<LAST_ID_BEFORE_DEPLOY>' ORDER BY CreatedDate DESC"

この実行に関するすべての行で、DeploymentStatus = 'Successful' かつ DeploymentError が空欄である必要があります。いずれかの行が Failure であるか、エラーが空でない場合は、決して成功を宣言しないでください。

UI で確認する場合：Data Cloud Setup → Data Kits → TPM Accruals → Local Deployment History → ステータスが Successful。

既知の注意点

• FlowDefinition は SOQL でクエリできません。準備状況の確認に使用しないでください。
• sfdatakit__DeployDataKitComponents の ApexClass の確認では、フレームワークが稼働していても 0 行が返る場合があります。直接 DataKitDeploymentLog を確認する方法を優先し（フェーズ 5）、Apex クラスは決して確認しないでください。

ルール

• この実行に関する DataKitDeploymentLog の行に Failure がある場合、または DeploymentError が空でない場合は、決して成功を宣言しないでください。
• CGCloudAddons の StaticResource は（download-static-resource.js を介して）読み取るだけにしてください。デプロイや変更は決して行わないでください。ダウンロードには組織自身の sf 認証済みアクセストークンを使用し、ハードコードされた認証情報は決して使用しません。
• 準備状況の確認に FlowDefinition や sfdatakit__DeployDataKitComponents の Apex クラスを確認しないでください。代わりに DataKitDeploymentLog を確認してください。
• デプロイ手順については、組織に同梱されている README.md（または CGCloudAddons に含まれるパッケージ内ドキュメント）を決して参照しないでください。このスキルのフェーズに記載された手順に正確に従ってください。ここに記載されているスクリプト名やパスが、ダウンロードしたパッケージの実際の内容と一致しない場合は、このスキルの不具合なので修正してください（スキル自体を更新）。実行時にパッケージのドキュメントへ切り替える理由にはなりません。
• ダウンロードしたフォルダーにスクリプトやフォルダーがない場合、推測したりスクリプトを変更したりしないでください。例：deploy-tpm-tpe.js スクリプトは決して変更しないでください。
• update-field-permissions.js は、必ず最初に --dry-run を付けて実行してください。wouldGrant／objectWouldGrant のいずれかが空でない場合は、変更内容の正確な差分をユーザーに提示して明示的な承認を得るまで、実際の実行を決して行わないでください。このスキル内の他の書き込み操作と同様です。両方とも空の場合は確認不要です。そのまま報告してください。
• update-field-permissions.js が行うのは追加のみです。既存の行がない場合に新しい FieldPermissions／ObjectPermissions の行を追加するか、既存の行のオフフラグ（PermissionsRead、またはオブジェクトレベルの PermissionsViewAllRecords）を true に変更します。行の削除、既存の許可の弱体化、PermissionsCreate／Edit／Delete／ModifyAllRecords の変更を行う方法では、決して呼び出さないでください。
• sfdc_a360_sfcrm_data_extract（「Data Cloud Salesforce Connector」）権限セットがない場合、またはフィールド／オブジェクトが update-field-permissions.js の failed[]／objectFailed[] に含まれる場合は、回避策を推測しないでください。停止し、Setup からフィールドレベルまたはオブジェクトレベルのセキュリティを手動で付与するようユーザーに依頼してください（フェーズ 2 を参照）。

レポート

以下を網羅した最終レポート（pass/blocked/pending）を作成してください。CRM ストリームの項目レベルの権限（extract-crm-field-permissions.js によるオブジェクトごとの項目一覧、および update-field-permissions.js による各項目の granted／alreadyGranted／notFlsEligible／failed の結果。onObject: false の notFlsEligible エントリは、通常のスキップではなくパッケージと組織のデータ不一致を示すため、別途明記してください）、CRM ストリームのオブジェクトレベルの権限（同じスクリプトによる各 sobject の objectGranted／objectAlreadyGranted／objectFailed の結果。Product2 の permissionsViewAllRecords: false は想定どおりなので、特に取り上げる必要はありません）、事前チェック（コネクタのステータス）、メタデータのデプロイ、DMO マッピングのデプロイ、デプロイスクリプトの実行、および DataKitDeploymentLog の検証結果（行数、失敗の有無）。これは、このスキルが委任によって呼び出された場合に、consumer-goods-tpe-dashboard-configure の Step 7 が独自の結果としてそのまま中継する内容です。

委任によって呼び出された場合（ユーザーが直接呼び出したのではなく、呼び出し元のスキルが Skill ツールを使ってこのファイルに到達した場合）、このレポートは中間結果であり、タスクの最終結果ではありません。呼び出し元のスキルにレポートを返し、次のフェーズを続行できるようにしてください。このレポートをユーザーへの最終回答として提示して終了してはいけません。このレポートをユーザーに直接提示するのは、このスキルが単独で呼び出された場合に限ります。