Custom Field Creation

Custom Field Creation

Use this skill when a practitioner needs to add a new custom field to any Salesforce object — from choosing the right field type through FLS configuration, page layout placement, and deployment to production. The skill covers all field types on both standard and custom objects.

Before Starting

Gather this context before working on field creation:

The most common wrong assumption: creating a field is enough to make it visible to users. It is not. FLS and page layout must also be configured.

Core Concepts

1. Field Type Changes Are Allowed — and That Is the Danger

Most conversions are permitted: Text → Picklist, Number → Currency, and Picklist → Multi-Select Picklist all go through. The risk is not that Salesforce refuses, it is that stored values disappear. Salesforce's rule is to convert only custom fields that hold no data. Conversions documented as data-losing: to or from Date or Date/Time; to Number, Percent, or Currency from any other type; from Checkbox to any other type; to or from Multi-Select Picklist; from Text to Picklist; from Auto Number to any other type except Text; to Auto Number from any type except Text; and from Long Text Area to any type except Email, Phone, Text, Text Area, or URL.

A smaller set is blocked outright: Formula fields convert neither in nor out, Classic Encrypted Text converts neither in nor out, and no custom field referenced in Apex or on a Visualforce page can change type at all. Text ↔ Auto Number is the safe round trip, with Auto Number capped at 30 characters. Plan the type before clicking Save anyway — see references/gotchas.md Gotcha 6 for what a lossy conversion destroys beyond the field itself.

2. Three Separate Access Layers

Salesforce has three independent layers that must all be configured for a user to see and use a custom field:

1. Field definition — the field exists on the object (created in Object Manager).
2. Field-Level Security (FLS) — controls which profiles or permission sets can see (Read) or edit (Edit) the field. Newly created fields default to hidden for all profiles in Enterprise and Unlimited editions.
3. Page layout — controls whether the field appears on the record detail/edit page in the UI. FLS and page layout are independent: a field can be on a layout but hidden by FLS (user sees nothing), or accessible via FLS but not on any layout (accessible via API and reports, but not the UI record page).

All three must be configured. Missing any one of them is why users cannot see a new field.

3. API Name Rules and Permanence

The API name is permanent after save. Rules:

• Maximum 40 characters
• Alphanumeric characters and underscores only
• Must start with a letter
• Cannot end with an underscore
• Cannot contain consecutive underscores
• Salesforce appends __c automatically

Choose a clear, unambiguous name. "Billing_Region__c" is better than "BR__c". You cannot rename an API name after creation.

4. Platform Limits

Key type-level limits:

Field Type Decision Guide

Common Patterns

Pattern 1: Build from Scratch — New Field for a Business Requirement

When to use: A stakeholder requests a new data capture point on any object.

Steps:

1. Navigate to Setup → Object Manager → [Object] → Fields & Relationships → New.
2. Select field type using the decision guide above. Click Next.
3. Enter Field Label (user-facing name). Salesforce auto-populates Field Name (API name) — review it. Add Description (internal notes for admins) and Help Text (shown to end users).
4. Configure type-specific options: Length (Text), Decimal Places (Number/Currency), Visible Lines (Long Text Area), picklist values.
5. On "Establish Field-Level Security": set Read and/or Edit per profile. Include every profile whose users need access.
6. On "Add to Page Layouts": select every layout where the field must appear.
7. Click Save.
8. Verify: use View as a target user or log in as a test user. Confirm the field is visible and editable.

Pattern 2: Review / Troubleshoot — Field Not Visible to Users

When to use: A user reports they cannot see a field that was recently created.

Diagnosis steps:

1. Setup → Object Manager → [Object] → Fields & Relationships → [Field] → Set Field-Level Security. Confirm the user's profile (or relevant permission set) has at least Read access checked.
2. Setup → Object Manager → [Object] → Page Layouts → [Applicable layout]. Confirm the field appears on the layout canvas (not just in the palette on the left, which means it is NOT on the layout).
3. If the org uses Lightning Record Pages with Dynamic Forms: Setup → App Builder → [Record page for this object] → check the Dynamic Form component. In Dynamic Forms, fields must be added to the form component individually — the page layout is not used for those fields.
4. Check the user's active record type and which layout is assigned to that record type for that profile.

Pattern 3: Lookup vs. Master-Detail — Choosing the Right Relationship Type

Lookup Relationship — use when:

• The parent record is optional (child can exist without a parent)
• Deleting the parent should NOT delete child records
• Child records have their own ownership and sharing rules
• Roll-up summaries are not needed

Master-Detail Relationship — use when:

• Every child record must have a parent (field is always required)
• Deleting the parent should cascade-delete all children
• Roll-Up Summary fields are needed on the parent
• Child records should inherit the parent's sharing model

A Lookup can be converted to Master-Detail later only if no child records have a blank parent. Master-Detail cannot be converted to Lookup if the object has Roll-Up Summary fields using that relationship.

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Before marking field creation complete:

• Field type chosen intentionally — most conversions are allowed later, but the data-losing ones destroy stored values, and where data is lost every list view built on the field is deleted.
• API name reviewed: clear, unique, under 40 characters, no trailing underscores.
• Description and Help Text filled in — helps future admins and end users.
• FLS configured for all profiles or permission sets that need Read and/or Edit access.
• Field added to all relevant page layouts for the target user group.
• If Dynamic Forms are in use on any Lightning record page, field added to the Dynamic Form component.
• Required setting validated: if required, existing records and integrations can provide the value.
• Tested as a target user (View as user or dedicated test user in sandbox).
• Deployment artifact prepared: field + page layout(s) included in change set or SFDX retrieve manifest.
• Production deployment validated: field visible and editable for users in production.

Salesforce-Specific Gotchas

1. New fields are hidden for all profiles in Enterprise/Unlimited editions — When you create a field in Enterprise or Unlimited, the default FLS is hidden (no access) for all profiles. If you click through the FLS screen without setting visibility, no user (other than System Administrators in some editions) can see the field. The field exists and stores data written via API, but the UI and reports show it as blank or invisible.

2. Required fields break existing records and integrations — Marking a field Required at the field definition level causes the Salesforce API to reject any DML (from UI, triggers, or integrations) that does not supply the field. If you convert an optional field to required after records already exist without values, bulk operations and integrations that do not explicitly set the field will start producing errors. Provide a default value or run a data update before making an existing field required.

3. Dynamic Forms bypass classic page layouts for field display — If a Lightning record page uses the Dynamic Forms feature in Lightning App Builder, fields on the classic page layout are NOT automatically shown. Dynamic Forms replaces the classic layout's field section with a custom field component. Adding a field to the classic page layout has no effect for users seeing the Dynamic Forms version of the page. The field must be added directly to the Dynamic Form component in App Builder.

Output Artifacts

Related Skills

• formula-fields — use when the field value should be computed from other fields (read-only, not stored)
• picklist-and-value-sets — use when managing picklist values, global value sets, or controlling/dependent picklists after field creation
• object-creation-and-design — use when deciding whether to create a new custom object vs. adding fields to an existing one
• permission-set-architecture — use when designing the FLS and access model across many users, profiles, and permission sets