Skip to content

PranavNagrecha/AwesomeSalesforceSkills / skills/admin/custom-field-creation

custom-field-creation

Verified

Use when creating a new custom field on any Salesforce object: choosing field type, setting API name, configuring Field-Level Security, adding to page layouts, and deploying. Triggers: 'add a field', 'new custom field', 'what field type should I use', 'FLS not working', 'field not showing on page layout'. NOT for creating the object itself - use admin/object-creation-and-design. NOT for formula field logic - use admin/formula-fields. NOT for picklist value set management - use admin/picklist-and-value-sets. Also covers: field-meta.xml, CustomField metadata, deleteConstraint, externalId, unique, precision and scale, relationshipOrder, writeRequiresMasterRead, fieldPermissions, package.xml for fields.

references/examples.md

View on GitHub
# Examples — Custom Field Creation

## Example 1: Sales Team Needs a Region Field on Opportunity

**Context:** A sales operations manager wants to capture the sales region on every Opportunity so that regional dashboards and assignment rules can use the data. The valid regions are fixed: North America, EMEA, APAC, LATAM.

**Problem:** The admin creates a Text field named "Region" and sets its length to 255. Users start entering inconsistent values ("NA", "N. America", "North America") that break dashboard filters. The admin has no way to enforce consistent values with a Text field without a validation rule and a hard-coded list.

**Solution:**

Create a Picklist field instead:

1. Object Manager → Opportunity → Fields & Relationships → New.
2. Select **Picklist** as the field type.
3. Label: `Sales Region`, API Name: `Sales_Region__c`.
4. Add values: `North America`, `EMEA`, `APAC`, `LATAM`. Leave "Sort values alphabetically" unchecked so values appear in the business-preferred order.
5. Set FLS: Read + Edit for Sales Rep profile, Sales Manager profile. Read-only for reporting profiles.
6. Add to Opportunity page layouts for Sales Rep and Sales Manager.
7. Mark field as Required if every opportunity must have a region before it can be moved to any closed stage.

**Why it works:** Picklist enforces a controlled vocabulary. Users cannot enter free-form text. Reports and dashboards filter on exact picklist API values, which are stable even if the label changes. FLS restricts edit access to prevent unauthorized value changes.

**The evidence, before and after.** Run this against the Text version of the field to size the damage before migrating:

```sql
SELECT Region__c, COUNT(Id) recordCount
FROM Opportunity
WHERE Region__c != null
GROUP BY Region__c
ORDER BY COUNT(Id) DESC
```

The shape this returns after two quarters of free-form entry — one logical region, five stored values, and a dashboard filter on `Region__c = 'North America'` that sees only the first row (illustrative counts):

| `Region__c` | recordCount |
|---|---|
| `North America` | 812 |
| `NA` | 407 |
| `N. America` | 233 |
| `north america` | 118 |
| `NAM` | 26 |

Set `restricted` `true` on the replacement picklist so a data load cannot reintroduce a sixth spelling. The migration is a Data Loader export of `Id, Region__c`, a mapping pass, and a re-import into `Sales_Region__c` — not a field type conversion, which would take the list views with it (`references/gotchas.md` Gotcha 6).

---

## Example 2: Support Team Needs to Track Customer Contract Expiry Date

**Context:** A service team tracks customer support contracts. They need to capture the contract expiry date on the Account object so that automated flows can trigger renewal outreach 30 days before expiry.

**Problem:** The admin creates a Text field and asks users to type the date as "MM/DD/YYYY". Dates entered inconsistently ("Jan 1 2026", "2026-01-01", "1/1/26") cannot be used in date functions in flows, reports, or formula fields without complex parsing logic.

**Solution:**

Create a Date field:

1. Object Manager → Account → Fields & Relationships → New.
2. Select **Date** as the field type. (Not Date/Time — no time component is needed.)
3. Label: `Contract Expiry Date`, API Name: `Contract_Expiry_Date__c`.
4. Help Text: "Enter the date the customer's support contract expires."
5. FLS: Read + Edit for Account Manager profile and Contract Admin profile. Read for Sales Rep profile.
6. Add to the Account page layout in the "Contract Information" section.
7. Verify in a sandbox: create a test account, enter the expiry date, confirm the date formula in a flow evaluates correctly (TODAY() vs Contract_Expiry_Date__c gives a numeric day difference).

