Back to Details

generating-custom-field

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When to Use This Skill

何时使用此技能

Use this skill when you need to:
  • Create custom fields on any object
  • Generate field metadata for any field type
  • Set up relationship fields (Lookup or Master-Detail)
  • Create formula or roll-up summary fields
  • Troubleshoot deployment errors related to custom fields
当你需要以下操作时，使用此技能：
  • 在任何对象上创建自定义字段
  • 为任意字段类型生成字段元数据
  • 设置关系字段（Lookup或Master-Detail）
  • 创建公式字段或Roll-up Summary字段
  • 排查与自定义字段相关的部署错误

Salesforce Custom Field Generator and Validator

Salesforce自定义字段生成器与验证器

Overview

概述

Generate and validate Salesforce Custom Field metadata with mandatory constraints to prevent deployment errors. This skill has special focus on the highest-failure-rate field types: Roll-up Summary and Master-Detail relationships.
生成并验证带有强制约束的Salesforce Custom Field元数据，以避免部署错误。此技能重点关注失败率最高的字段类型：Roll-up Summary和Master-Detail关系。

Specification

规范

1. Purpose

1. 目的

This document defines the mandatory constraints for generating CustomField metadata XML. The agent must verify these constraints before outputting XML to prevent Metadata API deployment errors.
Critical Focus Areas:
  • Roll-up Summary field format errors
  • Master-Detail field attribute restrictions
  • Lookup Filter restrictions
本文档定义了生成CustomField元数据XML的强制约束。Agent在输出XML前必须验证这些约束，以防止Metadata API部署错误。
核心关注领域：
  • Roll-up Summary字段格式错误
  • Master-Detail字段属性限制
  • Lookup筛选器限制

2. Universal Mandatory Attributes

2. 通用强制属性

Every generated field must include these tags:
AttributeRequirementNotes
<fullName>
RequiredDerive from 
<label>
: capitalize each word, replace spaces with 
_
, append 
__c
. Must start with a letter. E.g., label 
Total Contract Value
→ 
Total_Contract_Value__c
<label>
RequiredThe UI name (Title Case)
<description>
MandatoryState the business "why" behind the field
<inlineHelpText>
MandatoryProvide actionable guidance for the end-user. Must add value beyond the label (e.g., "Enter the value in USD including tax" instead of just "The amount")
每个生成的字段必须包含以下标签：
属性要求说明
<fullName>
必填从
<label>
派生：每个单词首字母大写，空格替换为
_
，末尾追加
__c
。必须以字母开头。示例：标签
Total Contract Value
→ 
Total_Contract_Value__c
<label>
必填UI显示名称（标题大小写）
<description>
必填说明字段背后的业务用途
<inlineHelpText>
必填为终端用户提供可操作的指导。内容需超出标签本身的价值（例如："输入包含税费的USD金额"而非仅"金额"）

External ID Configuration

外部ID配置

Trigger: If the user mentions "integration," "importing data," "external system ID," or "unique key from [System Name]," set 
<externalId>true</externalId>
.
Applicable Types: Text, Number, Email
触发条件： 如果用户提及"集成"、"导入数据"、"外部系统ID"或"来自[系统名称]的唯一键"，设置
<externalId>true</externalId>
。
适用类型： 文本、数字、邮箱

3. Technical Interplay: Precision, Scale, and Length

3. 技术交互：精度、小数位数与长度

To ensure deployment success, follow these mathematical constraints:
为确保部署成功，请遵循以下数学约束：

Precision vs. Scale Rules

精度与小数位数规则

  • precision
    is the total digits; 
    scale
    is the decimal digits
  • Rule: 
    precision ≤ 18
    AND 
    scale ≤ precision
  • Calculation: Digits to the left of decimal = 
    precision - scale
  • precision
    为总位数；
    scale
    为小数位数
  • 规则： 
    precision ≤ 18
    且 
    scale ≤ precision
  • 计算： 小数点左侧位数 = 
    precision - scale

The "Fixed 255" Rule

"固定255"规则

For standard TextArea types, the Metadata API requires 
<length>255</length>
, even though it isn't configurable in the UI.
对于标准TextArea类型，Metadata API要求设置
<length>255</length>
，即使在UI中无法配置该值。

Visible Lines

可见行数

Mandatory for Long/Rich text and Multi-select picklists to control UI height.
长文本/富文本和多选选择列表必须设置该属性，以控制UI高度。

4. Field Data Types

4. 字段数据类型

4.1 Simple Attribute Types

4.1 简单属性类型

Type
<type>
Value		Required Attributes
Auto Number
AutoNumber
displayFormat
(must include 
{0}
), 
startingNumber
Checkbox
Checkbox
Default 
defaultValue
to 
false
Date
Date
No precision/length required
Date/Time
DateTime
No precision/length required
Email
Email
Built-in format validation
Lookup Relationship
Lookup
referenceTo
, 
relationshipName
, 
deleteConstraint
Master-Detail Relationship
MasterDetail
referenceTo
, 
relationshipName
, 
relationshipOrder
Number
Number
precision
, 
scale
Currency
Currency
Default precision: 18, scale: 2
Percent
Percent
Default precision: 5, scale: 2
Phone
Phone
Standardizes phone number formatting
Picklist
Picklist
valueSet
with 
valueSetDefinition
and 
restricted
Text
Text
length
(Max 255)
Text Area
TextArea
<length>255</length>
Text (Long)
LongTextArea
length
, 
visibleLines
(default 3)
Text (Rich)
Html
length
, 
visibleLines
(default 25)
Time
Time
Stores time only (no date)
URL
Url
Validates for protocol and format
类型
<type>
值		必填属性
自动编号
AutoNumber
displayFormat
（必须包含
{0}
）、
startingNumber
复选框
Checkbox
默认
defaultValue
为
false
日期
Date
无需精度/长度
日期/时间
DateTime
无需精度/长度
邮箱
Email
内置格式验证
Lookup关系
Lookup
referenceTo
、
relationshipName
、
deleteConstraint
Master-Detail关系
MasterDetail
referenceTo
、
relationshipName
、
relationshipOrder
数字
Number
precision
、
scale
货币
Currency
默认精度：18，小数位数：2
百分比
Percent
默认精度：5，小数位数：2
电话
Phone
标准化电话号码格式
选择列表
Picklist
包含
valueSetDefinition
和
restricted
的
valueSet
文本
Text
length
（最大255）
文本区域
TextArea
<length>255</length>
长文本
LongTextArea
length
、
visibleLines
（默认3）
富文本
Html
length
、
visibleLines
（默认25）
时间
Time
仅存储时间（不含日期）
URL
Url
验证协议与格式

4.2 Computed & Multi-Value Types

4.2 计算型与多值类型

Type
<type>
Value		Required Attributes
FormulaResult type (e.g., 
Number
)
formula
, 
formulaTreatBlanksAs
Roll-Up Summary
Summary
See Section 6 for complete requirements
Multi-Select Picklist
MultiselectPicklist
valueSet
, 
visibleLines
(default 4)
类型
<type>
值		必填属性
公式结果类型（例如
Number
）
formula
、
formulaTreatBlanksAs
Roll-Up Summary
Summary
详见第6节完整要求
多选选择列表
MultiselectPicklist
valueSet
、
visibleLines
（默认4）

4.3 Specialized Types

4.3 特殊类型

Type
<type>
Value		Required Attributes
Geolocation
Location
scale
, 
displayLocationInDecimal
类型
<type>
值		必填属性
地理位置
Location
scale
、
displayLocationInDecimal

Picklist 
restricted
Rule

选择列表
restricted
规则

The 
<restricted>
boolean inside 
<valueSet>
controls whether only admin-defined values are allowed.
  • IF user does not specify → default to 
    <restricted>true</restricted>
    (restricted, avoids performance issues with large picklist value sets)
  • IF user explicitly says the picklist should allow custom/new values, or mentions "unrestricted" or "open" → set 
    <restricted>false</restricted>
  • Restricted picklists are limited to 1,000 total values (active + inactive)
xml
<valueSet>
  <restricted>true</restricted>
  <valueSetDefinition>
    <sorted>false</sorted>
    <value>
      <fullName>Option_A</fullName>
      <default>false</default>
      <label>Option A</label>
    </value>
  </valueSetDefinition>
</valueSet>
<valueSet>
中的
<restricted>
布尔值控制是否仅允许管理员定义的值。
  • 如果用户未指定 → 默认设置为
    <restricted>true</restricted>
    （受限模式，避免大型选择列表值集的性能问题）
  • 如果用户明确说明选择列表应允许自定义/新值，或提及"不受限"或"开放" → 设置为
    <restricted>false</restricted>
  • 受限选择列表最多包含1000个值（激活+未激活）
xml
<valueSet>
  <restricted>true</restricted>
  <valueSetDefinition>
    <sorted>false</sorted>
    <value>
      <fullName>Option_A</fullName>
      <default>false</default>
      <label>Option A</label>
    </value>
  </valueSetDefinition>
</valueSet>

5. Master-Detail Relationship Rules ⭐ CRITICAL

5. Master-Detail关系规则 ⭐ 关键

Master-Detail fields have strict attribute restrictions that differ from Lookup fields. Violating these rules causes deployment failures.
Master-Detail字段有严格的属性限制，与Lookup字段不同。违反这些规则会导致部署失败。

Forbidden Attributes on Master-Detail Fields

Master-Detail字段的禁用属性

