platform-value-set-generate

## Overview Generates and validates the two reusable picklist value-set metadata types — **GlobalValueSet** (a new reusable set shared across fields) and **StandardValueSet** (customizing a built-in catalog picklist like Industry or Lead Source) — and wires a CustomField to one via `<valueSetName>`. For authoritative Metadata API type, field, and enum details beyond this skill, use the `platform-metadata-api-context-get` skill. ### Scope - **In scope:** creating a GlobalValueSet, customizing a StandardValueSet, referencing either from a field, and the related deployment errors. - **Out of scope:** a one-off inline picklist on a single field with no reuse → use **`platform-custom-field-generate`** (inline `<valueSetDefinition>`). Generating the *field* that references a value set is also `platform-custom-field-generate`'s job; this skill produces the value set itself. **Two different metadata types — do not confuse them:** | Concern | GlobalValueSet | StandardValueSet | |---------|----------------|------------------| | Folder | `globalValueSets/` | `standardValueSets/` | | File suffix | `.globalValueSet-meta.xml` | `.standardValueSet-meta.xml` | | Root element | `<GlobalValueSet>` | `<StandardValueSet>` | | Name source | filename (dev name) | `<fullName>` = fixed catalog name | | Value element | `<customValue>` | `<standardValue>` | | Can add NEW values? | Yes | No — modify existing only | | Can create a new NAME? | Yes | No — only the fixed catalog | | `*` wildcard in package.xml | Supported | Not supported | --- ## Specification ### 1. Purpose This document defines the mandatory constraints for generating value-set metadata XML. The agent must verify these constraints before outputting XML to prevent Metadata API deployment errors. - **GlobalValueSet** — a reusable, named set of picklist values defined once and referenced by any number of picklist/multi-select fields. Use when the same value list is shared across multiple fields. - **StandardValueSet** — the value list behind a Salesforce-defined standard picklist (Industry, Lead Source, etc.). You can only **modify** the values in a fixed catalog of named sets; you cannot invent a new set or add brand-new values. --- ### 2. GlobalValueSet — Syntactic Essentials **File:** `globalValueSets/<DeveloperName>.globalValueSet-meta.xml` The developer name comes from the **filename**, not a `<fullName>` tag. #### Required Elements | Element | Requirement | Notes | |---------|-------------|-------| | `<masterLabel>` | Required | UI label for the value set | | `<sorted>` | Required | `true` = alphabetize values in the UI; `false` = preserve listed order | | `<customValue>` | Required (≥1) | One per value (see below) | #### `<customValue>` Sub-Elements | Sub-element | Requirement | Notes | |-------------|-------------|-------| | `<fullName>` | Required | The value's API name. Use the value text **as the user spelled it** — spaces are allowed and must be preserved (e.g. `Closed Won`, not `Closed_Won`). Must start with a letter. This is a value name, NOT a field API name, so do not append `__c` or replace spaces with underscores. | | `<default>` | Optional | At most one value `true`. Omit it (or use `false`) on the rest — it is not required on every value. | | `<label>` | Required | UI label for the value | | `<color>` | Optional | Hex color, e.g. `#FF0000` | | `<isActive>` | Optional | Omit (active) or `false` to deactivate | | `<description>` | Optional | Per-value description | #### The `__gvs` Suffix — do NOT use it in metadata **Rule: reference a GlobalValueSet by its bare developer name. Never add `__gvs`.** In API 57.0+ orgs the platform *stores/displays* a GlobalValueSet's developer name with a `__gvs` suffix internally, but the **Metadata API (deploy and retrieve) always uses the bare name** — `<valueSetName>Priority_Levels</valueSetName>`, not `Priority_Levels__gvs`. The suffix was briefly emitted by a Winter '23 change that caused deploy failures and was patched out. So: - The file is `globalValueSets/Priority_Levels.globalValueSet-meta.xml` — **no `__gvs`** in the filename. - A field references it as `<valueSetName>Priority_Levels</valueSetName>` — **no `__gvs`**. - If a retrieve shows `Priority_Levels__gvs` in the org or you see a "returned from org but not found in local project" warning, that's the expected org-storage display — keep your local metadata on the bare name. #### CORRECT — GlobalValueSet ```xml <?xml version="1.0" encoding="UTF-8"?> <GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata"> <masterLabel>Priority Levels</masterLabel> <sorted>false</sorted> <customValue> <fullName>Critical</fullName> <default>false</default> <label>Critical</label> </customValue> <customValue> <fullName>High</fullName> <default>false</default> <label>High</label> </customValue> <customValue> <fullName>Medium</fullName> <default>true</default> <label>Medium</label> </customValue> <customValue> <fullName>Low</fullName> <default>false</default> <label>Low</label> </customValue> </GlobalValueSet> ``` #### INCORRECT — GlobalValueSet ```xml <GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata"> <fullName>Priority_Levels</fullName> <!-- WRONG: name comes from the filename --> <masterLabel>Priority Levels</masterLabel> <!-- WRONG: <sorted> is required and missing --> <standardValue> <!-- WRONG: GVS uses <customValue>, not <standardValue> --> <fullName>Critical</fullName> </standardValue> </GlobalValueSet> ``` **Errors:** missing required `sorted`; unknown element `standardValue`; root `fullName` is rejected because the name is derived from the filename. --- ### 3. StandardValueSet — Syntactic Essentials CRITICAL **File:** `standardValueSets/<Name>.standardValueSet-meta.xml` #### HARD CONSTRAINTS — read before generating 1. **You can ONLY modify values inside the fixed catalog of named standard value sets.** You **cannot** add a brand-new value, and you **cannot** create a new StandardValueSet name. The Metadata API will reject both. 2. The root carries a `<fullName>` whose value is the **fixed enum name** (e.g. `Industry`), NOT a `masterLabel`. The filename must match this name. 3. Values are `<standardValue>` entries — **not** `<customValue>`. 4. **Emit ONLY the values the request explicitly names — a surgical, minimal change.** Include a `<standardValue>` block for each value the user asks you to activate, deactivate, relabel, or reorder, and **nothing else**. Do **not** enumerate the full picklist or emit `<standardValue>` entries for values the request did not mention. A StandardValueSet deployment is a partial update: unlisted values keep their current org state untouched. Reproducing every value (e.g. all 30+ Industry entries) is noise and risks clobbering org state — it is wrong even when the request says "keep *only* X active," which means "set the named ones; leave the rest as-is," not "enumerate and deactivate everything else." If you use the grounding MCP to discover existing values, use it only to confirm the named values exist and to get their exact `<fullName>`/`<label>` — not as a list to reproduce in full. #### `<standardValue>` — Modifiable Sub-Elements | Sub-element | Modifiable? | Notes | |-------------|-------------|-------| | `<fullName>` | Identifies the value (must already exist) | Cannot introduce a new one | | `<label>` | Yes | Relabel the value's UI text | | `<isActive>` | Yes | `false` deactivates; omit or `true` keeps active | | `<default>` | Yes | At most one value `true` | | `<groupingString>` | Yes | Category grouping (used by some standard picklists) | #### Canonical StandardValueSet Names (partial) `Industry`, `LeadSource`, `OpportunityStage`, `OpportunityType`, `AccountType`, `AccountRating`, `LeadStatus`, `CaseStatus`, `CaseOrigin`, `CasePriority`, `CaseReason`, `TaskStatus`, `TaskPriority`, `QuoteStatus`, `Product2Family`, `Salutation`, `AccountOwnership`, `ContractStatus`, `OrderStatus`, `PartnerRole`. > Full appendix: the complete list of valid standard value set names is at > `https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/standardvalueset_names.htm`. > If the name is not in that appendix, it is **not** a StandardValueSet — it is either a GlobalValueSet or an inline CustomField picklist. #### CORRECT — StandardValueSet (modify existing values only) ```xml <?xml version="1.0" encoding="UTF-8"?> <StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata"> <fullName>Industry</fullName> <standardValue> <fullName>Technology</fullName> <default>false</default> <label>Technology</label> <isActive>true</isActive> </standardValue> <standardValue> <fullName>Agriculture</fullName> <default>false</default> <label>Agriculture</label> <isActive>false</isActive> <!-- deactivated, but kept in the set --> </standardValue> </StandardValueSet> ``` #### INCORRECT — StandardValueSet ```xml <StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata"> <masterLabel>Industry</masterLabel> <!-- WRONG: StandardValueSet uses <fullName>, not masterLabel --> <customValue> <!-- WRONG: uses <standardValue>, not customValue --> <fullName>Renewable Energy</fullName> <!-- WRONG: cannot ADD a new value to a standard set --> <label>Renewable Energy</label> </customValue> </StandardValueSet> ``` **Errors:** unknown element `masterLabel`/`customValue`; adding a value not already in the standard catalog fails deployment. --- ### 4. Never Invent Values — Verify, Don't Hallucinate CRITICAL When customizing a **StandardValueSet** (or extending a shared GlobalValueSet), **only modify values that already exist** — never invent the value list of a standard picklist. The hard rule is about what you EMIT: a `<standardValue>` whose `<fullName>` is not a real catalog value will fail deployment. For well-known standard picklists you already know the canonical values (e.g. `Industry`, `LeadSource`, `OpportunityStage`). When you are unsure a named value exists, you can confirm it against the live org — but treat lookup as a *confirmation* step, not a required first call: - **Grounding MCP** (if available) exposes `search_metadata` and `query_metadata` to look up live metadata. Use them only to confirm a named value's exact `<fullName>`/`<label>` — not to pull the full list to reproduce. - **CLI fallback** — query the Tooling API directly: ```bash sf data query --use-tooling-api \ --query "SELECT MasterLabel, Metadata FROM StandardValueSet WHERE MasterLabel = '<name>'" ``` > **The point is the output, not the lookup:** emit modifications ONLY to values you know exist. A generated StandardValueSet that introduces unseen values is a hallucination and will fail deployment. (This pairs with the minimal-scope rule in §3: confirm the *named* values; don't enumerate the whole set.) --- ### 5. Referencing a Value Set from a CustomField A picklist/multi-select CustomField references a value set via `<valueSetName>` inside `<valueSet>` (instead of an inline `<valueSetDefinition>`). ```xml <CustomField xmlns="http://soap.sforce.com/2006/04/metadata"> <fullName>Priority__c</fullName> <label>Priority</label> <type>Picklist</type> <valueSet> <restricted>true</restricted> <valueSetName>Priority_Levels</valueSetName> <!-- bare developer name, NO __gvs; see §2 --> </valueSet> </CustomField> ``` - For a **GlobalValueSet**, `<valueSetName>` is the **bare developer name** (e.g. `Priority_Levels`) — **never** add `__gvs`. The suffix is an org-storage display artifact; the Metadata API uses the bare name for both deploy and retrieve (see §2). - A field bound to a value set must **not** also declare an inline `<valueSetDefinition>` — choose one or the other. --- ### 6. Validation Rules The agent must **reject** and explain — not silently "fix" by inventing metadata — the following: | Violation | Action / Message | |-----------|------------------| | Add a NEW value to a **StandardValueSet** | Reject. "Standard value sets cannot accept new values. Create a **GlobalValueSet** (reusable) or an inline picklist on a **CustomField** instead." | | Create a NEW StandardValueSet name | Reject. The name must be in the standard catalog appendix. Otherwise it is a GlobalValueSet. | | **Value set developer name** with spaces / invalid chars | Convert spaces to underscores; must start with a letter; alphanumeric + underscore only. `Priority Levels` → `Priority_Levels`. (This applies to the value SET name and the field API name — NOT to individual `<customValue><fullName>` values, which keep spaces as written.) | | Duplicate value `fullName` within one set | Reject. Each `fullName` must be unique within the value set. | | More than one `<default>true</default>` | Reject. At most one default value per set. | #### INCORRECT — adding a value to a standard set > "Add a `Cryptocurrency` value to the Industry picklist." Do not emit a `<standardValue>` with `fullName` `Cryptocurrency`. Respond that standard value sets are a fixed catalog and propose a GlobalValueSet (if reused across fields) or an inline restricted picklist on a single CustomField. ---