- 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
- Salesforce Custom Field Generator and Validator
- 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.
- Specification
- 1. Purpose
- 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
- 2. Universal Mandatory Attributes
- Every generated field must include these tags:
- Attribute
- Requirement
- Notes
- Required
- Derive from
- capitalize each word, replace spaces with _ , append __c . Must start with a letter. E.g., label Total Contract Value → Total_Contract_Value__c
< deleteConstraint
Cascade </ deleteConstraint
< lookupFilter
< 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 ✅ CORRECT — Master-Detail field: < 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
</ CustomField
✅ CORRECT — Lookup field (with optional attributes): < 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
Additional Master-Detail Rules 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. 6. Roll-Up Summary Field Rules ⭐ CRITICAL Roll-up Summary fields have the highest deployment failure rate . Follow these rules exactly. Required Elements for Roll-Up Summary Element Requirement Format
Required Always Summary Required count , sum , min , or max Required ChildObject__c.MasterDetailField__c Conditional Required for sum , min , max . NOT for count Forbidden Elements on Roll-Up Summary NEVER include these attributes on Roll-Up Summary fields: Forbidden Attribute Why Summary inherits from summarized field Summary inherits from summarized field Not applicable to Summary fields Not applicable to Summary fields Format Rules for summaryForeignKey and 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 ❌ INCORRECT — Roll-Up Summary with common errors: < 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
Errors: 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): < 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
</ CustomField
✅ CORRECT — Roll-Up Summary (COUNT operation): < 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
</ CustomField
✅ CORRECT — Roll-Up Summary (MIN operation): < 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
✅ CORRECT — Roll-Up Summary (MAX operation): < 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
Roll-Up Summary Quick Reference Operation summarizedField Required? Use Case count NO Count number of child records sum YES Add up numeric values min YES Find smallest value max YES Find largest value Roll-Up Summary Prerequisites 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 7. Formula Field Rules Formula Result Types A Formula is not a type itself. The
tag is added to a field whose is set to the result data type : Checkbox , Currency , Date , DateTime , Number , Percent , Text Formula XML Generation Rules The contents of the tag MUST be wrapped in a
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.,
NEVER use an attribute or tag named
returnType
. This does not exist in the Metadata API. The
< fullName
Calculated_Value__c </ fullName
< type
Formula </ type
< returnType
Number </ returnType
< formula
Field1__c + Field2__c </ formula
</ CustomField
✅ CORRECT — Formula field: < 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
< precision
18 </ precision
< scale
2 </ scale
< formula
</ 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 Function Rule 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() . 8. Common Deployment Errors Error Message Cause Fix ConversionError: Invalid XML tags or unable to find matching parent xml file for CustomField XML comments placed before the root
element Remove XML comments (
) that appear before
) before the root
?
Is