Picklist

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.
sorted	boolean	Required. Indicates whether values should be sorted (`true`), or not (`false`).

PicklistValue

This metadata type defines a value in the picklist and specifies whether this value is the default value. It extends the Metadata metadata type and inherits its fullName field. Note the following when working with picklist values for standard objects:

When you retrieve a standard object, you all picklist values are retrieved, not just the customized picklist values.
When you deploy changes to standard picklist fields, you cannot delete existing picklist values.

Field Name	Field Type	Description
allowEmail	boolean	Indicates whether this value lets users email a quote PDF (`true`), or not (`false`). This field is only relevant for the Status field in quotes. This field is available in API version 18.0 and later.
closed	boolean	Indicates whether this value is associated with a closed status (`true`), or not (`false`). This field is only relevant for the standard Status field in cases and tasks. This field is available in API version 16.0 and later.
color	string	Indicates the color assigned to the picklist value when used in charts on reports and dashboards. The color is in hexadecimal format; for example #FF6600. If a color is not specified, it will be assigned dynamically on chart generation. This field is available in API version 17.0 and later.
controllingFieldValues	string[]	A list of values in the controlling field that are linked to this picklist value. The controlling field can be a checkbox or a picklist. This field is available in API version 14.0 and later. The values in the list depend on the field type: `Checkbox`: `checked` or `unchecked`. `Picklist`: The fullName of the picklist value in the controlling field.
converted	boolean	Indicates whether this value is associated with a converted status (`true`), or not (`false`). This field is only relevant for the standard Lead Status field in leads. Your organization can set its own guidelines for determining when a lead is qualified, but typically, you will want to convert a lead as soon as it becomes a real opportunity that you want to forecast. For more information, see “Converting Leads” in the Salesforce online help. This field is available in API version 16.0 and later.
cssExposed	boolean	Indicates whether this value is available in your Self-Service Portal (`true`), or not (`false`). This field is only relevant for the standard Case Reason field in cases. Self-Service provides an online support channel for your customers - allowing them to resolve their inquiries without contacting a customer service representative. For more information about Self-Service, see “Setting Up Self-Service” in the Salesforce online help. Note Starting with Spring ’12, the Self-Service portal isn’t available for new organizations. Existing organizations continue to have access to the Self-Service portal. This field is available in API version 16.0 and later.
default	boolean	Required. Indicates whether this value is the default picklist value in the specified picklist (`true`), or not (`false`).
description	string	Description of a custom picklist value. This field is only relevant for the standard Stage field in opportunities. It is useful to include a description for a customized picklist value so that the historical reason for creating it can be tracked. This field is available in API version 16.0 and later.
forecastCategory	ForecastCategories (enumeration of type string)	Indicates whether this value is associated with a forecast category (`true`), or not (`false`). This field is only relevant for the standard Stage field in opportunities. For more information about forecast categories, including the valid string values listed below, see “ Working with Forecast Categories ” in the Salesforce online help. Omitted Pipeline BestCase Forecast Closed This field is available in API version 16.0 and later.
fullName	string	The name used as a unique identifier for API access. The fullName can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. This field is inherited from the Metadata component.
highPriority	boolean	Indicates whether this value is a high priority item (`true`), or not (`false`). This field is only relevant for the standard Priority field in tasks. For more information about tasks, see “Creating Tasks” in the Salesforce online help. This field is available in API version 16.0 and later.
probability	int	Indicates whether this value is a probability percentage (`true`), or not (`false`). This field is only relevant for the standard Stage field in opportunities. For more information about opportunities, see “Opportunities Overview” in the Salesforce online help. This field is available in API version 16.0 and later.
reverseRole	string	A picklist value corresponding to a reverse role name for a partner. If the role is “subcontractor”, then the reverse role might be “general contractor”. Assigning a partner role to an account in Salesforce creates a reverse partner relationship so that both accounts list the other as a partner. This field is only relevant for partner roles. For more information, see “Partner Fields” in the Salesforce online help. This field is available in API version 18.0 and later.
reviewed	boolean	Indicates whether this value is associated with a reviewed status (`true`), or not (`false`). This field is only relevant for the standard Status field in solutions. For more information about opportunities, see “Creating Solutions” in the Salesforce online help. This field is available in API version 16.0 and later.
won	boolean	Indicates whether this value is associated with a closed or won status (`true`), or not (`false`). This field is only relevant for the standard Stage field in opportunities. This field is available in API version 16.0 and later.

