Custom Settings Methods

Custom settings methods are all instance methods, that is, they are called by and operate on a particular instance of a custom setting. There are two types of custom settings: hierarchy and list. The methods are divided into those that work with list custom settings, and those that work with hierarchy custom settings.

The following are the instance methods for list custom settings.

Table 1. List Custom Settings Methods
Name	Arguments	Return Type	Description
`getAll`		Map<String `Data_set_name`, CustomSetting__c>	Returns a map of the data sets defined for the custom setting. If no data set is defined, this method returns an empty map.
`getInstance`	String `dataset_name`	CustomSetting__c	Returns the custom setting data set record for the specified `dataset_name`. This method returns the exact same object as `getValues(dataset_name)`. If no data is defined for the specified data set, this method returns `null`.
`getValues`	String `dataset_name`	CustomSetting__c	Returns the custom setting data set record for the specified `dataset_name`. This method returns the exact same object as `getInstance(dataset_name)`. If no data is defined for the specified data set, this method returns `null`.

The following are the instance methods for hierarchy custom settings:

Table 2. Hierarchy Custom Settings Methods
Name	Arguments	Return Type	Description
`getInstance`		CustomSetting__c	Returns a custom setting data set record for the running user. The fields returned in the custom setting record are merged based on the lowest level fields that are defined in the hierarchy. If no custom setting data is defined for the user, this method returns a new custom setting record with the ID set to a `null` and with merged fields from higher in the hierarchy. You can add this new custom setting record for the user by using `insert` or `upsert`. If no data is defined for this custom setting, this method returns `null`. Note For Apex saved using SalesforceAPI version 21.0 or earlier, this method returns the lowest level custom setting data that is defined—the profile custom setting, or if the latter is not defined, the organization custom setting. Examples: Custom setting data set defined for the user: If you have a custom setting data set defined for the user “Uriel Jones,” for the profile “System Administrator,” and for the organization as a whole, and the user running the code is Uriel Jones, this method returns the custom setting record defined for Uriel Jones. Merged fields: If you have a custom setting data set with fields A and B for the user “Uriel Jones” and for the profile “System Administrator,” and field A is defined for Uriel Jones, field B is `null` but is defined for the System Adminitrator profile, this method returns the custom setting record for Uriel Jones with field A for Uriel Jones and field B from the System Administrator profile. No custom setting data set record defined for the user: If the running user is “Barbara Mahonie,” who also shares the “System Administrator” profile, but no data is defined for Barbara as a user, this method returns a new custom setting record with the ID set to `null` and with fields merged based on the fields defined in the lowest level in the hierarchy. This method is equivalent to a method call to `getInstance(User_Id)` for the running user.
`getInstance`	ID `User_Id`	CustomSetting__c	Returns the custom setting data set record for the specified `User_Id`. The lowest level custom setting record and fields are returned. Use this when you want to explicitly retrieve data for the custom setting at the user level. If no custom setting data is defined for the user, this method returns a new custom setting record with the ID set to a `null` and with merged fields from higher in the hierarchy. You can add this new custom setting record for the user by using `insert` or `upsert`. If no data is defined for this custom setting, this method returns `null`. Note For Apex saved using SalesforceAPI version 21.0 or earlier, this method returns the lowest level custom setting data that is defined—the profile custom setting, or if the latter is not defined, the organization custom setting.
`getInstance`	ID `Profile_Id`	CustomSetting__c	Returns the custom setting data set record for the specified `Profile_Id`. The lowest level custom setting record and fields are returned. Use this when you want to explicitly retrieve data for the custom setting at the profile level. If no custom setting data is defined for the profile, this method returns a new custom setting record with the ID set to `null` and with merged fields from your organization's default values. You can add this new custom setting for the profile by using `insert` or `upsert`. If no data is defined for this custom setting, this method returns `null`.
`getOrgDefaults`		CustomSetting__c	Returns the custom setting data set record for the organization. If no data is defined for this custom setting, this method returns `null`.
`getValues`	ID `User_Id`	CustomSetting__c	Returns the custom setting data set record for the specified `User_Id`. Use this if you only want the subset of custom setting data that has been defined at the user level. For example, suppose you have a custom setting field that has been assigned a value of "foo" at the organizational level, but has no value assigned at the user or profile level. Using `getValues(User_Id)` returns `null` for this custom setting field.
`getValues`	ID `Profile_Id`	CustomSetting__c	Returns the custom setting data set for the specified `Profile_Id`. Use this if you only want the subset of custom setting data that has been defined at the profile level. For example, suppose you have a custom setting field that has been assigned a value of "foo" at the organizational level, but has no value assigned at the user or profile level. Using `getValues(Profile_Id)` returns `null` for this custom setting field.

