Back to Details

handling-sf-data

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Salesforce Data Operations Expert (handling-sf-data)

Salesforce数据操作专家（handling-sf-data）

Use this skill when the user needs Salesforce data work: record CRUD, bulk import/export, test data generation, cleanup scripts, or data factory patterns for validating Apex, Flow, or integration behavior.
当用户需要进行Salesforce数据处理工作时使用本技能：记录的增删改查（CRUD）、批量导入/导出、测试数据生成、清理脚本编写，或用于验证Apex、Flow或集成行为的数据工厂模式开发。

When This Skill Owns the Task

本技能负责的任务场景

Use 
handling-sf-data
when the work involves:
  • sf data
    CLI commands
  • record creation, update, delete, upsert, export, or tree import/export
  • realistic test data generation
  • bulk data operations and cleanup
  • Apex anonymous scripts for data seeding / rollback
Delegate elsewhere when the user is:
  • writing SOQL only → querying-soql
  • running or repairing Apex tests → running-apex-tests
  • deploying metadata first → deploying-metadata
  • creating or modifying custom objects / fields → generating-custom-object or generating-custom-field
当工作涉及以下内容时，使用
handling-sf-data
技能：
  • sf data
    CLI命令
  • 记录的创建、更新、删除、插入更新（upsert）、导出或树形导入/导出
  • 真实可信的测试数据生成
  • 批量数据操作与清理
  • 用于数据填充/回滚的匿名Apex脚本
当用户有以下需求时，请转交至对应技能：
  • 仅编写SOQL查询 → querying-soql
  • 运行或修复Apex测试 → running-apex-tests
  • 优先部署元数据 → deploying-metadata
  • 创建或修改自定义对象/字段 → generating-custom-object 或 generating-custom-field

Important Mode Decision

重要模式决策

Confirm which mode the user wants:
ModeUse when
Script generationthey want reusable 
.apex
, CSV, or JSON assets without touching an org yet
Remote executionthey want records created / changed in a real org now
Do not assume remote execution if the user may only want scripts.
确认用户需要的模式：
模式使用场景
脚本生成用户需要可复用的
.apex
、CSV或JSON资源，但暂不操作Salesforce组织
远程执行用户需要立即在真实Salesforce组织中创建/修改记录
请勿默认选择远程执行，若用户可能仅需要脚本则优先采用脚本生成模式。

Required Context to Gather First

需先收集的必要上下文信息

Ask for or infer:
  • target object(s)
  • org alias, if remote execution is required
  • operation type: query, create, update, delete, upsert, import, export, cleanup
  • expected volume
  • whether this is test data, migration data, or one-off troubleshooting data
  • any parent-child relationships that must exist first
询问或推断以下信息：
  • 目标对象
  • 若需远程执行，需提供组织别名
  • 操作类型：查询、创建、更新、删除、插入更新、导入、导出、清理
  • 预期数据量
  • 数据类型：测试数据、迁移数据还是一次性排查数据
  • 必须预先存在的父子关系

Core Operating Rules

核心操作规则

  • handling-sf-data
    acts on remote org data unless the user explicitly wants local script generation.
  • Objects and fields must already exist before data creation.
  • For automation testing, prefer 251+ records when bulk behavior matters.
  • Plan cleanup before creating large or noisy datasets — untracked records accumulate across runs and pollute org state.
  • Use synthetic, non-identifying data in test records — real PII creates compliance risk and cannot be safely removed after bulk import.
  • Prefer CLI-first for straightforward CRUD; use anonymous Apex when the operation truly needs server-side orchestration.
If metadata is missing, stop and hand off to:
  • generating-custom-object or generating-custom-field to create the missing schema, then deploying-metadata to deploy it before retrying the data operation
  • 除非用户明确要求本地脚本生成，否则
    handling-sf-data
    默认操作远程组织数据。
  • 创建数据前，对象和字段必须已存在。
  • 对于自动化测试，当批量行为至关重要时，优先使用251条以上记录。
  • 在创建大型或干扰性数据集前规划清理方案——未跟踪的记录会在多次运行后累积，污染组织状态。
  • 在测试记录中使用合成的非识别性数据——真实的个人身份信息（PII）会带来合规风险，且批量导入后无法安全删除。
  • 对于简单的增删改查操作，优先采用CLI优先的方式；仅当操作确实需要服务器端编排时，才使用匿名Apex。
若缺少元数据，请停止当前操作并转交至：
  • generating-custom-object 或 generating-custom-field 创建缺失的架构，然后通过deploying-metadata部署后再重试数据操作

Recommended Workflow

推荐工作流程

1. Verify prerequisites

1. 验证前提条件

Confirm object / field availability, org auth, and required parent records.
确认对象/字段的可用性、组织授权以及所需的父记录。

2. Run describe-first pre-flight validation when schema is uncertain

2. 当架构不确定时，先执行描述性预飞验证

Before creating or updating records, use object describe data to validate:
  • required fields
  • createable vs non-createable fields
  • picklist values
  • relationship fields and parent requirements
See references/sf-cli-data-commands.md for the 
sf sobject describe
command and jq filter patterns for inspecting fields, picklist values, and createable constraints.
在创建或更新记录前，使用对象描述数据验证：
  • 必填字段
  • 可创建与不可创建字段
  • 选择列表值
  • 关系字段与父记录要求
查看references/sf-cli-data-commands.md获取
sf sobject describe
命令以及用于检查字段、选择列表值和可创建约束的jq过滤模式。

3. Choose the smallest correct mechanism

3. 选择最合适的最小实现机制

NeedDefault approach
small one-off CRUD
sf data
single-record commands
large import/exportBulk API 2.0 via 
sf data ... bulk
parent-child seed settree import/export
reusable test datasetfactory / anonymous Apex script
reversible experimentcleanup script or savepoint-based approach
需求默认方案
小型一次性增删改查
sf data
单记录命令
大型导入/导出通过
sf data ... bulk
使用Bulk API 2.0
父子关系数据集填充树形导入/导出
可复用测试数据集工厂/匿名Apex脚本
可回滚实验清理脚本或基于保存点的方案

4. Execute or generate assets

4. 执行操作或生成资源

Use the built-in templates under 
assets/
when they fit:
  • assets/factories/
  • assets/bulk/
  • assets/cleanup/
  • assets/soql/
  • assets/csv/
  • assets/json/
当符合需求时，使用
assets/
下的内置模板：
  • assets/factories/
  • assets/bulk/
  • assets/cleanup/
  • assets/soql/
  • assets/csv/
  • assets/json/

5. Verify results

5. 验证结果

Check counts, relationships, and record IDs after creation or update.
创建或更新后，检查记录数量、关系和记录ID。

6. Apply a bounded retry strategy

6. 应用有限重试策略

If creation fails:
  1. try the primary CLI shape once
  2. retry once with corrected parameters
  3. re-run describe / validate assumptions
  4. pivot to a different mechanism or provide a manual workaround
Do not repeat the same failing command indefinitely.
若创建失败：
  1. 尝试一次主CLI命令
  2. 使用修正后的参数重试一次
  3. 重新执行描述/验证假设
  4. 切换到其他机制或提供手动解决方案
请勿无限重复执行相同的失败命令。

7. Leave cleanup guidance

7. 提供清理指导

Provide exact cleanup commands or rollback assets whenever data was created.
无论何时创建了数据，都要提供明确的清理命令或回滚资源。

High-Signal Rules

高优先级规则

Bulk safety

批量操作安全

  • use bulk operations for large volumes
  • test automation-sensitive behavior with 251+ records where appropriate
  • avoid one-record-at-a-time patterns for bulk scenarios
  • 针对大量数据使用批量操作
  • 在合适的场景下，使用251条以上记录测试对自动化敏感的行为
  • 批量场景下避免逐条记录操作的模式

Data integrity

数据完整性

  • include required fields
  • validate picklist values before creation
  • verify parent IDs and relationship integrity
  • account for validation rules and duplicate constraints
  • exclude non-createable fields from input payloads
  • 包含必填字段
  • 创建前验证选择列表值
  • 验证父记录ID和关系完整性
  • 考虑验证规则和重复约束
  • 从输入负载中排除不可创建字段

Cleanup discipline

清理规范

Prefer one of:
  • delete-by-ID
  • delete-by-pattern
  • delete-by-created-date window
  • rollback / savepoint patterns for script-based test runs
优先选择以下方式之一：
  • 按ID删除
  • 按模式删除
  • 按创建日期窗口删除
  • 基于脚本测试运行的回滚/保存点模式

Common Failure Patterns

常见失败模式

ErrorLikely causeDefault fix direction
INVALID_FIELD
wrong field API name or FLS issueverify schema and access
REQUIRED_FIELD_MISSING
mandatory field omittedinclude required values from describe data
INVALID_CROSS_REFERENCE_KEY
bad parent IDcreate / verify parent first
FIELD_CUSTOM_VALIDATION_EXCEPTION
validation rule blocked the recorduse valid test data or adjust setup
invalid picklist valueguessed value instead of describe-backed valueinspect picklist values first
non-writeable field errorfield is not createable / updateableremove it from the payload
bulk limits / timeoutswrong tool for the volumeswitch to bulk / staged import
错误可能原因默认修复方向
INVALID_FIELD
字段API名称错误或字段级安全性（FLS）问题验证架构和访问权限
REQUIRED_FIELD_MISSING
遗漏必填字段从描述数据中获取并包含必填值
INVALID_CROSS_REFERENCE_KEY
父记录ID无效先创建/验证父记录
FIELD_CUSTOM_VALIDATION_EXCEPTION
验证规则阻止了记录创建使用有效的测试数据或调整设置
无效选择列表值猜测值而非基于描述数据的有效值先检查选择列表值
不可写入字段错误字段不可创建/更新从负载中移除该字段
批量操作限制/超时工具不匹配数据量切换到批量/分段导入

Output Format

输出格式

When finishing, report in this order:
  1. Operation performed
  2. Objects and counts
  3. Target org or local artifact path
  4. Record IDs / output files
  5. Verification result
  6. Cleanup instructions
Suggested shape:
text
Data operation: <create / update / delete / export / seed>
Objects: <object + counts>
Target: <org alias or local path>
Artifacts: <record ids / csv / apex / json files>
Verification: <passed / partial / failed>
Cleanup: <exact delete or rollback guidance>
完成操作后，按以下顺序汇报：
  1. 执行的操作
  2. 对象与数量
  3. 目标组织或本地资源路径
  4. 记录ID/输出文件
  5. 验证结果
  6. 清理说明
建议格式：
text
数据操作：<创建/更新/删除/导出/填充>
对象：<对象名称 + 数量>
目标：<组织别名或本地路径>
资源：<记录ID / CSV / Apex / JSON文件>
验证结果：<通过/部分通过/失败>
清理：<明确的删除或回滚指导>

Cross-Skill Integration

跨技能集成

NeedDelegate toReason
create missing custom objectsgenerating-custom-objectschema must exist before data operations
create missing custom fieldsgenerating-custom-fieldfield-level schema must exist before data creation
run bulk-sensitive Apex validationrunning-apex-teststest execution and coverage
deploy missing schema firstdeploying-metadatametadata readiness
implement production Apex logic consuming the datagenerating-apexApex class / trigger authoring
implement Flow logic consuming the datagenerating-flowFlow authoring and automation
需求转交至原因
创建缺失的自定义对象generating-custom-object数据操作前必须先存在架构
创建缺失的自定义字段generating-custom-field创建数据前必须先存在字段级架构
运行对批量操作敏感的Apex验证running-apex-tests测试执行与覆盖率
先部署缺失的架构deploying-metadata元数据就绪性
实现使用该数据的生产级Apex逻辑generating-apexApex类/触发器编写
实现使用该数据的Flow逻辑generating-flowFlow编写与自动化

Reference Map

参考资源映射

Start here

入门参考

  • references/sf-cli-data-commands.md
  • references/test-data-best-practices.md
  • references/orchestration.md
  • references/test-data-patterns.md
  • references/test-data-factory-usage.md
  • references/sf-cli-data-commands.md
  • references/test-data-best-practices.md
  • references/orchestration.md
  • references/test-data-patterns.md
  • references/test-data-factory-usage.md

Query / bulk / cleanup

查询/批量/清理

  • references/soql-relationship-guide.md
  • references/relationship-query-examples.md
  • references/bulk-operations-guide.md
  • references/cleanup-rollback-guide.md
  • references/cleanup-rollback-example.md
  • references/soql-relationship-guide.md
  • references/relationship-query-examples.md
  • references/bulk-operations-guide.md
  • references/cleanup-rollback-guide.md
  • references/cleanup-rollback-example.md

Examples / limits

示例/限制

  • references/crud-workflow-example.md
  • references/bulk-testing-example.md
  • references/anonymous-apex-guide.md
  • references/governor-limits-reference.md
  • references/crud-workflow-example.md
  • references/bulk-testing-example.md
  • references/anonymous-apex-guide.md
  • references/governor-limits-reference.md

Validation scripts

验证脚本

  • scripts/soql_validator.py — validate SOQL queries before execution
  • scripts/validate_data_operation.py — pre-flight check for data operations (required fields, picklist values, createable fields)
  • scripts/soql_validator.py — 执行前验证SOQL查询
  • scripts/validate_data_operation.py — 数据操作预飞检查（必填字段、选择列表值、可创建字段）

Asset templates

资源模板

  • assets/factories/
    — Apex test data factory scripts (account, contact, opportunity, lead, user, etc.)
  • assets/bulk/
    — Bulk API 2.0 Apex templates (insert 200, 500, 10000 records; upsert by external ID)
  • assets/cleanup/
    — Cleanup and rollback scripts (delete by name, date, pattern; transaction rollback)
  • assets/soql/
    — SOQL query templates (aggregate, subquery, parent-to-child, child-to-parent, polymorphic)
  • assets/csv/
    — CSV import templates for Account, Contact, Opportunity, custom objects
  • assets/json/
    — JSON tree import templates (account-contact, account-opportunity, full hierarchy)
  • assets/factories/
    — Apex测试数据工厂脚本（客户、联系人、商机、线索、用户等）
  • assets/bulk/
    — Bulk API 2.0 Apex模板（插入200、500、10000条记录；按外部ID插入更新）
  • assets/cleanup/
    — 清理与回滚脚本（按名称、日期、模式删除；事务回滚）
  • assets/soql/
    — SOQL查询模板（聚合、子查询、父到子、子到父、多态）
  • assets/csv/
    — 客户、联系人、商机、自定义对象的CSV导入模板
  • assets/json/
    — JSON树形导入模板（客户-联系人、客户-商机、完整层级）

Score Guide

评分指南

ScoreMeaning
117+strong production-safe data workflow
104–116good operation with minor improvements possible
91–103acceptable but review advised
78–90partial / risky patterns present
< 78blocked until corrected
分数含义
117+可靠的生产级安全数据工作流
104–116良好的操作，存在少量可优化点
91–103可接受，但建议复查
78–90存在部分/高风险模式
< 78需修正后才能继续