NEVER include these attributes on Master-Detail fields:
Forbidden AttributeWhyWhat Happens
<required>
Master-Detail is ALWAYS required by designDeployment error
<deleteConstraint>
Master-Detail ALWAYS cascades deletesDeployment error
<lookupFilter>
Only supported on Lookup fieldsDeployment error
绝对不能在Master-Detail字段中包含以下属性：
禁用属性原因后果
<required>
Master-Detail设计上始终为必填部署错误
<deleteConstraint>
Master-Detail始终级联删除部署错误
<lookupFilter>
仅支持Lookup字段部署错误

Master-Detail vs Lookup Comparison

Master-Detail与Lookup对比

AttributeMaster-DetailLookup
<required>
❌ FORBIDDEN✅ Optional
<deleteConstraint>
❌ FORBIDDEN (always CASCADE)✅ Required (
SetNull
, 
Restrict
, 
Cascade
)
<lookupFilter>
❌ FORBIDDEN✅ Optional
<relationshipOrder>
✅ Required (0 or 1)❌ Not applicable
<reparentableMasterDetail>
✅ Optional❌ Not applicable
<writeRequiresMasterRead>
✅ Optional❌ Not applicable
属性Master-DetailLookup
<required>
❌ 禁用✅ 可选
<deleteConstraint>
❌ 禁用（始终为CASCADE）✅ 必填（
SetNull
、
Restrict
、
Cascade
）
<lookupFilter>
❌ 禁用✅ 可选
<relationshipOrder>
✅ 必填（0或1）❌ 不适用
<reparentableMasterDetail>
✅ 可选❌ 不适用
<writeRequiresMasterRead>
✅ 可选❌ 不适用

❌ INCORRECT — Master-Detail with forbidden attributes:

❌ 错误示例 — 包含禁用属性的Master-Detail字段：

xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Account__c</fullName>
  <label>Account</label>
  <type>MasterDetail</type>
  <referenceTo>Account</referenceTo>
  <relationshipName>Contacts</relationshipName>
  <relationshipOrder>0</relationshipOrder>
  <required>true</required>           <!-- WRONG: Remove this -->
  <deleteConstraint>Cascade</deleteConstraint>  <!-- WRONG: Remove this -->
  <lookupFilter>                       <!-- WRONG: Remove this entire block -->
    <active>true</active>
    <filterItems>
      <field>Account.Type</field>
      <operation>equals</operation>
      <value>Customer</value>
    </filterItems>
  </lookupFilter>
</CustomField>
Errors:
  • Master-Detail Relationship Fields Cannot be Optional or Required
  • Can not specify 'deleteConstraint' for a CustomField of type MasterDetail
  • Lookup filters are only supported on Lookup Relationship Fields
xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Account__c</fullName>
  <label>Account</label>
  <type>MasterDetail</type>
  <referenceTo>Account</referenceTo>
  <relationshipName>Contacts</relationshipName>
  <relationshipOrder>0</relationshipOrder>
  <required>true</required>           <!-- 错误：移除该属性 -->
  <deleteConstraint>Cascade</deleteConstraint>  <!-- 错误：移除该属性 -->
  <lookupFilter>                       <!-- 错误：移除整个代码块 -->
    <active>true</active>
    <filterItems>
      <field>Account.Type</field>
      <operation>equals</operation>
      <value>Customer</value>
    </filterItems>
  </lookupFilter>
</CustomField>
错误信息：
  • Master-Detail Relationship Fields Cannot be Optional or Required
  • Can not specify 'deleteConstraint' for a CustomField of type MasterDetail
  • Lookup filters are only supported on Lookup Relationship Fields

✅ CORRECT — Master-Detail field:

✅ 正确示例 — Master-Detail字段：

xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Account__c</fullName>
  <label>Account</label>
  <description>Links this record to its parent Account</description>
  <type>MasterDetail</type>
  <referenceTo>Account</referenceTo>
  <relationshipLabel>Child Records</relationshipLabel>
  <relationshipName>ChildRecords</relationshipName>
  <relationshipOrder>0</relationshipOrder>
  <reparentableMasterDetail>false</reparentableMasterDetail>
  <writeRequiresMasterRead>false</writeRequiresMasterRead>
  <!-- NO required, deleteConstraint, or lookupFilter -->
</CustomField>
xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Account__c</fullName>
  <label>Account</label>
  <description>将此记录关联到其父级Account</description>
  <type>MasterDetail</type>
  <referenceTo>Account</referenceTo>
  <relationshipLabel>子记录</relationshipLabel>
  <relationshipName>ChildRecords</relationshipName>
  <relationshipOrder>0</relationshipOrder>
  <reparentableMasterDetail>false</reparentableMasterDetail>
  <writeRequiresMasterRead>false</writeRequiresMasterRead>
  <!-- 不包含required、deleteConstraint或lookupFilter -->
</CustomField>

✅ CORRECT — Lookup field (with optional attributes):

✅ 正确示例 — Lookup字段（包含可选属性）：

xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Related_Account__c</fullName>
  <label>Related Account</label>
  <description>Optional link to a related Account</description>
  <type>Lookup</type>
  <referenceTo>Account</referenceTo>
  <relationshipLabel>Related Records</relationshipLabel>
  <relationshipName>RelatedRecords</relationshipName>
  <required>false</required>
  <deleteConstraint>SetNull</deleteConstraint>
  <lookupFilter>
    <active>true</active>
    <filterItems>
      <field>Account.Type</field>
      <operation>equals</operation>
      <value>Customer</value>
    </filterItems>
    <isOptional>false</isOptional>
  </lookupFilter>
</CustomField>
xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Related_Account__c</fullName>
  <label>关联Account</label>
  <description>可选关联到相关Account</description>
  <type>Lookup</type>
  <referenceTo>Account</referenceTo>
  <relationshipLabel>关联记录</relationshipLabel>
  <relationshipName>RelatedRecords</relationshipName>
  <required>false</required>
  <deleteConstraint>SetNull</deleteConstraint>
  <lookupFilter>
    <active>true</active>
    <filterItems>
      <field>Account.Type</field>
      <operation>equals</operation>
      <value>Customer</value>
    </filterItems>
    <isOptional>false</isOptional>
  </lookupFilter>
</CustomField>

Additional Master-Detail Rules

额外Master-Detail规则

  • Relationship Order: First Master-Detail on object = 
    0
    , second = 
    1
  • Relationship Name: Must be a plural PascalCase string (e.g., 
    Travel_Bookings
    )
  • Junction Objects: Use two Master-Detail fields for standard many-to-many (enables Roll-ups)
  • Limit: Maximum 2 Master-Detail relationships per object. Use Lookup for additional relationships.
  • 关系顺序： 对象上的第一个Master-Detail字段设为
    0
    ，第二个设为
    1
  • 关系名称： 必须为复数帕斯卡命名法字符串（例如
    Travel_Bookings
    ）
  • 连接对象： 使用两个Master-Detail字段实现标准多对多关系（支持Roll-up）
  • 限制： 每个对象最多支持2个Master-Detail关系。额外关系请使用Lookup。

6. Roll-Up Summary Field Rules ⭐ CRITICAL

6. Roll-Up Summary字段规则 ⭐ 关键

Roll-up Summary fields have the highest deployment failure rate. Follow these rules exactly.
Roll-Up Summary字段的部署失败率最高。请严格遵循以下规则。

Required Elements for Roll-Up Summary

Roll-Up Summary必填元素

ElementRequirementFormat
<type>
RequiredAlways 
Summary
<summaryOperation>
Required
count
, 
sum
, 
min
, or 
max
<summaryForeignKey>
Required
ChildObject__c.MasterDetailField__c
<summarizedField>
ConditionalRequired for 
sum
, 
min
, 
max
. NOT for 
count
元素要求格式
<type>
必填始终为
Summary
<summaryOperation>
必填
count
、
sum
、
min
或
max
<summaryForeignKey>
必填
ChildObject__c.MasterDetailField__c
<summarizedField>
条件必填
sum
、
min
、
max
操作时必填，
count
操作时无需

Forbidden Elements on Roll-Up Summary

Roll-Up Summary禁用元素

NEVER include these attributes on Roll-Up Summary fields:
Forbidden AttributeWhy
<precision>
Summary inherits from summarized field
<scale>
Summary inherits from summarized field
<required>
Not applicable to Summary fields
<length>
Not applicable to Summary fields
绝对不能在Roll-Up Summary字段中包含以下属性：
禁用属性原因
<precision>
Summary继承自被汇总字段的精度
<scale>
Summary继承自被汇总字段的小数位数
<required>
不适用于Summary字段
<length>
不适用于Summary字段

Format Rules for summaryForeignKey and summarizedField

summaryForeignKey与summarizedField格式规则

CRITICAL: Both 
summaryForeignKey
and 
summarizedField
MUST use the fully qualified format:
ChildObjectAPIName__c.FieldAPIName__c
Decision Logic:
  • summaryForeignKey
    = 
    ChildObject__c.MasterDetailFieldOnChild__c
  • summarizedField
    = 
    ChildObject__c.FieldToSummarize__c
关键： 
summaryForeignKey
和
summarizedField
必须使用完全限定格式：
ChildObjectAPIName__c.FieldAPIName__c
决策逻辑：
  • summaryForeignKey
    = 
    ChildObject__c.MasterDetailFieldOnChild__c
  • summarizedField
    = 
    ChildObject__c.FieldToSummarize__c

❌ INCORRECT — Roll-Up Summary with common errors:

❌ 错误示例 — 包含常见错误的Roll-Up Summary字段：

xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Total_Amount__c</fullName>
  <label>Total Amount</label>
  <type>Summary</type>
  <precision>18</precision>           <!-- WRONG: Remove - inherited from source -->
  <scale>2</scale>                    <!-- WRONG: Remove - inherited from source -->
  <summaryOperation>sum</summaryOperation>
  <summaryForeignKey>Order__c</summaryForeignKey>        <!-- WRONG: Missing field name -->
  <summarizedField>Amount__c</summarizedField>           <!-- WRONG: Missing object name -->
</CustomField>
Errors:
  • Can not specify 'precision' for a CustomField of type Summary
  • Must specify the name in the CustomObject.CustomField format (e.g. Account.MyNewCustomField)
xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Total_Amount__c</fullName>
  <label>Total Amount</label>
  <type>Summary</type>
  <precision>18</precision>           <!-- 错误：移除该属性 - 继承自源字段 -->
  <scale>2</scale>                    <!-- 错误：移除该属性 - 继承自源字段 -->
  <summaryOperation>sum</summaryOperation>
  <summaryForeignKey>Order__c</summaryForeignKey>        <!-- 错误：缺少字段名称 -->
  <summarizedField>Amount__c</summarizedField>           <!-- 错误：缺少对象名称 -->
</CustomField>
错误信息：
  • Can not specify 'precision' for a CustomField of type Summary
  • Must specify the name in the CustomObject.CustomField format (e.g. Account.MyNewCustomField)

✅ CORRECT — Roll-Up Summary (SUM operation):

✅ 正确示例 — Roll-Up Summary（SUM操作）：

xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Total_Amount__c</fullName>
  <label>Total Amount</label>
  <description>Sum of all line item amounts</description>
  <inlineHelpText>Automatically calculated from child line items</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>sum</summaryOperation>
  <summarizedField>Order_Line_Item__c.Amount__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
  <!-- NO precision, scale, required, or length -->
</CustomField>
xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Total_Amount__c</fullName>
  <label>Total Amount</label>
  <description>所有行项目金额的总和</description>
  <inlineHelpText>由子行项目自动计算得出</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>sum</summaryOperation>
  <summarizedField>Order_Line_Item__c.Amount__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
  <!-- 不包含precision、scale、required或length -->
</CustomField>

✅ CORRECT — Roll-Up Summary (COUNT operation):

✅ 正确示例 — Roll-Up Summary（COUNT操作）：

xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Line_Item_Count__c</fullName>
  <label>Line Item Count</label>
  <description>Count of related line items</description>
  <inlineHelpText>Automatically calculated from child records</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>count</summaryOperation>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
  <!-- NO summarizedField needed for COUNT -->
  <!-- NO precision, scale, required, or length -->
</CustomField>
xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Line_Item_Count__c</fullName>
  <label>行项目数量</label>
  <description>相关行项目的数量</description>
  <inlineHelpText>由子记录自动计算得出</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>count</summaryOperation>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
  <!-- COUNT操作无需summarizedField -->
  <!-- 不包含precision、scale、required或length -->
</CustomField>

✅ CORRECT — Roll-Up Summary (MIN operation):

✅ 正确示例 — Roll-Up Summary（MIN操作）：

xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Earliest_Due_Date__c</fullName>
  <label>Earliest Due Date</label>
  <description>Earliest due date among all line items</description>
  <inlineHelpText>Shows the soonest deadline</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>min</summaryOperation>
  <summarizedField>Order_Line_Item__c.Due_Date__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
</CustomField>
xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Earliest_Due_Date__c</fullName>
  <label>最早到期日</label>
  <description>所有行项目中的最早到期日</description>
  <inlineHelpText>显示最近的截止日期</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>min</summaryOperation>
  <summarizedField>Order_Line_Item__c.Due_Date__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
</CustomField>

✅ CORRECT — Roll-Up Summary (MAX operation):

✅ 正确示例 — Roll-Up Summary（MAX操作）：

xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Highest_Price__c</fullName>
  <label>Highest Price</label>
  <description>Maximum unit price among all line items</description>
  <inlineHelpText>Shows the most expensive item</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>max</summaryOperation>
  <summarizedField>Order_Line_Item__c.Unit_Price__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
</CustomField>
xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Highest_Price__c</fullName>
  <label>最高价格</label>
  <description>所有行项目中的最高单价</description>
  <inlineHelpText>显示最昂贵的项目</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>max</summaryOperation>
  <summarizedField>Order_Line_Item__c.Unit_Price__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
</CustomField>

Roll-Up Summary Quick Reference

Roll-Up Summary快速参考

OperationsummarizedField Required?Use Case
count
NOCount number of child records
sum
YESAdd up numeric values
min
YESFind smallest value
max
YESFind largest value
操作是否需要summarizedField？使用场景
count
否统计子记录数量
sum
是汇总数值
min
是查找最小值
max
是查找最大值

Roll-Up Summary Prerequisites

Roll-Up Summary前提条件

  • Roll-Up Summary fields can ONLY be created on the parent object in a Master-Detail relationship
  • The child object MUST have a Master-Detail field pointing to this parent
  • The summarized field must exist on the child object
  • Roll-Up Summary字段只能在Master-Detail关系的父对象上创建
  • 子对象必须有指向该父对象的Master-Detail字段
  • 被汇总字段必须存在于子对象上

7. Formula Field Rules

7. 公式字段规则

Formula Result Types

公式结果类型

A Formula is not a type itself. The 
<formula>
tag is added to a field whose 
<type>
is set to the result data type:
  • Checkbox
    , 
    Currency
    , 
    Date
    , 
    DateTime
    , 
    Number
    , 
    Percent
    , 
    Text
Formula本身不是一种类型。
<formula>
标签需添加到
<type>
设为结果数据类型的字段中：
  • Checkbox
    、
    Currency
    、
    Date
    、
    DateTime
    、
    Number
    、
    Percent
    、
    Text

Formula XML Generation Rules

公式XML生成规则

  • The contents of the 
    <formula>
    tag MUST be wrapped in a 
    <![CDATA[ ... ]]>
    section. This prevents the XML parser from interpreting formula operators (like 
    &
    , 
    <
    , 
    >
    ) as XML markup.
  • If the formula text itself contains the literal sequence 
    ]]>
    , escape it by breaking the CDATA block: e.g., 
    <![CDATA[Text_Field__c & "]]]]><![CDATA[>"]]>
  • NEVER use an attribute or tag named 
    returnType
    . This does not exist in the Metadata API. The 
    <type>
    tag defines the return data type of the formula result.
  • <formula>
    标签的内容必须包裹在
    <![CDATA[ ... ]]>
    中。这可防止XML解析器将公式运算符（如
    &
    、
    <
    、
    >
    ）视为XML标记。
  • 如果公式文本本身包含文字序列
    ]]>
    ，需通过拆分CDATA块进行转义：例如
    <![CDATA[Text_Field__c & "]]]]><![CDATA[>"]]>
  • 绝对不能使用名为
    returnType
    的属性或标签。Metadata API中不存在该属性。
    <type>
    标签定义公式结果的返回数据类型。

formulaTreatBlanksAs Rule

formulaTreatBlanksAs规则

Decision Logic:
  • IF formula result type = 
    Number
    , 
    Currency
    , or 
    Percent
    → set 
    <formulaTreatBlanksAs>BlankAsZero</formulaTreatBlanksAs>
  • IF formula result type = 
    Text
    , 
    Date
    , or 
    DateTime
    → set 
    <formulaTreatBlanksAs>BlankAsBlank</formulaTreatBlanksAs>
决策逻辑：
  • 如果公式结果类型为
    Number
    、
    Currency
    或
    Percent
    → 设置
    <formulaTreatBlanksAs>BlankAsZero</formulaTreatBlanksAs>
  • 如果公式结果类型为
    Text
    、
    Date
    或
    DateTime
    → 设置
    <formulaTreatBlanksAs>BlankAsBlank</formulaTreatBlanksAs>

❌ INCORRECT — Using Formula as type:

❌ 错误示例 — 将Formula作为类型：

xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Calculated_Value__c</fullName>
  <type>Formula</type>  <!-- WRONG: Formula is not a valid type -->
  <returnType>Number</returnType>  <!-- WRONG: returnType does not exist in Metadata API -->
  <formula>Field1__c + Field2__c</formula>  <!-- WRONG: Missing CDATA wrapper -->
</CustomField>
xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Calculated_Value__c</fullName>
  <type>Formula</type>  <!-- 错误：Formula不是有效类型 -->
  <returnType>Number</returnType>  <!-- 错误：returnType在Metadata API中不存在 -->
  <formula>Field1__c + Field2__c</formula>  <!-- 错误：缺少CDATA包裹 -->
</CustomField>

✅ CORRECT — Formula field:

✅ 正确示例 — 公式字段：

xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Calculated_Value__c</fullName>
  <label>Calculated Value</label>
  <description>Sum of Field1 and Field2</description>
  <type>Number</type>  <!-- Result type, not "Formula" -->
  <precision>18</precision>
  <scale>2</scale>
  <formula><![CDATA[Field1__c + Field2__c]]></formula>
  <formulaTreatBlanksAs>BlankAsZero</formulaTreatBlanksAs>
</CustomField>
xml
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Calculated_Value__c</fullName>
  <label>计算值</label>
  <description>Field1与Field2的总和</description>
  <type>Number</type>  <!-- 结果类型，而非"Formula" -->
  <precision>18</precision>
  <scale>2</scale>
  <formula><![CDATA[Field1__c + Field2__c]]></formula>
  <formulaTreatBlanksAs>BlankAsZero</formulaTreatBlanksAs>
</CustomField>

Formula Field Dependencies

公式字段依赖

Formula fields that reference other fields will fail deployment if the referenced field does not exist or has not been deployed yet. Ensure all referenced fields are deployed before the formula field.
引用其他字段的公式字段，如果被引用字段不存在或尚未部署，部署会失败。请确保所有被引用字段在公式字段之前部署。

Specific Function Guidelines

特定函数指南

FunctionRule
TEXT()
MUST NOT be used with Text fields. If the field is already Text, remove the 
TEXT()
wrapper.
CASE()
Last parameter is always the default value. Total parameter count MUST be even (value-result pairs + default).
VALUE()
MUST only be used with Text fields. If a Number is passed as parameter, remove the 
VALUE()
wrapper.
DAY()
MUST only be used with Date fields. If a DateTime field is used, convert it to Date first (e.g., 
DAY(DATEVALUE(DateTimeField__c))
).
MONTH()
MUST only be used with Date fields. If a DateTime field is used, convert it to Date first (e.g., 
MONTH(DATEVALUE(DateTimeField__c))
).
DATEVALUE()
MUST only be used with DateTime fields. If a Date field is used, remove the 
DATEVALUE()
wrapper.
ISPICKVAL()
MUST be used when checking equality of a Picklist field. NEVER use 
==
with Picklist fields.
ISCHANGED()
Use 
ISCHANGED()
to check if a field value has changed. Do not manually compare with 
PRIORVALUE()
.
函数规则
TEXT()
不能用于文本字段。如果字段已是文本类型，移除
TEXT()
包裹。
CASE()
最后一个参数始终为默认值。参数总数必须为偶数（值-结果对 + 默认值）。
VALUE()
只能用于文本字段。如果参数是数字，移除
VALUE()
包裹。
DAY()
只能用于日期字段。如果使用DateTime字段，需先转换为日期（例如
DAY(DATEVALUE(DateTimeField__c))
）。
MONTH()
只能用于日期字段。如果使用DateTime字段，需先转换为日期（例如
MONTH(DATEVALUE(DateTimeField__c))
）。
DATEVALUE()
只能用于DateTime字段。如果使用日期字段，移除
DATEVALUE()
包裹。
ISPICKVAL()
检查选择列表字段是否相等时必须使用。绝对不能使用
==
比较选择列表字段。
ISCHANGED()
使用
ISCHANGED()
检查字段值是否已更改。不要手动与
PRIORVALUE()
比较。

8. Common Deployment Errors

8. 常见部署错误

Error MessageCauseFix
ConversionError: Invalid XML tags or unable to find matching parent xml file for CustomField
XML comments placed before the root 
<CustomField>
element		Remove XML comments (
<!-- ... -->
) that appear before 
<CustomField>
in the 
.field-meta.xml
file
Field [FieldName] does not exist. Check spelling.
Referenced field does not exist or has not been deployed yetVerify the referenced field exists and is deployed before this field
DUPLICATE_DEVELOPER_NAME
Field fullName already exists on the objectUse a unique business-driven name
MAX_RELATIONSHIPS_EXCEEDED
More than 2 Master-Detail or 15 Lookup fields on the objectUse Lookup for 3rd+ Master-Detail; review Lookup count
Reserved keyword errorUsing 
Order__c
, 
Group__c
, etc.		Rename to 
Status_Order__c
, etc.
错误信息原因修复方案
ConversionError: Invalid XML tags or unable to find matching parent xml file for CustomField
XML注释位于根
<CustomField>
元素之前		移除
.field-meta.xml
文件中
<CustomField>
之前的XML注释（
<!-- ... -->
）
Field [FieldName] does not exist. Check spelling.
被引用字段不存在或尚未部署验证被引用字段已存在并在此字段之前部署
DUPLICATE_DEVELOPER_NAME
字段fullName已在对象上存在使用唯一的业务驱动名称
MAX_RELATIONSHIPS_EXCEEDED
对象上的Master-Detail关系超过2个或Lookup关系超过15个第三个及以上Master-Detail关系改用Lookup；检查Lookup数量
保留关键字错误使用
Order__c
、
Group__c
等		重命名为
Status_Order__c
等

9. Verification Checklist

9. 验证清单

Before generating CustomField XML, verify:
生成CustomField XML前，请验证：

Universal Checks