For more information on custom settings, see “Custom Settings Overview” in the Salesforce online help.

Note

All custom settings data is exposed in the application cache, which enables efficient access without the cost of repeated queries to the database. However, querying custom settings data using Standard Object Query Language (SOQL) doesn't make use of the application cache and is similar to querying a custom object. To benefit from caching, use other methods for accessing custom settings data such as the Apex Custom Settings methods.

Custom Setting Examples

The following example uses a list custom setting called Games. Games has a field called GameType. This example determines if the value of the first data set is equal to the string PC.

List<Games__C> mcs = Games__c.getall().values();
boolean textField = null;
if (mcs[0].GameType__c == 'PC') {
  textField = true;
}
system.assertEquals(textField, true);

The following example uses a custom setting from Country and State Code Custom Settings Example. This example demonstrates that the getValues and getInstance methods list custom setting return identical values.

Foundation_Countries__c myCS1 = Foundation_Countries__c.getValues('United States');
String myCCVal = myCS1.Country_code__c;
Foundation_Countries__c myCS2 = Foundation_Countries__c.getInstance('United States');
String myCCInst = myCS2.Country_code__c;
system.assertEquals(myCCinst, myCCVal);

Hierarchy Custom Setting Examples

In the following example, the hierarchy custom setting GamesSupport has a field called Corporate_number. The code returns the value for the profile specified with pid.

GamesSupport__c mhc = GamesSupport__c.getInstance(pid);
string mPhone = mhc.Corporate_number__c;

The example is identical if you choose to use the getValues method.

The following example shows how to use hierarchy custom settings methods. For getInstance, the example shows how field values that aren't set for a specific user or profile are returned from fields defined at the next lowest level in the hierarchy. The example also shows how to use getOrgDefaults.

Finally, the example demonstrates how getValues returns fields in the custom setting record only for the specific user or profile, and doesn't merge values from other levels of the hierarchy. Instead, getValues returns null for any fields that aren't set. This example uses a hierarchy custom setting called Hierarchy. Hierarchy has two fields: OverrideMe and DontOverrideMe. In addition, a user named Robert has a System Administrator profile. The organization, profile, and user settings for this example are as follows:

Organization settings: OverrideMe: Hello; DontOverrideMe: World
Profile settings: OverrideMe: Goodbye; DontOverrideMe is not set.
User settings: OverrideMe: Fluffy; DontOverrideMe is not set.

The following example demonstrates the result of the getInstance method if Robert calls it in his organization:

Hierarchy__c CS = Hierarchy__c.getInstance();
System.Assert(CS.OverrideMe__c == 'Fluffy');
System.assert(CS.DontOverrideMe__c == 'World');

If Robert passes his user ID specified by RobertId to getInstance, the results are the same. This is because the lowest level of data in the custom setting is specified at the user level.

Hierarchy__c CS = Hierarchy__c.getInstance(RobertId);
System.Assert(CS.OverrideMe__c == 'Fluffy');
System.assert(CS.DontOverrideMe__c == 'World');

If Robert passes the System Administrator profile ID specified by SysAdminID to getInstance, the result is different. The data specified for the profile is returned:

Hierarchy__c CS = Hierarchy__c.getInstance(SysAdminID);
System.Assert(CS.OverrideMe__c == 'Goodbye');
System.assert(CS.DontOverrideMe__c == 'World');

When Robert tries to return the data set for the organization using getOrgDefaults, the result is:

Hierarchy__c CS = Hierarchy__c.getOrgDefaults();
System.Assert(CS.OverrideMe__c == 'Hello');
System.assert(CS.DontOverrideMe__c == 'World');

By using the getValues method, Robert can get the hierarchy custom setting values specific to his user and profile settings. For example, if Robert passes his user ID RobertId to getValues, the result is:

Hierarchy__c CS = Hierarchy__c.getValues(RobertId);
System.Assert(CS.OverrideMe__c == 'Fluffy');
// Note how this value is null, because you are returning 
    
// data specific for the user 
    
System.assert(CS.DontOverrideMe__c == null);

If Robert passes his System Administrator profile ID SysAdminID to getValues, the result is:

Hierarchy__c CS = Hierarchy__c.getValues(SysAdminID);
System.Assert(CS.OverrideMe__c == 'Goodbye');
// Note how this value is null, because you are returning 
    
// data specific for the profile 
    
System.assert(CS.DontOverrideMe__c == null);

Country and State Code Custom Settings Example

This example illustrates using two custom setting objects for storing related information, and a Visualforce page to display the data in a set of related picklists.

In the following example, country and state codes are stored in two different custom settings: Foundation_Countries and Foundation_States.

The Foundation_Countries custom setting is a list type custom setting, and has a single field, Country_Code.

The Foundation_States custom setting is also a List type of custom setting and has the following fields:

Country Code
State Code
State Name

The Visualforce page shows two picklists: one for country, and one for state.

<apex:page controller="CountryStatePicker">
   <apex:form >
      <apex:actionFunction name="rerenderStates" rerender="statesSelectList" >
          <apex:param name="firstParam" assignTo="{!country}" value="" />
      </apex:actionFunction>

   <table><tbody>
      <tr>
        <th>Country</th>
          <td>
             <apex:selectList id="country" styleclass="std" size="1" value="{!country}" onChange="rerenderStates(this.value)">
                    <apex:selectOptions value="{!countriesSelectList}"/>
             </apex:selectList>
          </td>
      </tr>
      <tr id="state_input">
        <th>State/Province</th>
          <td>
            <apex:selectList id="statesSelectList" styleclass="std" size="1" value="{!state}">
                   <apex:selectOptions value="{!statesSelectList}"/>
            </apex:selectList>
          </td>
      </tr>
   </tbody></table>
   </apex:form>
</apex:page>

The Apex controller CountryStatePicker finds the values entered into the custom settings, then returns them to the Visualforce page.

public with sharing class CountryStatePicker {

// Variables to store country and state selected by user 
    
    public String state { get; set; }
    public String country {get; set;}   

    // Generates country dropdown from country settings 
    
    public List<SelectOption> getCountriesSelectList() {
        List<SelectOption> options = new List<SelectOption>();
        options.add(new SelectOption('', '-- Select One --'));        

        // Find all the countries in the custom setting 
    
        Map<String, Foundation_Countries__c> countries = Foundation_Countries__c.getAll();
        
        // Sort them by name 
    
        List<String> countryNames = new List<String>();
        countryNames.addAll(countries.keySet());
        countryNames.sort();
        
        // Create the Select Options. 
    
        for (String countryName : countryNames) {
            Foundation_Countries__c country = countries.get(countryName);
            options.add(new SelectOption(country.country_code__c, country.Name));
        }
        return options;
    }
    
    // To generate the states picklist based on the country selected by user. 
    
    public List<SelectOption> getStatesSelectList() {
        List<SelectOption> options = new List<SelectOption>();
        // Find all the states we have in custom settings. 
    
        Map<String, Foundation_States__c> allstates = Foundation_States__c.getAll();

        // Filter states that belong to the selected country 
    
        Map<String, Foundation_States__c> states = new Map<String, Foundation_States__c>();
        for(Foundation_States__c state : allstates.values()) {
            if (state.country_code__c == this.country) {
                states.put(state.name, state);
            }
        }
        
        // Sort the states based on their names 
    
        List<String> stateNames = new List<String>();
        stateNames.addAll(states.keySet());
        stateNames.sort();
        
        // Generate the Select Options based on the final sorted list 
    
        for (String stateName : stateNames) {
            Foundation_States__c state = states.get(stateName);
            options.add(new SelectOption(state.state_code__c, state.state_name__c));
        }
        
        // If no states are found, just say not required in the dropdown. 
    
        if (options.size() > 0) {
            options.add(0, new SelectOption('', '-- Select One --'));
        } else {
            options.add(new SelectOption('', 'Not Required'));
        }
        return options;
    }
}