Using List Custom Settings in Salesforce.com

January 7th, 2010

Salesforce.com recently introduced Custom Settings in Winter ’10 which allows you to store custom data sets and associate them on an org-wide, profile or user basis. Custom Settings are essentially custom objects that are exposed in the applications cache and are accessible via their own API.

You can certainly build your own custom objects to store settings but using custom settings is much quicker (again they are stored in the application cache) and do not count against SOQL limits when fetched. You can also use custom settings in formula fields, validation rules, Apex code and the Web Services API.

Custom settings come in two flavors: list and hierarchy. This post will focus on list custom settings which is the simpler of the two to grok. List custom settings allow you to store org-wide static data that is frequently used. For instance, Salesforce.com does not have ISO country codes baked into the platform. At my last company we maintained this list of countries and their ISO codes in a separate custom object. Whenever we needed the data we’d have to query this custom object which brought with it additional overhead pertaining to the SOQL limits. Using a list custom setting you can now store these codes and use them virtually anywhere needed.

When you create a new custom settings the platform creates a custom object in the background for you (notice the API Name field). You then add additional fields to the custom setting in the same manner that you do for custom objects (you are limited to checkbox, currency, date, date/time, email, number, percent, phone, text, text area and URL fields). I found the management interface for custom settings a little confusing at first and got lost a number of times trying to add fields and/or data.



After you’ve setup your custom settings and added your fields, you can select the Manage link on the Custom Settings page to add add/edit/delete values. It’s very similar to maintaining other records in Salesforce.com.



Once you’ve finished adding fields and values to your custom settings, you can query it like any other custom object (if you like).



Custom settings have their own instance methods to allow easy access. It looks like the getInstance() and getValues() method returns the same object. I typically use the getInstance() method as it makes more sense to me. You access a record by using the value in the Name column (you cannot use the ID or other columns):

ISO_Country__c code = ISO_Country__c.getInstance(‘AFGHANISTAN’);

To return a map of data sets defined for the custom object (all records in the custom object), you would use:

Map mapCodes = ISO_Country__c.getAll();
// display the ISO code for Afghanistan
System.debug(‘ISO Code: ‘+mapCodes.get(‘AFGHANISTAN’).ISO_Code__c);

Alternatively you can return the map as a list:

List listCodes = ISO_Country__c.getAll().values();



I put together a quick demo on how to use the ISO Countries custom setting in a Visualforce page for a picklist. You can run this example on my Developer Site.


Apex Controller – CustomSettingsListController

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public with sharing class CustomSettingsListController {
 
	public String selectedIso {get;set;}
 
	public List<selectOption> isoCodes {
		get {
			List<selectOption> options = new List<selectOption>();
 
			for (ISO_Country__c iso : ISO_Country__c.getAll().values())
				options.add(new SelectOption(iso.ISO_Code__c,iso.Name+' - '+iso.ISO_Code__c));
			return options;
 
		}
		set;
	}
 
}

Visualforce Page – CustomSettingsList

1
2
3
4
5
6
7
8
9
10
11
12
13
<apex:page controller="CustomSettingsListController">
	<apex:sectionHeader title="Custom Settings" subtitle="List Demo"/>
 
	<apex:form >
		<apex:pageBlock >
 
	        <apex:selectList value="{!selectedIso}" size="1">
	            <apex:selectOptions value="{!isoCodes}"/>
	        </apex:selectList>
 
		</apex:pageBlock>
	</apex:form>
</apex:page>

Note: If you include custom settings in your distributed package you’ll need to build in some scripts which populate the settings with data after the package has been installed.


VN:F [1.9.22_1171]
Rating: 9.1/10 (12 votes cast)
VN:F [1.9.22_1171]
Rating: +6 (from 6 votes)
Using List Custom Settings in Salesforce.com, 9.1 out of 10 based on 12 ratings

Categories: Apex, Code Sample, Salesforce, Visualforce

Leave a comment

Comments Feed31 Comments

  1. Jeff Grosse

    Great post Jeff, and it’s a nice example. It’s now filed for future reference for me. Thanks for taking the time to write it.

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  2. Scott Hemmeter

    Great post. I am sold on custom settings and am using them a lot. A couple considerations.

    As an ISV, I can use them and set them to Protected so my customer doesn’t even know they exist.

    There is a 10mb limit per namespace. Custom Settings should be used more for things like preferences and lookup tables like ISO codes. They probably should not be used as a solution for logging data that is being continually inserted where you can hit the 10mb limit. A record is always measured at 2k, so it’s only a matter of time before you hit the limits.

    Good news. Salesforce can increase the 10mb limit for you. As an ISV, they can increase it in your DE org and that setting travels with the app’s namespace on install. The principle is still the same. You can just delay the limit being reached.

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  3. jeffdonthemic

    Great comments!! Thanks.

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  4. Scott Hemmeter

    A bit more…

    Custom Settings are case sensitive. Beware that you could have “ABC”, “abc” and “Abc” as 3 different custom settings and the getInstance method cases about the case sensitivity.

    As of this time Custom Settings are “setup” objects. This means you can get weird errors depending upon your updating of Custom Settings and real data. I think this will be changing, though.

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  5. Rich Unger

    Great post, Jeff. I’m one of the engineers who worked on this feature, so I thought I’d chime in on a few things.

    getInstance and getValues return the same thing for list custom settings. Where they differ is on hierarchy custom settings. getValues(myUserId) will return only those values that are overridden for the user, whereas getInstance(myUserId) will return the merged result of the 3 rows (org, profile, user). The utility of getValues() is mainly for writing configuration pages for your settings (so you can edit org defaults, etc).

    Scott:
    Custom Settings are not be case sensitive. When I attempt to create ABC after creating abc, I get an error. If you are somehow able to create multiple custom settings with the same name, please file a support ticket.

    You are correct about Custom Settings being setup objects. This will be changing in the next release.

    As a temporary workaround until then, you can put your custom settings modifications in a @Future method, which will separate them enough from your other DML that you won’t get the MIXED_DML error. Unfortunately, your tests will still fail, since in tests @Future methods are inlined.

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  6. Scott Hemmeter

    Rich, I guess my DE org has a bug that allows duplicate custom setting records.

    While they may not be case sensitive, if you have a setting named ‘Hello’, running .getInstance(‘hello’) will not find it. The get instance method is not smart enough to look for custom setting records of any case.

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  7. Dave Weinreich

    Alas, I am an Admin, not a developer. I created my Custom Setting with the intent of using it in a Custom Email Template. I could not find my new Custom Setting. Can I do what I am trying to do?

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  8. jeffdonthemic

    They are under Setup -> App Setup -> Develop -> Custom Settings. Let me know if you don’t see them.

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  9. Eric Kintzer

    Jeff – This was terrific and fit my application use case perfectly. I understand how to use in APEX but SFDC claims that Custom Settings can be used in Formula fields!?

    I created a List Custom Setting similar to yours and can find no reference to it all in a Formula builder. The Custom Setting is definitely present as I can query it with SOQL.

    What am I missing here? Can I create a Billing_Country_ISO_Code field on the Account and use the Custom Setting to populate it from Account.BillingCountry using a Formula? This would save me writing, testing and deploying the APEX.

    Thanks

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  10. jeffdonthemic

    I found that confusing also. I couldn’t locate the the list custom settings in the formula builder either. However, I could locate hierarchy custom settings. Reading the docs it states, “Formula fields only work for hierarchy custom settings; they cannot be used for list custom settings.”

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  11. Using Hierarchy Custom Settings in Salesforce.com | Jeff Douglas – Technology, Coding and Bears… OH MY!

    [...] month I posted on the new List Custom Settings feature released in Winter ‘10. I’ll finally round out the topic with the other flavor of custom [...]

  12. Wes

    I’m using list custom settings in a few of my projects.. previously I used a static utility class to manage such settings and I’m still debating which method I prefer. Does anyone have any insight that might tip the scales?

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  13. David Schach

    The 10MB limit, assuming 2kb per entry, gives us 5000 list entries. Sounds like a lot. How’s my math?

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: +1 (from 1 vote)
  14. Jason

    Heads up that the name of a value should never be more that 38 characters as you could run into this issue.

    http://community.salesforce.com/sforce/board/message?board.id=apex&message.id=25521&query.id=424014#M25521

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  15. Jeff Douglas

    Nice to know, Jason. Thanks!

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  16. Dave

    Excellent,

    Is there any way to get a fields value dynamically, as well as the row.

    So instead of
    mapCodes.get(‘AFGHANISTAN’).ISO_Code__c

    I can say:
    ISO_Country__c code = ISO_Country__c.getInstance(‘AFGHANISTAN’);
    string myCode = code.get(‘ISO_Code__c’);

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  17. Dave

    I just noticed the sObject api has a GET method.

    This solved my issue calling code.get(string) returns the Object that I want.

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  18. Niels

    We have a managed package with embedded Flex objects that we use for aircraft and crew scheduling. The objects need to read a custom setting (list type) to determine what event types are allowed to overlap in the calendar.

    The Flex objects access the DB via the Apex API. This works great for admins but not for other profiles, where we get a query failure.

    SF support tells us the only way we can do this is for the User accessing the object to have “Customize Application” permission (not good…!), but we only want Read access, not Read/Write or Manage. When we set that permission then our app works fine, but of course we cannot let all Users have this permission enabled.

    Is there a way around this? Do we have to use heirarchy type instead of list type?

    Many thanks in advance for any help.

    Niels
    Perfect Aviation

    PS: Here is our select for the custom setting:
    var sql: String = “SELECT Id, ” +
    “Name, ” +
    “bas__Is_In_Duty__c, ” +
    “bas__Overlap_Level__c, ” +
    “bas__AS_Create_Edit__c, ” +
    “bas__CS_Create_Edit__c, ” +
    “bas__SC_Create_Edit__c, ” +
    “bas__CC_Create_Edit__c, ” +
    “bas__TC_Create_Edit__c ” +
    “FROM bas__Activity_Mgt__c”;
    this.query(ACTIVITY_MGT, sql, success, failed);

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  19. Jeff Douglas

    So are users of the Flex application creating, editing or deleting these custom settings?

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  20. Niels

    The Flex object is only reading the custom settings and copying the resulting dataset into other parts of its code as parameters.

    No creating, editing or deleting of custom settings is performed, only the select statement in my previous post.

    I found this thread – maybe I am not the only one with this error:

    http://community.salesforce.com/t5/General-Development/Custom-settings-return-Error-for-non-sys-admins/m-p/173879

    Many thanks for your help.
    Niels

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  21. Andres Perez

    Since the data is being stored in a cache and not in a database, does the cache ever get refreshed?

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  22. Jeff Douglas

    My guess is that they get cached each time the JVM recycles plus when ever you make a change. I just changed a value and the change was reflected with the correct value immediately.

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  23. Jeff Douglas

    It looks a little buggy. Perhaps your best bet in the short-term is to use a custom object to store these settings and then move them to actual custom settings once fixed. It should be a fairly academic process. You can use Eclipse to move the field from the custom object settings to the list settings object (they are both essentially custom objects) when fixed. You can then search and replace on the Flex code to change where the setting come from.

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  24. Niels

    Hi Jeff,

    Clear, thanks. I have escalated this as a bug.

    We deploy a managed package in very few but large installs and have a dozen different custom settings so creating a new custom object in lieu of each of them is not a great solution for us as it would leave all those old objects hanging.

    We also like the other benefits of custom settings such as not counting against query limits and being available in formulas without having a lookup relationship consumed.

    We are part of the deprecation pilot but even that leaves deprecated fields and objects in installations, only new installs are without them.

    I don’t know if you have someone influential you could talk to this about, but a fix would be most welcome :)

    Thanks for your input and help.

    Niels

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  25. MetratoN

    Hi my friend, good work for this web site..i found interesting you not in the final post. i need add data automatic in my package so that the moment of instalation, the custom setting component holds values by default…

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: -2 (from 2 votes)
  26. Neeru

    Hi Jeff,

    Am facing some problem in this custom settings, actually am not much aware of this. and trying to implement this in my salesforce account.

    i have created a page on which picklist of custom setting is visible with one standard field of object. But i want to save the value of picklist with my standard field record. and don’t know hoe to do that.

    Will you please help me this problem?

    Thanks

    VA:F [1.9.22_1171]
    Rating: 5.0/5 (1 vote cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  27. Jeff Douglas

    @Neeru, I think you’ll have to use a custom controller or extension and then overwrite the value in the standard field with the chosen value from your custom picklist before you save the record. HTH

    VN:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VN:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  28. Nandini

    I have been reading your blog and its of great help to us,

    your doing a excellent job,

    Many Thanks,
    Nandini

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  29. Ceyhun

    Hi,
    So here we only retrieve the values of the fields, is there any way to create an custom setting object with apex code, or create some fields of custom setting object and insert some values to it through apex code?

    Thanks
    Ceyhun

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  30. Klaus

    Hi Jeff,
    in the final note of your article you mentioned a script to populate custom settings in a managed package. What would be the best practice for this purpose?
    Thanks
    Klaus

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  31. Ravi alok

    Hi Jeff,

    Very nice post.Superb job!

    Thanks,
    Ravi Alok

    VA:F [1.9.22_1171]
    Rating: 0.0/5 (0 votes cast)
    VA:F [1.9.22_1171]
    Rating: -1 (from 1 vote)

Leave a comment

Feed

http://blog.jeffdouglas.com / Using List Custom Settings in Salesforce.com