Java Sample

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

public void setPicklistValues() {
  // Create a picklist
  Picklist expenseStatus = new Picklist();
  PicklistValue unsubmitted = new PicklistValue();
  unsubmitted.setFullName("Unsubmitted");
  PicklistValue submitted = new PicklistValue();
  submitted.setFullName("Submitted");
  PicklistValue approved = new PicklistValue();
  approved.setFullName("Approved");
  PicklistValue rejected = new PicklistValue();
  rejected.setFullName("Rejected");
  expenseStatus.setPicklistValues(new PicklistValue[]
      {unsubmitted, submitted, approved, rejected});
  
  CustomField expenseStatusField = new CustomField();
  expenseStatusField.setFullName(
      "ExpenseReport__c.ExpenseStatus__c");
  expenseStatusField.setLabel("Expense Report Status");
  expenseStatusField.setType(FieldType.Picklist);
  expenseStatusField.setPicklist(expenseStatus);
  try {
    AsyncResult[] ars =
    metadataConnection.create(new Metadata[] {expenseStatusField});
  } catch (ConnectionException ce) {
    ce.printStackTrace();
  }
}

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.

<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
    <deploymentStatus>Deployed</deploymentStatus>
    <enableActivities>true</enableActivities>
    <fields>
        <fullName>isAmerican__c</fullName>
        <defaultValue>false</defaultValue>
        <label>American Only</label>
        <type>Checkbox</type>
    </fields>
    <fields>
        <fullName>manufacturer__c</fullName>
        <label>Manufacturer</label>
        <picklist>
            <controllingField>isAmerican__c</controllingField>
            <picklistValues>
                <fullName>Chrysler</fullName>
                <controllingFieldValues>checked</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <picklistValues>
                <fullName>Ford</fullName>
                <controllingFieldValues>checked</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <picklistValues>
                <fullName>Honda</fullName>
                <controllingFieldValues>unchecked</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <picklistValues>
                <fullName>Toyota</fullName>
                <controllingFieldValues>unchecked</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <sorted>false</sorted>
        </picklist>
        <type>Picklist</type>
    </fields>
    <fields>
        <fullName>model__c</fullName>
        <label>Model</label>
        <picklist>
            <controllingField>manufacturer__c</controllingField>
            <picklistValues>
                <fullName>Mustang</fullName>
                <controllingFieldValues>Ford</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <picklistValues>
                <fullName>Taurus</fullName>
                <controllingFieldValues>Ford</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <picklistValues>
                <fullName>PT Cruiser</fullName>
                <controllingFieldValues>Chrysler</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <picklistValues>
                <fullName>Pacifica</fullName>
                <controllingFieldValues>Chrysler</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <picklistValues>
                <fullName>Accord</fullName>
                <controllingFieldValues>Honda</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <picklistValues>
                <fullName>Civic</fullName>
                <controllingFieldValues>Honda</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <picklistValues>
                <fullName>Prius</fullName>
                <controllingFieldValues>Toyota</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <picklistValues>
                <fullName>Camry</fullName>
                <controllingFieldValues>Toyota</controllingFieldValues>
                <default>false</default>
            </picklistValues>
            <sorted>false</sorted>
        </picklist>
        <type>Picklist</type>
    </fields>
....
</CustomObject>

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

<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
    <fields>
        <fullName>StageName</fullName>
        <picklist>
            <picklistValues>
                <fullName>Prospecting</fullName>
                <default>false</default>
                <forecastCategory>Pipeline</forecastCategory>
                <probability>10</probability>
            </picklistValues>
            <picklistValues>
                <fullName>Qualification</fullName>
                <default>false</default>
                <forecastCategory>Pipeline</forecastCategory>
                <probability>10</probability>
            </picklistValues>
            <picklistValues>
                <fullName>Needs Analysis</fullName>
                <default>false</default>
                <forecastCategory>Pipeline</forecastCategory>
                <probability>20</probability>
            </picklistValues>
            ...
        </picklist>
    </fields>
<CustomObject>