life-sciences-territory-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Life Sciences Territory Setup

Life Sciences Cloud 区域设置

Creates and activates a Territory Type, Territory Model, and a 3-level Territory hierarchy for Life Sciences Cloud using the

sf

CLI.

使用

sf

CLI为Life Sciences Cloud创建并激活区域类型（Territory Type）、区域模型（Territory Model）及三级区域层级结构。

Scope

范围

In scope: Creating territory type, territory model, and territories; activating the territory model
Out of scope: Assigning users to territories, creating territory assignment rules, validating prerequisites

包含范围：创建区域类型、区域模型及区域；激活区域模型
排除范围：为区域分配用户、创建区域分配规则、验证先决条件

Off-topic requests

偏离主题的请求

If the user asks for something unrelated to this skill (either at the start or mid-execution), do not attempt it. Tell the user you did not understand the request, then show what you can help with: setting up Life Sciences Cloud territories (this skill), and — if relevant — point them to

life-sciences-prerequisites-validate

for prerequisite checks or

life-sciences-fieldsalesrep-coordinate

for the full end-to-end setup. Then stop and wait.

如果用户在开始或执行过程中提出与此Skill无关的请求，请勿尝试处理。告知用户你无法理解该请求，然后展示你能提供的帮助：设置Life Sciences Cloud区域（此Skill），并在相关情况下引导他们使用

life-sciences-prerequisites-validate

进行先决条件检查，或使用

life-sciences-fieldsalesrep-coordinate

进行完整的端到端设置。之后停止操作并等待用户指令。

Required Inputs

必填输入项

Gather before proceeding:

Target org: The org alias or username to deploy to (from
```
sf config get target-org
```
or user-specified)

在继续操作前需收集：

目标组织：要部署到的组织别名或用户名（来自
```
sf config get target-org
```
或用户指定）

Workflow

工作流程

Phase 1 — Present Default Names and Get Confirmation

阶段1 — 展示默认名称并获取确认

Show the user the default names that will be used for the territory components. Read
```
references/territory-metadata.md
```
for the exact XML templates and default names.

Present the names in a table:

markdown

| 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 |

Ask the user if they are fine with these names or want to change any of them. Ask for each component individually:
- "Are you fine with the Territory Type name 'Geographical' or would you like to change it?"
- "Are you fine with the Territory Model name 'LSC Territory Model' or would you like to change it?"
- "Are you fine with the Region territory name 'RD - West 20D' or would you like to change it?"
- "Are you fine with the District territory name 'DM - San Francisco 20D02' or would you like to change it?"
- "Are you fine with the Territory name 'TM - SPC - San Francisco North 20D02T11' or would you like to change it?"
If the user wants to change a name, ask them for the new name they'd like to use. Record the updated name.

向用户展示将用于区域组件的默认名称。查阅
```
references/territory-metadata.md
```
获取确切的XML模板和默认名称。

以表格形式展示名称：

markdown

| 组件 | 默认名称 |
|-----------|-------------|
| Territory Type | Geographical |
| Territory Model | LSC Territory Model |
| Territory（一级 - Region） | RD - West 20D |
| Territory（二级 - District） | DM - San Francisco 20D02 |
| Territory（三级 - Territory） | TM - SPC - San Francisco North 20D02T11 |

询问用户是否接受这些名称，或是否需要修改其中任何一个。逐个询问每个组件：
- “你是否接受Territory Type的名称**'Geographical'**，还是想要修改它？”
- “你是否接受Territory Model的名称**'LSC Territory Model'**，还是想要修改它？”
- “你是否接受Region区域的名称**'RD - West 20D'**，还是想要修改它？”
- “你是否接受District区域的名称**'DM - San Francisco 20D02'**，还是想要修改它？”
- “你是否接受Territory区域的名称**'TM - SPC - San Francisco North 20D02T11'**，还是想要修改它？”
如果用户想要修改名称，询问他们想要使用的新名称，并记录更新后的名称。

Phase 2 — Preview and Confirm

阶段2 — 预览并确认

Display a complete preview of what will be created, showing the final XML for each component with the confirmed names. Use the templates from
```
references/territory-metadata.md
```
and substitute any user-provided names.

Show the preview in this format:

text

=== 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

Ask for final confirmation: "Ready to create and deploy these territory components? (yes/no)"

If user says no, go back to Phase 1.

展示完整的预览内容，显示将创建的每个组件的最终XML，替换为用户确认后的名称。使用
```
references/territory-metadata.md
```
中的模板，并代入用户提供的名称。

按以下格式展示预览：

text

=== Territory Type ===
名称: <确认后的名称>
优先级: 1