**Why it works:** Date fields store values as ISO date strings internally. All Salesforce formulas, flows, reports, and Apex DML use this consistent storage format. The UI renders dates in the user's locale automatically, so international teams see correct regional date formats with no additional configuration.

---

## Example 3: Master-Detail vs Lookup — Order Line Items

**Context:** A team is building a custom object `Order_Line_Item__c` that belongs to a parent `Order__c` custom object. They need to display the total order value on the Order record by summing all line item amounts.

**Problem:** The admin creates a Lookup Relationship from `Order_Line_Item__c` to `Order__c`. When they try to create a Roll-Up Summary field on `Order__c` to sum the line item amounts, the option is greyed out. Roll-Up Summary requires a Master-Detail relationship.

**Solution:**

Use Master-Detail Relationship:

1. On `Order_Line_Item__c`, create a **Master-Detail Relationship** to `Order__c` (not a Lookup).
2. This makes `Order__c` the master object and `Order_Line_Item__c` the detail object.
3. On `Order__c`, create a **Roll-Up Summary** field:
   - Summary Type: **SUM**
   - Summarized Field: `Amount__c` on `Order_Line_Item__c`
   - Filter criteria: none (sum all line items)
4. The total order value is now always current and maintained by the platform without any Apex or Flow.

**The Roll-Up Summary as metadata.** A `Summary` field names four things: what it sums, which relationship it walks back through, the operation, and an optional filter. `objects/Order__c/fields/Total_Order_Value__c.field-meta.xml`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Total_Order_Value__c</fullName>
    <description>Sum of Amount__c across non-cancelled Order_Line_Item__c children. Maintained by the platform; do not write to it.</description>
    <label>Total Order Value</label>
    <summarizedField>Order_Line_Item__c.Amount__c</summarizedField>
    <summaryFilterItems>
        <field>Order_Line_Item__c.Status__c</field>
        <operation>notEqual</operation>
        <value>Cancelled</value>
    </summaryFilterItems>
    <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
    <summaryOperation>Sum</summaryOperation>
    <trackFeedHistory>false</trackFeedHistory>
    <trackHistory>false</trackHistory>
    <type>Summary</type>
</CustomField>
```

- `summaryForeignKey` "represents the master-detail field on the child that defines the relationship between the parent and the child" (api_meta.txt:43648–43650) — it is the child's master-detail field, `Order_Line_Item__c.Order__c`, not the parent object.
- `summaryOperation` valid values are `Count`, `Min`, `Max`, `Sum` (api_meta.txt:43651–43666). There is no Average; compute it with a formula dividing a `Sum` by a `Count`.
- `summarizedField` "can't be null unless the `summaryOperation` value is `count`" (api_meta.txt:43640–43643) — a `Count` roll-up omits the element entirely.
- `summaryFilterItems` reuses the same `FilterItem` shape as a lookup filter (api_meta.txt:43644–43647), so `field` / `operation` / `value` behave identically to `references/metadata-examples.md` §5.

**Why it works:** Master-Detail is the only relationship type that enables Roll-Up Summary fields. The platform maintains the roll-up automatically whenever a child record is created, updated, or deleted. Using a Lookup would require a trigger or Flow to maintain the parent total, adding complexity and potential for stale data.

---

## Anti-Pattern: Creating a Text Field When a Picklist Is Needed

**What practitioners do:** They create a Text field because it feels more flexible — users can type anything. They plan to handle validation through instructions or training.

**What goes wrong:** Users enter inconsistent values. Reports show dozens of variations for the same logical value ("Enterprise", "Ent.", "enterprise", "ENT"). Dashboard filters break. Workflow criteria that compare the text value to a fixed string miss records with unexpected capitalization or spacing. The admin must build a complex validation rule to enforce the allowed values, which is exactly what a Picklist does by default.

**Correct approach:** When the field represents one of a known set of discrete values, use a Picklist. The platform enforces the allowed values by construction. If the values may expand over time, use a Global Value Set Picklist so the same values are shared and managed centrally across multiple objects.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall