List Custom Settings

What is a Custom Setting?  We talked about Hierarchy Custom Settings in the Keep Clean Validation Rules with Custom Settings post, which let you set a default field value for the organization, then you can assign a value to a Profile or User.  List Custom Settings are a bit different, they don’t relate to Profiles or even users. So, what is a list custom setting?  When would you use it? How would you use it? Lots of questions, we are getting ahead of ourselves, let’s start with the basics.


What is a List Custom Setting?

A list custom setting is a data set, with the Custom Setting being similar to an object, and the records in that List Custom Setting hold the data.  The way Custom Settings are different than objects can be a bit frustrating at first, since Custom Settings can’t do everything a Custom Object can, but they have superpowers that will help you with your data quality, your org maintenance, and so much more.

Custom Settings vs. Custom Objects

Custom Settings work similarly to Custom Object, but they have their own quirks and are used differently.  On a metadata level, even though your List Custom Setting counts towards your Custom Object limit, your List Custom Setting is different from your Custom objects.   They are not for your end users to use when creating records, they aren’t found in the Tabs area of setup so that they can be easily accessed by Users, they are used as “settings”.   The List Custom Setting records have no owner, the data is available org-wide.  There are no sharing rules or security settings that you have with Custom Objects, everyone can see all the records.  

There are also no security settings on the fields you add to the Custom Setting, so there is no FLS (Field Level Security), all users see all fields.  In addition to field security, there are other quirks about Custom Settings that go with fields as well.  First off, you don’t have Lookup fields or Master Detail fields, because you cannot create a relationship with a List Custom Setting record, you will not have Rollup Summary fields.  If you need access to IDs with your data, you might want to consider a Custom Object, or you can create a text field to store the ID or the record if you need to reference it.

You also don’t have formula fields available with List Custom Setting records.  So you can’t make that magic happen, which is OK, as your records are a static data set for you to reference and re-use.  

Custom Object Fields Custom Setting Fields Definition
Auto Number   A system-generated sequence number that uses a display format you define. The number is automatically incremented for each new record.
Formula   A read-only field that derives its value from a formula expression you define. The formula field is updated when any of the source fields change.
Roll-Up Summary   A read-only field that displays the sum, minimum, or maximum value of a field in a related list or the record count of all records listed in a related list.
Lookup Relationship   Creates a relationship that links this object to another object. The relationship field allows users to click on a lookup icon to select a value from a popup list. The other object is the source of the values in the list.
External Lookup Relationship   Creates a relationship that links this object to an external object whose data is stored outside the Salesforce org.
Checkbox Checkbox Allows users to select a True (checked) or False (unchecked) value.
Currency Currency Allows users to enter a dollar or other currency amount and automatically formats the field as a currency amount. This can be useful if you export data to Excel or another spreadsheet.
Date Date Allows users to enter a date or pick a date from a popup calendar.
Date/Time Date/Time Allows users to enter a date and time, or pick a date from a popup calendar. When users click a date in the popup, that date and the current time are entered into the Date/Time field.
Email Email Allows users to enter an email address, which is validated to ensure proper format. If this field is specified for a contact or lead, users can choose the address when clicking Send an Email. Note that custom email addresses cannot be used for mass emails.
Geolocation   Allows users to define locations. Includes latitude and longitude components, and can be used to calculate distance.
Number Number Allows users to enter any number. Leading zeros are removed.
Percent Percent Allows users to enter a percentage number, for example, ’10’ and automatically adds the percent sign to the number.
Phone Phone Allows users to enter any phone number. Automatically formats it as a phone number.
Picklist   Allows users to select a value from a list you define.
Picklist (Multi-Select)   Allows users to select multiple values from a list you define.
Text Text Allows users to enter any combination of letters and numbers.
Text Area Text Area Allows users to enter up to 255 characters on separate lines.
Text Area (Long)   Allows users to enter up to 131,072 characters on separate lines.
Text Area (Rich)   Allows users to enter formatted text, add images and links. Up to 131,072 characters on separate lines.
Text (Encrypted)   Allows users to enter any combination of letters and numbers and store them in encrypted form.
URL   Allows users to enter any valid website address. When users click on the field, the URL will open in a separate browser window.

The data stored in List Custom Settings is awesome for development.  The data is cached, so it’s easy to access efficiently.  Also, you don’t need to use SOQL queries to reach your data, that data is there for you to get without worrying about governor limits. BOOM!  That’s awesome.  

List Custom Setting Use Cases

Picklist values on a VF page

The most common example you will hear for List Custom Settings is to have your Country and ISO-Codes, or your State & Country picklists on a Visualforce page.  How that works…

The Name of the Custom Setting record must be unique, and we will assign the Country Name as the Name of the record.  We have created the Country Code (Country_Code__c) custom field on the Custom Setting as well, this will hold the assigned Country Code. 

Using an Apex class, you can assign the Country Code based on the Country Selected.  

Change Your Code/Flow on the Fly

So, you don’t code? No problem, List Custom Settings can help you declaratively too!

Previously I did a webinar on How to Auto-Add Users to Chatter Groups, and one of the elements in the flow is a List Custom Setting.  So the flow is designed to add users to Chatter Groups based on their Profile when their User record is activated and when the Profile is changed.  There isn’t really a set way to determine which of the many chatter groups a user’s profile should be auto-added to, so the values are held in the Custom Setting. If the values were written in, we would need to update the code every time a Profile or Chatter Group is added if we want to align all the Users, so we use the Custom Setting to hold the Profile ID, Chatter Group ID, and the User’s Role in the Chatter Group.

You can see that the Profile Name and Chatter Group Name are listed too, this is for the admin’s usability, the values are not used in the Flow.

Let’s say we create a new Chatter Group for all Employees.  Only the Internal User Profiles should be included, no Customer, Partner, or Chatter Free users should be in this group.

In the flow, we have a Fast Look at the far left, this stop in the flow lookup the List Custom Setting Records where the  Profile Id (Profile_Id__c) matches the User.ProfileId of the initial User record that kicked off the process.  This is the key square!  Because of this fast lookup and the custom setting, we don’t have to update this flow in the Sandbox, test it, move it to the next sandbox, test it, wait for the release date, then deploy.

Instead, we can click “New” button, add the Group and Profile, then Save.  No deployment. No waiting for a release, instant flow change without breaking the rules!!

So, now that you know how they work, the question is how to create a Custom Setting….

Create a Custom Setting

How to create, Custom Settings are like Custom Objects, but a bit different, so it’s expected they wouldn’t be in the same place.  If you look below the Create section, you will see the Develop section, this is where the custom settings live.  Don’t worry that it says development or be turned off my it, being in the Dev section is what gives them the super powers we want to use.

  1. Access Custom Settings via the Quick Find, by typing in “Custom Settings” or at Setup – Develop – Custom Settings
  2. Click New
  3. Enter the details for your custom setting:
    1. Label: Name Displayed
    2. Object Name: This is the Developer Name, the name used to access the custom setting in code and such, without spaces.
    3. Setting Type: List or Hierarchy, this time, we select ‘List’
    4. Visibility: Public or Protected, if you are creating a managed packed and want to hide the custom setting and access from the people that install your app, selected Protected, otherwise, click Public.  99.9% of the time you will select Public, so if you are unsure, click Public.
    5. Description
    6. Save

Create Fields

You will be brought to the setting page, this is where you will add the new fields.  


  1. From the Custom Setting Record, click the New Button in the center of the page, below the Custom Setting Details.
  2. Select a field type and click Next.
  3. Enter the Name, Help Text (if necessary) and Description for the field.
  4. Verify your entry and then click Save & New if you are creating another field, otherwise just click Save.

Enter Custom Setting Data

Now that you have the Custom Setting and Custom Fields created, you can create the records.  You can mass import using the Data Loader, or you can manually enter the records from the Custom Setting.


Click the Manage button from the Custom Setting Detail


Click the Manage button from the Custom Setting List page

  1. Click Manage next to a custom setting, or from the detail page for a custom setting.
  2. You will be brought to the Setting Record List page.
  3. Click the New button
  4. Provide or change values for the custom fields you created, keeping in mind the Name must be unique.
  5. Click Save.

And now you have your list custom setting all setup!


Access Custom Settings

Custom Setting Limits



One thought on “List Custom Settings

What are your thoughts? Seriously, comment.

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s