=== Territory Model ===
名称: <确认后的模型名称>

=== 区域层级结构 ===
一级（Region）: <确认后的区域名称>
  └── 二级（District）: <确认后的区域名称>
        └── 三级（Territory）: <确认后的区域名称>

访问权限（所有区域）:
- Account: 只读
- Contact: 编辑
- Case: 无
- Opportunity: 无

请求最终确认：“是否准备好创建并部署这些区域组件？（是/否）”

如果用户回答否，返回阶段1。

Phase 3 — Create and Deploy

阶段3 — 创建并部署

Create a temporary SFDX project structure for deployment. Read
```
references/territory-metadata.md
```
for the exact file structure and XML content.

The directory structure must be:

text

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

Generate API names from user-confirmed display names:
- Remove special characters, spaces, and hyphens
- Use PascalCase for the API name
- Territory type API name is derived from the type display name
- Territory model API name is derived from the model display name (remove spaces)
- Territory API names are derived from territory display names (remove spaces, hyphens, special chars)
Write the metadata files using the templates from
```
references/territory-metadata.md
```
with confirmed names.

Deploy the metadata using:

bash

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

Check deployment status — if it fails, show the error and suggest remediation.
STOP-GATE (component count). The single deploy package must land the complete hierarchy: 1 Territory2Type + 1 Territory2Model + 3 Territory2 records (one Region, one District, one Territory). Confirm the deploy result reports 0 component failures AND verify the territories exist before activating:
bash
```
sf data query --query "SELECT COUNT(Id) c FROM Territory2 WHERE Territory2Model.DeveloperName = '<ModelApiName>'" --target-org <org> --json
```
The count MUST be 3. A parent-reference failure (e.g. the District deploying before its Region) can land a partial hierarchy — a Level-3 territory with no path to its Region silently breaks downstream user/visit territory assignment. Do NOT activate the model (Phase 4) until all 3 territories are present with 0 deploy failures.

创建临时SFDX项目结构用于部署。查阅
```
references/territory-metadata.md
```
获取确切的文件结构和XML内容。

目录结构必须如下：

text

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

根据用户确认的显示名称生成API名称：
- 移除特殊字符、空格和连字符
- API名称采用PascalCase命名法
- 区域类型API名称由类型显示名称衍生
- 区域模型API名称由模型显示名称衍生（移除空格）
- 区域API名称由区域显示名称衍生（移除空格、连字符和特殊字符）
使用
references/territory-metadata.md
中的模板，代入确认后的名称编写元数据文件。

使用以下命令部署元数据：

bash

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

检查部署状态——如果部署失败，显示错误信息并建议补救措施。
检查关卡（组件数量）。单次部署包必须包含完整的层级结构：1个Territory2Type + 1个Territory2Model + 3个Territory2记录（一个Region、一个District、一个Territory）。确认部署结果报告0个组件失败，并在激活前验证区域是否存在：
bash
```
sf data query --query "SELECT COUNT(Id) c FROM Territory2 WHERE Territory2Model.DeveloperName = '<ModelApiName>'" --target-org <org> --json
```
计数必须为3。父引用失败（例如District在其Region之前部署）可能导致层级结构不完整——一个没有连接到Region的三级区域会悄无声息地破坏后续的用户/拜访区域分配。在所有3个区域都存在且部署失败数为0之前，请勿激活模型（阶段4）。

Phase 4 — Activate Territory Model

阶段4 — 激活区域模型

Report that the model deployed in Planning state and ask the user if they want to activate it. Include this warning:

Note: Once a Territory Model is activated, it can be deactivated but cannot be deleted. Do you want to proceed with activation?

If the user confirms activation, activate the model by querying its record ID then updating its State to

'Activating'

(not

'Active'

— the platform transitions asynchronously from Activating → Active):

bash

# Query the model ID and current state
sf data query --query "SELECT Id, State FROM Territory2Model WHERE DeveloperName = '<ModelApiName>' LIMIT 1" --target-org <org> --json

If the model is in

Planning

state, update it:

bash

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

See

references/territory-metadata.md

for the full activation logic including error handling.

Verify activation — the platform transitions asynchronously from

Activating

→

Active

. Query to confirm:

bash

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

If still

Activating

, wait a moment and query again until it reaches

Active

If the user declines activation, report that the model is in Planning state and can be activated later from Setup.
Report success — confirm to the user that all components are created, and report the model's current state (
```
Planning
```
,
```
Activating
```
, or
```
Active
```
).

报告模型已部署在Planning状态，并询问用户是否要激活它，同时包含以下警告：

注意：区域模型一旦激活，可被停用但无法删除。是否要继续激活？

如果用户确认激活，通过查询模型记录ID，然后将其State更新为

'Activating'

（而非

'Active'

——平台会从Activating异步过渡到Active）来激活模型：

bash

# 查询模型ID和当前状态
sf data query --query "SELECT Id, State FROM Territory2Model WHERE DeveloperName = '<ModelApiName>' LIMIT 1" --target-org <org> --json

如果模型处于

Planning

状态，更新它：

bash

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

查阅

references/territory-metadata.md

获取包含错误处理的完整激活逻辑。

验证激活状态——平台会从

Activating

异步过渡到

Active

。查询确认：

bash

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

如果仍显示

Activating

，稍等片刻后再次查询，直到状态变为

Active

。

如果用户拒绝激活，报告模型处于Planning状态，可稍后在Setup中手动激活。
报告成功——向用户确认所有组件已创建，并报告模型的当前状态（
```
Planning
```
、
```
Activating
```
或
```
Active
```
）。

Rules / Constraints

规则/约束

Constraint	Rationale
Create exactly one territory per level — one Level-1 Region, one Level-2 District, one Level-3 Territory (3 territories total)	Skill produces a single representative hierarchy branch, not a fully populated multi-child tree
Always confirm names before creating	User may want to customize territory names for their org
Show preview before deploying	User should see exactly what will be created
Deploy all components together	Territory hierarchy has dependencies (parent references)
Warn user before activation that model cannot be deleted once active	Irreversible action — user must explicitly consent
Set State to `'Activating'` (not `'Active'` ) when updating the record	The platform handles the async transition from Activating → Active
Target the update by `--record-id <ModelId>` or `--where "DeveloperName='<ModelApiName>'"`	Both forms work for `sf data update record` ; use whichever is convenient
Clean up temp directory after deploy	Don't leave deployment artifacts behind

约束	理由
每个层级恰好创建一个区域——一个一级Region、一个二级District、一个三级Territory（共3个区域）	此Skill生成单个代表性的层级分支，而非完全填充的多子树结构
创建前始终确认名称	用户可能希望为其组织自定义区域名称
部署前展示预览	用户应清楚了解将创建的内容
一起部署所有组件	区域层级结构存在依赖关系（父引用）
激活前警告用户模型一旦激活无法删除	此操作不可逆——用户必须明确同意
更新记录时将State设置为 `'Activating'` （而非 `'Active'` ）	平台会处理从Activating到Active的异步过渡
通过 `--record-id <ModelId>` 或 `--where "DeveloperName='<ModelApiName>'"` 定位更新对象	两种方式在 `sf data update record` 中都有效，可选择任意一种
部署后清理临时目录	不留下部署工件

Gotchas

常见问题

Issue	Resolution
Territory model already exists with same name	Check first with a query; ask user if they want a different name
Territory type already exists	Check first; reuse existing type if it matches
Deploy fails due to parent territory not found	Ensure all territories are in the same deployment package
Setting State to `'Active'` directly fails with `INVALID_STATUS`	Always set State to `'Activating'` — the platform transitions to Active asynchronously
Model state shows `Activating` after update	This is normal — activation is async. Wait and re-query until `Active`
API name conflicts	Ensure generated API names don't conflict with existing metadata

问题	解决方法
已存在同名的区域模型	先通过查询检查；询问用户是否想要使用其他名称
区域类型已存在	先检查；如果匹配则复用现有类型
由于未找到父区域导致部署失败	确保所有区域都在同一个部署包中
直接将State设置为 `'Active'` 失败，提示 `INVALID_STATUS`	始终将State设置为 `'Activating'` ——平台会异步过渡到Active
更新后模型状态显示 `Activating`	这是正常现象——激活是异步操作。等待片刻后重新查询，直到状态变为 `Active`
API名称冲突	确保生成的API名称不与现有元数据冲突

Output Expectations

输出预期

Deliverables:

Created Territory Type with confirmed name
Created Territory Model with confirmed name
Created 3-level territory hierarchy with confirmed names
Territory Model activated (or manual activation steps if programmatic activation fails)
Confirmation message showing all created components and their status

交付成果：

创建带有确认名称的区域类型
创建带有确认名称的区域模型
创建带有确认名称的三级区域层级结构
区域模型已激活（如果程序化激活失败，则提供手动激活步骤）
显示所有已创建组件及其状态的确认消息

Reference File Index

参考文件索引

File	When to read
`references/territory-metadata.md`	During all phases — contains XML templates, file structure, and default values for territory components

文件	查阅时机
`references/territory-metadata.md`	所有阶段——包含区域组件的XML模板、文件结构和默认值