Apex Reference Guide

Apex Reference Guide
Release Notes
Apex DML Operations
ApexPages Namespace
AppLauncher Namespace
Approval Namespace
Auth Namespace
Cache Namespace
Canvas Namespace
ChatterAnswers Namespace
CommercePayments Namespace
ConnectApi Namespace
Database Namespace
Datacloud Namespace
DataSource Namespace
DataWeave Namespace (Beta)
Dom Namespace
EventBus Namespace
ExternalService Namespace
Flow Namespace
Functions Namespace
Invocable Namespace
KbManagement Namespace
LxScheduler Namespace
Messaging Namespace
Metadata Namespace
Pref_center Namespace
Process Namespace
QuickAction Namespace
Reports Namespace
RichMessaging Namespace
Schema Namespace
Search Namespace
Sfc Namespace
Sfdc_Checkout Namespace
sfdc_surveys Namespace
Site Namespace
Support Namespace
System Namespace
AccessLevel Class
AccessType Enum
Address Class
Answers Class
ApexPages Class
Approval Class
Assert Class
AsyncInfo Class
AsyncOptions Class
Blob Class
Boolean Class
BusinessHours Class
Callable Interface
Cases Class
Comparable Interface
Continuation Class
Cookie Class
Crypto Class
Custom Metadata Type Methods
Custom Settings Methods
List Custom Setting Methods
Hierarchy Custom Setting Methods
Database Class
Date Class
Datetime Class
Decimal Class
Domain Class
DomainCreator Class
DomainParser Class
DomainType Enum
Double Class
EmailMessages Class
EncodingUtil Class
Enum Methods
EventBus Class
Exception Class and Built-In Exceptions
FlexQueue Class
FeatureManagement Class
Formula Class
FormulaRecalcFieldError Class
FormulaRecalcResult Class
Http Class
HttpCalloutMock Interface
HttpRequest Class
HttpResponse Class
Id Class
Ideas Class
InstallHandler Interface
Integer Class
JSON Class
JSONGenerator Class
JSONParser Class
JSONToken Enum
Label Class
Limits Class
List Class
Location Class
LoggingLevel Enum
Long Class
Map Class
Matcher Class
Math Class
Messaging Class
MultiStaticResourceCalloutMock Class
Network Class
OrgLimit Class
OrgLimits Class
PageReference Class
Packaging Class
Pattern Class
Queueable Interface
QueueableContext Interface
QuickAction Class
Quiddity Enum
RemoteObjectController
Request Class
ResetPasswordResult Class
RestContext Class
RestRequest Class
RestResponse Class
SandboxPostCopy Interface
Schedulable Interface
SchedulableContext Interface
Schema Class
Search Class
Security Class
SelectOption Class
Set Class
Site Class
SObject Class
SObjectAccessDecision Class
StaticResourceCalloutMock Class
String Class
StubProvider Interface
System Class
Test Class
Time Class
TimeZone Class
Trigger Class
TriggerOperation Enum
Type Class
UninstallHandler Interface
URL Class
UserInfo Class
UserManagement Class
Version Class
WebServiceCallout Class
WebServiceMock Interface
XmlStreamReader Class
XmlStreamWriter Class
TerritoryMgmt Namespace
TxnSecurity Namespace
UserProvisioning Namespace
VisualEditor Namespace
Wave Namespace
Appendices
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Custom Settings Methods

Custom settings are similar to custom objects and enable application developers to create custom sets of data, as well as create and associate custom data for an organization, profile, or specific user. All custom settings data is exposed in the application cache, which enables efficient access without the cost of repeated queries to the database. This data is then available for formula fields, validation rules, flows, Apex, and the SOAP API.

Usage

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

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 use 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.

Note

For more information on creating custom settings in the Salesforce user interface, see “Create Custom Settings” in the Salesforce online help.

Custom Setting Examples

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

The following example uses a custom setting called Foundation_Countries. This example demonstrates that the getValues and getInstance methods return identical values.

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.

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 when Robert calls it in his organization:
If Robert passes his user ID specified by RobertId to getInstance, the results are the same. The identical results are because the lowest level of data in the custom setting is specified at the user level.
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:
When Robert tries to return the data set for the organization using getOrgDefaults, the result is:
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:
If Robert passes his System Administrator profile ID SysAdminID to getValues, the result is:

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.
Custom Setting Countries Example
The Foundation_States custom setting is also a List type of custom setting and has the following fields:
  • Country Code
  • State Code
  • State Name
Custom Settings State Example
The Visualforce page shows two picklists: one for country and one for state.
Custom Settings Visualforce Page
The Apex controller CountryStatePicker finds the values entered into the custom settings, then returns them to the Visualforce page.

List Custom Setting Methods

The following are instance methods for list custom settings.

getAll()

Returns a map of the data sets defined for the custom setting.

Signature

public Map<String, CustomSetting__c> getAll()

Return Value

Type: Map<String, CustomSetting__c>

Usage

If no data set is defined, this method returns an empty map.

For Apex saved using Salesforce API version 20.0 or earlier, the data set names, which are the keys in the returned map, are converted to lower case. For Apex saved using Salesforce API version 21.0 and later, the case of the data set names in the returned map keys is not changed and the original case is preserved.

Note

getInstance(dataSetName)

Returns the custom setting data set record for the specified data set name. This method returns the exact same object as getValues(dataSetName).

Signature

public CustomSetting__c getInstance(String dataSetName)

Parameters

dataSetName
Type: String

Return Value

Type: CustomSetting__c

Usage

If no data is defined for the specified data set, this method returns null.

getValues(dataSetName)

Returns the custom setting data set record for the specified data set name. This method returns the exact same object as getInstance(dataSetName).

Signature

public CustomSetting__c getValues(String dataSetName)

Parameters

dataSetName
Type: String

Return Value

Type: CustomSetting__c

Usage

If no data is defined for the specified data set, this method returns null.

Hierarchy Custom Setting Methods

The following are instance methods for hierarchy custom settings.

  • In API version 41.0 and below, each method in an Apex test class, including testSetup methods, are able to insert hierarchy custom setting values. This behavior is true even when the methods have the same SetupOwnerId value as a hierarchy custom setting record inserted in a different test method.
  • In API version 42.0 and later, if a hierarchy custom setting is inserted in a testSetup method, inserting a hierarchy custom setting record with the same SetupOwnerId in a test method throws a DUPLICATE_VALUE exception.

Note

getInstance()

Returns a custom setting data set record for the current user. The fields returned in the custom setting record are merged based on the lowest level fields that are defined in the hierarchy.

Signature

public CustomSetting__c getInstance()

Return Value

Type: CustomSetting__c

Usage

If no custom setting data is defined for the user, this method returns a new custom setting object. The new custom setting object contains an ID set to null and 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 custom setting data is defined in the hierarchy, the returned custom setting has empty fields, except for the SetupOwnerId field which contains the user ID.

For Apex saved using Salesforce API version 21.0 or earlier, this method returns the custom setting data set record with fields merged from field values defined at the lowest hierarchy level, starting with the user. Also, if no custom setting data is defined in the hierarchy, this method returns null.

Note

This method is equivalent to a method call to getInstance(User_Id) for the current user.

Example

  • 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 current 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.

getInstance(userId)

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.

Signature

public CustomSetting__c getInstance(ID userId)

Parameters

userId
Type: ID

Return Value

Type: CustomSetting__c

Usage

If no custom setting data is defined for the user, this method returns a new custom setting object. The new custom setting object contains an ID set to null and 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 custom setting data is defined in the hierarchy, the returned custom setting has empty fields, except for the SetupOwnerId field which contains the user ID.

For Apex saved using Salesforce API version 21.0 or earlier, this method returns the custom setting data set record with fields merged from field values defined at the lowest hierarchy level, starting with the user. Also, if no custom setting data is defined in the hierarchy, this method returns null.

Note

getInstance(profileId)

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.

Signature

public CustomSetting__c getInstance(ID profileId)

Parameters

profileId
Type: ID

Return Value

Type: CustomSetting__c

Usage

If no custom setting data is defined for the profile, this method returns a new custom setting record. The new custom setting object contains an 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 custom setting data is defined in the hierarchy, the returned custom setting has empty fields, except for the SetupOwnerId field which contains the profile ID.

For Apex saved using SalesforceAPI version 21.0 or earlier, this method returns the custom setting data set record with fields merged from field values defined at the lowest hierarchy level, starting with the profile. Also, if no custom setting data is defined in the hierarchy, this method returns null.

Note

getOrgDefaults()

Returns the custom setting data set record for the organization.

Signature

public CustomSetting__c getOrgDefaults()

Return Value

Type: CustomSetting__c

Usage

If no custom setting data is defined for the organization, this method returns an empty custom setting object.

For Apex saved using Salesforce API version 21.0 or earlier, this method returns null if no custom setting data is defined for the organization.

Note

getValues(userId)

Returns the custom setting data set record for the specified user ID.

Signature

public CustomSetting__c getValues(ID userId)

Parameters

userId
Type: ID

Return Value

Type: CustomSetting__c

Usage

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 "alpha" at the organizational level, but has no value assigned at the user or profile level. Using getValues(UserId) returns null for this custom setting field.

getValues(profileId)

Returns the custom setting data set for the specified profile ID.

Signature

public CustomSetting__c getValues(ID profileId)

Parameters

profileId
Type: ID

Return Value

Type: CustomSetting__c

Usage

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 "alpha" at the organizational level, but has no value assigned at the user or profile level. Using getValues(ProfileId) returns null for this custom setting field.