Skip to content

PranavNagrecha/AwesomeSalesforceSkills / skills/admin/field-dependency-and-controlling

field-dependency-and-controlling

Verified

Dependent picklists in Salesforce: controlling field (picklist or checkbox), dependent picklist, valueSettings matrix in metadata, API behavior via SOAP/REST, LWC lightning-combobox with dependency. NOT for creating picklist fields or Global Value Sets and replacing retired values - use admin/picklist-and-value-sets. NOT for filtering picklist values per record type or layout - use admin/record-types-and-page-layouts. Keywords: controllingField, valueSettings, controllingFieldValue, valueName, checked/unchecked checkbox controller, RecordTypePicklistValue, isDependentPicklist, getController, validFor, controllerValues.

references/well-architected.md

View on GitHub
# Well-Architected Notes — Field Dependency And Controlling

## Relevant Pillars

### Operational Excellence

The dependency matrix is metadata, and its failure mode is omission rather than error — but the direction of that failure is counter-intuitive, and it differs between the two collections in the same file. Dependency pairs are add-only: "You can add field dependency values via the Metadata API but not remove them" (api_meta.txt:45855–45858), so a deploy that drops a `valueSettings` block leaves the pair live in the org and source control lies about it. Picklist values are the opposite: "If picklist values are missing from a component definition, they get deactivated when deployed" (api_meta.txt:79237–79239). Operationally excellent teams therefore retrieve the field before editing it, deploy the whole field as one unit, treat un-mapping as a Setup task with its own ticket, and diff the enabled-pair count in the Field Dependencies grid against the pair count in source as a release check.

### User Experience

Dependent picklists exist to reduce the choice a user has to make. They fail the pillar in two directions: too little filtering (an unenforced matrix, so users pick combinations the business does not recognise) and too much (an empty dropdown with no explanation, which is what a hidden controlling field produces). Both look like a broken form to the person using it. The design goal is that a user always sees either a valid, filtered list or a clear reason there is none.

### Security

The controlling field is a security surface, not just an input. "If the controlling field is protected by field-level security (FLS), it doesn't appear in the controllerValues property" — so hiding a controlling field for a profile silently removes that profile's ability to use the dependent field. Withholding a classification, pricing tier, or internal-segment field from partner users is a legitimate security decision, but it has to be made in the same review as the dependency, or the access design and the form design contradict each other in production.

## Architectural Tradeoffs

**Dependency matrix vs. two flat picklists and a rule.** The matrix filters at the point of entry and needs no runtime logic, but it is per-field metadata that must be redeployed whenever values change. Two independent picklists plus a validation rule express the same constraint in one place and enforce it on every write path, at the cost of letting the user make the mistake before being told. Most orgs need both: the matrix for the UI, the rule for everything else.

**Depth vs. debuggability.** Each additional cascade level is another wire call, another index map, and another selection your code must clear when an ancestor changes. Two levels is cheap. Three is the point at which a custom component needs deliberate state management. Beyond that, a lookup to a reference object usually models the hierarchy better than a chain of picklists.

**Shared Global Value Set vs. per-field value sets.** A GVS keeps values consistent across objects and is capped at 1,000 total values including inactive ones. It does not carry the dependency: `controllingField` and `valueSettings` live on each field's own `ValueSet`, so two fields sharing a GVS still need two independently maintained matrices. Sharing values does not mean sharing behaviour.

## Anti-Patterns

1. **Believing a deploy can shrink the matrix.** Deleting a `valueSettings` block from source and deploying is inert — the pair stays enabled in the org, and the next retrieve puts the block back. The pattern looks like a minimal diff and changes nothing. Un-map in Setup (Field Dependencies → Edit), then re-retrieve. Always deploy the whole field, because the *values* in the same file are governed by the opposite rule.

2. **Treating `restricted` as combination enforcement.** `restricted` limits "the picklist's values ... to only the values defined by a Salesforce admin" — membership, not pairing. A load can still write a legal value against the wrong controller. Combination enforcement needs an explicit rule.

