platform-custom-field-generate

# Salesforce Custom Field Generator and Validator ## Overview Generates and validates Salesforce CustomField metadata XML, with special handling for the **highest-failure-rate types** — Roll-Up Summary and Master-Detail. The agent must verify the constraints below before outputting XML to prevent Metadata API deployment errors. --- ## 1. Universal Mandatory Attributes Every generated field must include these tags: | Attribute | Requirement | Notes | |-----------|-------------|-------| | `<fullName>` | Required | **Field** name only: derive 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`. This rule is for the FIELD name. **Picklist VALUE `<fullName>` is different — keep it exactly as the user spelled it, spaces and all, no `__c`** (e.g. `Closed Won`, NOT `Closed_Won`). See [`references/advanced-picklists.md`](references/advanced-picklists.md) (ref §3). | | `<label>` | Required | The UI name (Title Case) | | `<description>` | Always include | Explain the business reason *why* this field exists. | | `<inlineHelpText>` | Always include | Actionable end-user guidance that adds value beyond the label (e.g., "Enter the value in USD including tax", not "The amount"). | `<description>` and `<inlineHelpText>` are mandatory even though the Metadata API does not enforce them — omitting them yields low-quality metadata. **File path (SFDX source format):** save each field as `force-app/main/default/objects/<Object>/fields/<FieldName>__c.field-meta.xml`, where `<Object>` is the object's API name (`Account`, `Opportunity`, or a custom `Inventory_Item__c`). A correct XML at the wrong path is never seen by the Metadata API. ### External ID Configuration **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 --- ## 2. Precision, Scale, and Length Rules 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` ### The "Fixed 255" Rule **TextArea: do NOT include `<length>`** — the API fixes it at 255 implicitly and rejects an explicit value ("Can not specify 'length' for a CustomField of type TextArea"). The field needs only `<fullName>`, `<label>`, and `<type>TextArea</type>`. ### Visible Lines Mandatory for Long/Rich text and Multi-select picklists to control UI height. --- ## 3. Field Data Types ### 3.1 Simple Attribute Types | 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` containing EITHER `valueSetDefinition` (inline) OR `valueSetName` (reference); `restricted` (see "Picklist `restricted` default" below; advanced cases in §3.4) | | Text | `Text` | `length` (Max 255) | | Text Area | `TextArea` | None — do NOT include `<length>`; the API fixes length at 255 implicitly | | 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 | ### 3.2 Computed & Multi-Value Types | Type | `<type>` Value | Required Attributes | |------|----------------|---------------------| | Formula | Result type (e.g., `Number`) | `formula`, `formulaTreatBlanksAs` | | Roll-Up Summary | `Summary` | See Section 5 for complete requirements | | Multi-Select Picklist | `MultiselectPicklist` | `valueSet`, `visibleLines` (default 4) | ### 3.3 Specialized Types | Type | `<type>` Value | Required Attributes | |------|----------------|---------------------| | Geolocation | `Location` | `scale`, `displayLocationInDecimal` | ### Picklist `restricted` default **Always set `<restricted>true</restricted>`** inside `<valueSet>` unless the user explicitly says the picklist should accept custom values not in the admin-defined list (e.g. "unrestricted"/"open"). Restricted sets are capped at 1,000 total values (active + inactive). Minimal inline shape: ```xml <valueSet> <restricted>true</restricted> <valueSetDefinition> <sorted>false</sorted> <value><fullName>Option_A</fullName><default>false</default><label>Option A</label></value> </valueSetDefinition> </valueSet> ``` ### 3.4 Advanced Picklists The inline `<valueSetDefinition>` above is the simple case. Full rules and worked correct/incorrect examples for everything below are in [`references/advanced-picklists.md`](references/advanced-picklists.md) — load it for any non-trivial picklist. Section numbers in parentheses below (e.g. "ref §1") point to that reference file, not to this skill. The hard rules: - **Value-set reference (ref §1).** A `<valueSet>` holds EITHER `<valueSetName>` (reference) OR `<valueSetDefinition>` (inline) — **never both**. Reference by the **bare** developer name — Standard set `Industry`, GlobalValueSet `Priority_Levels` with **NO `__gvs`** and no `__c` (the `__gvs` suffix is org-storage display only; the Metadata API uses the bare name). A value-set-backed field is `<restricted>true</restricted>`. Creating the value set is the `platform-value-set-generate` skill's job; this one only references it. - **Value-name fidelity (ref §3).** A picklist value's `<fullName>`/`<label>` keep the user's exact text **including spaces** (`Closed Won`, never `Closed_Won`). The space→`_` + `__c` rule is for the FIELD name only. - **Dependent picklists (ref §2).** Use the **modern API 38.0+** form: `<controllingField>` + one `<valueSettings>` (`<controllingFieldValue>`+`<valueName>`) per pair; never the legacy `<picklist>`/`<picklistValues>`/`<controllingFieldValues>` tags. **Both** controlling and dependent fields MUST be `<restricted>true</restricted>`, even if the request doesn't say so. - **Enhanced value attributes (ref §3).** `<value>` entries also accept `<color>` (hex, leading `#`), `<isActive>` (`false` retires a value), and a value-level `<description>`. - **Scoping a picklist to a record type (ref §5).** Per-record-type value visibility lives on the **RecordType** (`<picklistValues>`), not the field. The RecordType file carries its own `<fullName>` (bare developer name). **First decide if the object needs a BusinessProcess:** only **Opportunity / Lead / Case / Solution** require one — they won't deploy without a `<businessProcess>` (`Required field is missing: businessProcess`), even when only a custom picklist is filtered. There you emit **two coupled files**: the `businessProcesses/<Name>.businessProcess-meta.xml` file AND a matching `<businessProcess><Name></businessProcess>` inside the `<RecordType>` (after `<active>`, before `<picklistValues>`; the `<fullName>` in the BP file is **bare**, never object-qualified). **Custom objects (`*__c`) and all other standard objects (Account, Contact, …) need NO BusinessProcess — emit the RecordType alone; do not invent one.** **Scope limit:** picklist-value visibility per record type only — NOT general record-type authoring (compact layouts, page layouts, branding). --- ## 4. Master-Detail Relationship Rules CRITICAL Master-Detail fields have **strict attribute restrictions** that differ from Lookup fields. Violating these rules causes deployment failures. ### Forbidden Attributes on Master-Detail Fields **NEVER include these attributes on Master-Detail fields:** | Forbidden Attribute | Why | What Happens | |---------------------|-----|--------------| | `<required>` | Master-Detail is ALWAYS required by design | Deployment error | | `<deleteConstraint>` | Master-Detail ALWAYS cascades deletes | Deployment error | | `<lookupFilter>` | Only supported on Lookup fields | Deployment error | ### Master-Detail vs Lookup Comparison | Attribute | Master-Detail | Lookup | |-----------|---------------|--------| | `<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 | ### INCORRECT — Master-Detail with forbidden attributes: ```xml <CustomField xmlns="http://soap.sforce.com/2006/04/metadata"> <fullName>Account__c</fullName> <type>MasterDetail</type> <referenceTo>Account</referenceTo> <relationshipName>Contacts</relationshipName> <relationshipOrder>0</relationshipOrder> <required>true</required> <!-- WRONG: remove --> <deleteConstraint>Cascade</deleteConstraint> <!-- WRONG: remove --> <lookupFilter>...</lookupFilter> <!-- WRONG: remove entire block --> </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: ```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> ``` ### CORRECT — Lookup field (with optional attributes): ```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>