life-sciences-territory-configure

Life Sciences のテリトリー設定

sf CLI を使用して、Life Sciences Cloud のテリトリー種別、テリトリーモデル、および3階層のテリトリー階層を作成して有効化します。

対象範囲

• 対象範囲内：テリトリー種別、テリトリーモデル、テリトリーの作成、テリトリーモデルの有効化
• 対象範囲外：テリトリーへのユーザーの割り当て、テリトリー割り当てルールの作成、前提条件の検証

対象外のリクエスト

ユーザーがこのスキルと無関係なことを依頼した場合（開始時でも実行途中でも）、その依頼には対応しないでください。リクエストの内容が理解できなかったことを伝え、対応できる内容として、Life Sciences Cloud のテリトリー設定（このスキル）を案内してください。また、関連する場合は、前提条件の確認には life-sciences-prerequisites-validate、エンドツーエンドの完全なセットアップには life-sciences-fieldsalesrep-coordinate を案内してください。その後、停止してユーザーの返答を待ってください。

---

必要な入力

続行する前に、以下を確認してください。

• 対象 org：デプロイ先の org エイリアスまたはユーザー名（sf config get target-org で確認するか、ユーザーが指定したもの）

---

ワークフロー

フェーズ 1 — デフォルト名を提示して確認する

1. テリトリーコンポーネントに使用するデフォルト名をユーザーに提示します。正確な XML テンプレートとデフォルト名については、references/territory-metadata.md を確認してください。

名前を表で提示します。

| Component | Default Name |
|-----------|-------------|
| Territory Type | Geographical |
| Territory Model | LSC Territory Model |
| Territory (Level 1 - Region) | RD - West 20D |
| Territory (Level 2 - District) | DM - San Francisco 20D02 |
| Territory (Level 3 - Territory) | TM - SPC - San Francisco North 20D02T11 |

2. これらの名前で問題ないか、または変更したいものがあるかをユーザーに確認します。各コンポーネントについて個別に質問してください。

   • 「テリトリー種別名 'Geographical' で問題ありませんか？それとも変更しますか？」
   • 「テリトリーモデル名 'LSC Territory Model' で問題ありませんか？それとも変更しますか？」
   • 「Region テリトリー名 'RD - West 20D' で問題ありませんか？それとも変更しますか？」
   • 「District テリトリー名 'DM - San Francisco 20D02' で問題ありませんか？それとも変更しますか？」
   • 「テリトリー名 'TM - SPC - San Francisco North 20D02T11' で問題ありませんか？それとも変更しますか？」

3. ユーザーが名前の変更を希望する場合は、使用したい新しい名前を尋ねてください。変更後の名前を記録します。

フェーズ 2 — プレビューして確認する

4. 確定した名前を使用した各コンポーネントの最終 XML を示し、作成される内容の完全なプレビューを表示します。references/territory-metadata.md のテンプレートを使用し、ユーザーが指定した名前があれば置き換えてください。

次の形式でプレビューを表示します。

=== Territory Type ===
Name: <confirmed name>
Priority: 1

=== Territory Model ===
Name: <confirmed model name>

=== Territory Hierarchy ===
Level 1 (Region): <confirmed region name>
  └── Level 2 (District): <confirmed district name>
        └── Level 3 (Territory): <confirmed territory name>

Access Levels (all territories):
- Account: Read
- Contact: Edit
- Case: None
- Opportunity: None

5. 最終確認を求めます：「これらのテリトリーコンポーネントを作成してデプロイしますか？（yes/no）」

ユーザーが no と答えた場合は、フェーズ 1 に戻ります。

フェーズ 3 — 作成とデプロイ

6. デプロイ用の一時的な SFDX プロジェクト構造を作成します。 正確なファイル構造と XML の内容については、references/territory-metadata.md を参照してください。

ディレクトリ構造は次のとおりです。

territory-deploy/
├── sfdx-project.json
└── force-app/
    └── main/
        └── default/
            └── territory2Models/
                ├── <ModelApiName>.territory2Model-meta.xml
                └── <ModelApiName>/
                    ├── territory2Types/
                    │   └── <TypeApiName>.territory2Type-meta.xml
                    └── territories/
                        ├── <Level1ApiName>.territory2-meta.xml
                        ├── <Level2ApiName>.territory2-meta.xml
                        └── <Level3ApiName>.territory2-meta.xml

7. ユーザーが確認した表示名から API 名を生成します。

   • 特殊文字、スペース、ハイフンを削除します
   • API 名には PascalCase を使用します
   • テリトリー種別の API 名は、種別の表示名から生成します
   • テリトリーモデルの API 名は、モデルの表示名から生成します（スペースを削除）
   • テリトリーの API 名は、テリトリーの表示名から生成します（スペース、ハイフン、特殊文字を削除）

8. 確認済みの名前を使用して、references/territory-metadata.md のテンプレートからメタデータファイルを作成します。

9. 次のコマンドでメタデータをデプロイします。

   sf project deploy start --source-dir territory-deploy/force-app --target-org <org>
   

10. デプロイのステータスを確認します。 失敗した場合は、エラーを表示して対処方法を提示します。

    停止ゲート（コンポーネント数）。 1 つのデプロイパッケージで、階層全体（Territory2Type 1 件、Territory2Model 1 件、Territory2 レコード 3 件（Region、District、Territory を各 1 件））をデプロイする必要があります。デプロイ結果でコンポーネントの失敗が 0 件であることを確認し、さらに有効化する前にテリトリーが存在することを確認します。

    sf data query --query "SELECT COUNT(Id) c FROM Territory2 WHERE Territory2Model.DeveloperName = '<ModelApiName>'" --target-org <org> --json
    

    件数は必ず 3 件でなければなりません。親参照の失敗（例：District が Region より先にデプロイされる）によって、階層が一部しかデプロイされないことがあります。Region へのパスがない Level-3 テリトリーは、ユーザーや訪問のテリトリー割り当てを下流で気付かれないまま破損させます。3 件すべてのテリトリーが存在し、デプロイの失敗が 0 件になるまで、モデルを有効化しないでください（フェーズ 4）。

フェーズ 4 — テリトリーモデルを有効化

11. モデルが Planning 状態でデプロイされたことを報告し、有効化するかどうかをユーザーに確認します。 次の警告を含めてください。

    注意： テリトリーモデルは、一度有効化すると無効化できますが、削除することはできません。有効化を進めますか？

12. **ユーザーが有効化を確認した場合、**モデルのレコード ID をクエリしてから、State を 'Activating' に更新してモデルを有効化します（'Active' ではありません。プラットフォームでは Activating → Active の遷移が非同期で行われます）。

    # モデル ID と現在の状態をクエリ
    sf data query --query "SELECT Id, State FROM Territory2Model WHERE DeveloperName = '<ModelApiName>' LIMIT 1" --target-org <org> --json
    

    モデルが Planning 状態の場合は、次のように更新します。

    sf data update record --sobject Territory2Model --record-id <ModelId> --values "State='Activating'" --target-org <org>
    

    エラー処理を含む有効化ロジックの全容については、references/territory-metadata.md を参照してください。

13. 有効化を確認します。 プラットフォームでは Activating → Active の遷移が非同期で行われます。次のクエリで確認してください。

    sf data query --query "SELECT Id, DeveloperName, State FROM Territory2Model WHERE DeveloperName='<ModelApiName>'" --target-org <org>
    

    まだ Activating の場合は、少し待ってから、Active になるまで再度クエリを実行します。

14. **ユーザーが有効化を希望しない場合は、**モデルが Planning 状態であり、後から Setup で有効化できることを報告します。

15. 成功を報告します。 すべてのコンポーネントが作成されたことをユーザーに確認し、モデルの現在の状態（Planning、Activating、または Active）を報告します。

---

ルール／制約

制約	理由
各レベルにつきテリトリーを1つだけ作成します。Level-1 Regionを1つ、Level-2 Districtを1つ、Level-3 Territoryを1つ作成します（テリトリーは合計3つ）。	スキルは、複数の子を持つツリー全体ではなく、代表的な階層の枝を1つ作成します
作成前に必ず名前を確認します	ユーザーは、組織に合わせてテリトリー名をカスタマイズしたい場合があります
デプロイ前にプレビューを表示します	ユーザーは、作成される内容を正確に確認できます
すべてのコンポーネントをまとめてデプロイします	テリトリー階層には依存関係（親への参照）があります
有効化前に、一度有効になるとモデルを削除できないことをユーザーに警告します	取り消せない操作のため、ユーザーの明示的な同意が必要です
レコードの更新時に、Stateを'Active'ではなく'Activating'に設定します	プラットフォームがActivatingからActiveへの非同期遷移を処理します
--record-id <ModelId>または--where "DeveloperName='<ModelApiName>'"を指定して更新対象を指定します	どちらの形式もsf data update recordで使用できます。使いやすい方を選んでください
デプロイ後に一時ディレクトリを削除します	デプロイの成果物を残さないでください

---

注意事項

問題	解決方法
同じ名前のテリトリーモデルがすでに存在する	まずクエリで確認し、別の名前にするかユーザーに尋ねます
テリトリータイプがすでに存在する	まず確認し、一致する場合は既存のタイプを再利用します
親テリトリーが見つからずデプロイに失敗する	すべてのテリトリーが同じデプロイパッケージに含まれていることを確認します
Stateを'Active'に直接設定するとINVALID_STATUSエラーが発生する	Stateは必ず'Activating'に設定します。プラットフォームが非同期でActiveに遷移させます
更新後もモデルの状態がActivatingと表示される	これは正常です。有効化は非同期で行われます。Activeになるまで待ってから再クエリします
API名が競合する	生成されたAPI名が既存のメタデータと競合しないことを確認します

---

出力要件

成果物：

• 確認済みの名前で作成されたテリトリータイプ
• 確認済みの名前で作成されたテリトリーモデル
• 確認済みの名前で作成された3レベルのテリトリー階層
• 有効化されたテリトリーモデル（プログラムによる有効化に失敗した場合は、手動で有効化する手順）
• 作成されたすべてのコンポーネントとそのステータスを示す確認メッセージ

---

参照ファイル一覧

ファイル	読むタイミング
references/territory-metadata.md	すべてのフェーズ。テリトリーコンポーネントのXMLテンプレート、ファイル構造、デフォルト値が含まれています