3. **Building a dependent picklist component that ignores the empty-map case.** An independent picklist and an FLS-hidden controller both yield an empty `controllerValues`, and an independent picklist's `validFor` is an empty list. A component that filters unconditionally renders nothing and reports no error, which is the hardest class of bug to get a user to describe accurately.

## Official Sources Used

- User Interface API — Build UI for Picklists — FLS hides the controlling field from `controllerValues`; a controlling field can be a picklist or a checkbox; `validFor` indexes map to `controllerValues` (verified 2026-08-14) — https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_features_records_dependent_picklist.htm
- User Interface API — Picklist Values response body — `controllerValues` is a map of the *immediate* controlling field's values to their indexes (verified 2026-08-14) — https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_picklist_values.htm
- User Interface API — Picklist Value response body — `validFor` is an Integer array, empty on independent picklists (verified 2026-08-14) — https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_picklist_value.htm
- Metadata API — Metadata Field Types — `ValueSet.controllingField`, `ValueSet.restricted`, `ValueSettings.controllingFieldValue` (string array) and `valueName` (verified 2026-08-14) — https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_field_types.htm
- Metadata API — `GlobalValueSet` — 1,000-value ceiling including inactive values; the value set is inherited by fields that use it (verified 2026-08-14) — https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_globalvalueset.htm
- Metadata API Developer Guide, Summer '26 / v62 PDF — `ValueSet` and `ValueSettings`: `controllingField` accepts "a checkbox or picklist field" (45843–45845), `restricted` as membership control (45847–45848), and "You can add field dependency values via the Metadata API but not remove them" (45855–45858, 45873–45875) — grounds Gotchas 4, 5 and 8 and metadata-examples §1, §2, §8 — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/api_meta.pdf
- Metadata API Developer Guide — `Picklist (Including Dependent Picklist)`: deprecated at v38.0 in favour of `ValueSet` (44676–44679), and the sample where a checkbox controls a picklist which in turn controls a third field, using `checked`/`unchecked` literals (44745–44852) — grounds Gotcha 7 and metadata-examples §3, §4
- Metadata API Developer Guide — `PicklistValue.controllingFieldValues`: "Checkbox: checked or unchecked. Picklist: The fullname of the picklist value in the controlling field" (79250–79258) — grounds Gotcha 7
- Metadata API Developer Guide — `CustomValue` and picklist-value deployment: "If picklist values are missing from a component definition, they get deactivated when deployed" (79237–79239, 47481–47483) and the retrieve asymmetry on unrestricted local picklists (47521–47525) — grounds Gotcha 8
- Metadata API Developer Guide — `RecordType` / `RecordTypePicklistValue` (45041–45053), the two retrieval caveats (44984–44988), and the `StandardValueSet` note that new values "don't display in the picklist UI by default" until added to the record type's Selected Fields (130774–130779) — grounds Gotcha 9 and metadata-examples §6
- Apex Developer Guide, Summer '26 / v62 PDF — Triggers and Order of Execution: "the browser runs JavaScript validation if the record contains any dependent picklist fields… No other validation occurs on the client side" (15404–15406) — grounds Gotcha 6, metadata-examples §7, and the whole UI-vs-API split in SKILL.md — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/salesforce_apex_developer_guide.pdf
- Apex Reference Guide, Summer '26 / v62 PDF — `DescribeFieldResult.isDependentPicklist()` (191169–191178) and `getController()` (190710–190720); `Schema.PicklistEntry` exposes only `getLabel`/`getValue`/`isActive`/`isDefaultValue` (193673–193685) — grounds Gotcha 10, metadata-examples §9, and examples.md Example 3
- Metadata API Developer Guide — https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_intro.htm
- Salesforce Well-Architected Overview — https://architect.salesforce.com/docs/architect/well-architected/guide/overview.html
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall