Picklist (Including Dependent Picklist) | Metadata API Developer Guide

Version

Picklists for custom fields in custom objects are available in API version 12.0 and later. Picklists for custom or standard fields in standard objects, such as accounts, are available in API version 16.0 and later.

Declarative Metadata File Suffix and Directory Location

Picklist definitions are included in the custom object and field with which they are associated.

Fields

Picklist contains the following fields:

Field Name	Field Type	Description
controllingField	string	The fullName of the controlling field if this is a dependent picklist. A dependent picklist works in conjunction with a controlling picklist or checkbox to filter the available options. The value chosen in the controlling field affects the values available in the dependent field. This field is available in API version 14.0 and later.
picklistValues	PicklistValue[]	Required. Represents a set of values for a picklist.
restrictedPicklist	boolean	Indicates whether the picklist’s value list is restricted. With a restricted picklist, only an admin can add or change values; users can’t load or remove values through the API. By default this value is `false`. This field is available in API version 37.0 and later.
sorted	boolean	Indicates whether values should be sorted (`true`), or not (`false`). By default this value is `false`.

Java Sample

The following sample uses a picklist. For a complete sample of using a picklist with record types and profiles, see Profile.

1public void setPicklistValues() {
2  // Create a picklist
3  Picklist expenseStatus = new Picklist();
4  PicklistValue unsubmitted = new PicklistValue();
5  unsubmitted.setFullName("Unsubmitted");
6  PicklistValue submitted = new PicklistValue();
7  submitted.setFullName("Submitted");
8  PicklistValue approved = new PicklistValue();
9  approved.setFullName("Approved");
10  PicklistValue rejected = new PicklistValue();
11  rejected.setFullName("Rejected");
12  expenseStatus.setPicklistValues(new PicklistValue[]
13      {unsubmitted, submitted, approved, rejected});
14  
15  CustomField expenseStatusField = new CustomField();
16  expenseStatusField.setFullName(
17      "ExpenseReport__c.ExpenseStatus__c");
18  expenseStatusField.setLabel("Expense Report Status");
19  expenseStatusField.setType(FieldType.Picklist);
20  expenseStatusField.setPicklist(expenseStatus);
21  try {
22    AsyncResult[] ars =
23    metadataConnection.create(new Metadata[] {expenseStatusField});
24  } catch (ConnectionException ce) {
25    ce.printStackTrace();
26  }
27}

Declarative Metadata Sample Definition

The following sample shows usage for picklists, including dependent picklists, in a custom object. The isAmerican__c checkbox controls the list of manufacturers shown in the manufacturer__c picklist. The manufacturer__c checkbox in turn controls the list of models shown in the model__c picklist.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
3    <deploymentStatus>Deployed</deploymentStatus>
4    <enableActivities>true</enableActivities>
5    <fields>
6        <fullName>isAmerican__c</fullName>
7        <defaultValue>false</defaultValue>
8        <label>American Only</label>
9        <type>Checkbox</type>
10    </fields>
11    <fields>
12        <fullName>manufacturer__c</fullName>
13        <label>Manufacturer</label>
14        <picklist>
15            <controllingField>isAmerican__c</controllingField>
16            <picklistValues>
17                <fullName>Chrysler</fullName>
18                <controllingFieldValues>checked</controllingFieldValues>
19                <default>false</default>
20            </picklistValues>
21            <picklistValues>
22                <fullName>Ford</fullName>
23                <controllingFieldValues>checked</controllingFieldValues>
24                <default>false</default>
25            </picklistValues>
26            <picklistValues>
27                <fullName>Honda</fullName>
28                <controllingFieldValues>unchecked</controllingFieldValues>
29                <default>false</default>
30            </picklistValues>
31            <picklistValues>
32                <fullName>Toyota</fullName>
33                <controllingFieldValues>unchecked</controllingFieldValues>
34                <default>false</default>
35            </picklistValues>
36            <sorted>false</sorted>
37        </picklist>
38        <type>Picklist</type>
39    </fields>
40    <fields>
41        <fullName>model__c</fullName>
42        <label>Model</label>
43        <picklist>
44            <controllingField>manufacturer__c</controllingField>
45            <picklistValues>
46                <fullName>Mustang</fullName>
47                <controllingFieldValues>Ford</controllingFieldValues>
48                <default>false</default>
49            </picklistValues>
50            <picklistValues>
51                <fullName>Taurus</fullName>
52                <controllingFieldValues>Ford</controllingFieldValues>
53                <default>false</default>
54            </picklistValues>
55            <picklistValues>
56                <fullName>PT Cruiser</fullName>
57                <controllingFieldValues>Chrysler</controllingFieldValues>
58                <default>false</default>
59            </picklistValues>
60            <picklistValues>
61                <fullName>Pacifica</fullName>
62                <controllingFieldValues>Chrysler</controllingFieldValues>
63                <default>false</default>
64            </picklistValues>
65            <picklistValues>
66                <fullName>Accord</fullName>
67                <controllingFieldValues>Honda</controllingFieldValues>
68                <default>false</default>
69            </picklistValues>
70            <picklistValues>
71                <fullName>Civic</fullName>
72                <controllingFieldValues>Honda</controllingFieldValues>
73                <default>false</default>
74            </picklistValues>
75            <picklistValues>
76                <fullName>Prius</fullName>
77                <controllingFieldValues>Toyota</controllingFieldValues>
78                <default>false</default>
79            </picklistValues>
80            <picklistValues>
81                <fullName>Camry</fullName>
82                <controllingFieldValues>Toyota</controllingFieldValues>
83                <default>false</default>
84            </picklistValues>
85            <sorted>false</sorted>
86        </picklist>
87        <type>Picklist</type>
88    </fields>
89....
90</CustomObject>

The following sample shows usage for the standard Stage field in opportunities.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
3    <fields>
4        <fullName>StageName</fullName>
5        <picklist>
6            <picklistValues>
7                <fullName>Prospecting</fullName>
8                <default>false</default>
9                <forecastCategory>Pipeline</forecastCategory>
10                <probability>10</probability>
11            </picklistValues>
12            <picklistValues>
13                <fullName>Qualification</fullName>
14                <default>false</default>
15                <forecastCategory>Pipeline</forecastCategory>
16                <probability>10</probability>
17            </picklistValues>
18            <picklistValues>
19                <fullName>Needs Analysis</fullName>
20                <default>false</default>
21                <forecastCategory>Pipeline</forecastCategory>
22                <probability>20</probability>
23            </picklistValues>
24            ...
25        </picklist>
26    </fields>
27<CustomObject>