通用检查

  • Does 
    <fullName>
    use valid format and end in 
    __c
    ?
  • Are 
    <description>
    and 
    <inlineHelpText>
    both populated and meaningful?
  • Is 
    <label>
    in Title Case?
  • Are there no XML comments (
    <!-- ... -->
    ) before the root 
    <CustomField>
    element? (Comments before the root element break SDR's parser)
  • <fullName>
    格式是否有效且以
    __c
    结尾？
  • <description>
    和
    <inlineHelpText>
    是否已填充且有意义？
  • <label>
    是否为标题大小写？
  • 根
    <CustomField>
    元素之前是否没有XML注释（
    <!-- ... -->
    ）？（根元素前的注释会破坏SDR解析器）

Master-Detail Field Checks ⭐ CRITICAL

Master-Detail字段检查 ⭐ 关键

  • Is 
    <required>
    attribute ABSENT? (Master-Detail is always required)
  • Is 
    <deleteConstraint>
    attribute ABSENT? (Master-Detail always cascades)
  • Is 
    <lookupFilter>
    block ABSENT? (Only for Lookup fields)
  • Is 
    <relationshipOrder>
    set to 
    0
    or 
    1
    ?
  • Is parent object's 
    <sharingModel>
    set to 
    ControlledByParent
    ?
  • 是否未包含
    <required>
    属性？（Master-Detail始终为必填）
  • 是否未包含
    <deleteConstraint>
    属性？（Master-Detail始终级联删除）
  • 是否未包含
    <lookupFilter>
    代码块？（仅适用于Lookup字段）
  • <relationshipOrder>
    是否设为
    0
    或
    1
    ？
  • 父对象的
    <sharingModel>
    是否设为
    ControlledByParent
    ？

Lookup Field Checks

Lookup字段检查

  • Is 
    <deleteConstraint>
    set to 
    SetNull
    , 
    Restrict
    , or 
    Cascade
    ?
  • Is 
    <relationshipName>
    in plural PascalCase?
  • <deleteConstraint>
    是否设为
    SetNull
    、
    Restrict
    或
    Cascade
    ？
  • <relationshipName>
    是否为复数帕斯卡命名法？

Roll-Up Summary Field Checks ⭐ CRITICAL

Roll-Up Summary字段检查 ⭐ 关键

  • Is 
    <precision>
    attribute ABSENT?
  • Is 
    <scale>
    attribute ABSENT?
  • Is 
    <summaryForeignKey>
    in format 
    ChildObject__c.MasterDetailField__c
    ?
  • For SUM/MIN/MAX: Is 
    <summarizedField>
    in format 
    ChildObject__c.FieldName__c
    ?
  • For COUNT: Is 
    <summarizedField>
    ABSENT?
  • Does the child object have a Master-Detail field to this parent?
  • 是否未包含
    <precision>
    属性？
  • 是否未包含
    <scale>
    属性？
  • <summaryForeignKey>
    是否为
    ChildObject__c.MasterDetailField__c
    格式？
  • 对于SUM/MIN/MAX操作：
    <summarizedField>
    是否为
    ChildObject__c.FieldName__c
    格式？
  • 对于COUNT操作：是否未包含
    <summarizedField>
    ？
  • 子对象是否有指向该父对象的Master-Detail字段？

Formula Field Checks

公式字段检查

  • Is 
    <type>
    set to result type (NOT "Formula")?
  • Is 
    <formula>
    content wrapped in 
    <![CDATA[ ... ]]>
    ?
  • Is 
    <returnType>
    attribute ABSENT? (does not exist in Metadata API)
  • Is 
    <formulaTreatBlanksAs>
    set to 
    BlankAsZero
    for numeric results or 
    BlankAsBlank
    for text/date results?
  • Do all referenced fields exist and deploy before this field?
  • <type>
    是否设为结果类型（而非"Formula"）？
  • <formula>
    内容是否包裹在
    <![CDATA[ ... ]]>
    中？
  • 是否未包含
    <returnType>
    属性？（Metadata API中不存在）
  • <formulaTreatBlanksAs>
    是否针对数值结果设为
    BlankAsZero
    ，针对文本/日期结果设为
    BlankAsBlank
    ？
  • 所有被引用字段是否已存在并在此字段之前部署？

Numeric Field Checks

数字字段检查

  • Is 
    scale ≤ precision
    ?
  • Is 
    precision ≤ 18
    ?
  • 是否满足
    scale ≤ precision
    ？
  • 是否满足
    precision ≤ 18
    ？

Text Area Checks

文本区域检查

  • For TextArea: Is 
    <length>255</length>
    explicitly included?
  • For LongTextArea/Html: Is 
    <visibleLines>
    set?
  • 对于TextArea：是否明确包含
    <length>255</length>
    ？
  • 对于LongTextArea/Html：是否已设置
    <visibleLines>
    ？

Relationship Limit Checks

关系限制检查

  • Are there 2 or fewer Master-Detail relationships on the object?
  • Are there 15 or fewer Lookup relationships on the object?
  • 对象上的Master-Detail关系是否不超过2个？
  • 对象上的Lookup关系是否不超过15个？

Naming Checks

命名检查

  • Is the API name free of reserved words (
    Order
    , 
    Group
    , 
    Select
    , etc.)?
  • Is the API name unique on this object?
  • API名称是否不含保留字（
    Order
    、
    Group
    、
    Select
    等）？
  • API名称在该对象上是否唯一？