Using Hierarchy Custom Settings in

Last 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 settings: Hierarchy.

In Winter '10, introduced Custom Settings which allow 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. Using custom settings is much easier than rolling your own solution as they are much faster and easier to access (cached at the application level and accessible via their own interface) and do not count against SOQL limits.

Hierarchy settings allow you to personalize your application for different profiles and/or users. The interface has baked-in logic that drills down into the org, profile, and user level (based upon the current user) and returns the most specific or lowest value in the hierarchy. I've found hierarchy custom settings to be extremely useful for those "one off" occasions. Let's suppose you want to authorize your sales teams to be able to offer a specific discount to customers. You might set up an org-wide custom setting of a 1% discount that everyone is authorized to offer. Now of course you have a set of high-producing sales people that are in their own profile and are able to offer a 5% discount. However (and here is the "one off"), there is that one sales person in that same profile that has lobbied the VP of Sales to be able to offer a 15% discount. With hierarchy custom settings you can accommodate all of these scenarios!!

As with list custom settings, when you create a new hierarchy custom setting, 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 youve set up your custom settings and added your fields, you can select the Manage link on the custom settings page to add add/edit/delete values for the entire org, a specific profile or individual users. The image below shows the 1% discount for the entire org and then specific settings for the Standard Employees profile and a specific user.

Selecting the View link for the profile displays the settings that apply to users that are part of the "Standard Employees" profile.

Selecting the View link for the "one off" user, displays the settings that are applicable for that user only.

Accessing Custom Settings Programmatically

The cool thing is now you can programmatically access these custom settings based upon the running user and return their most appropriate value (org-wide, profile or user) in formula fields, validation rules, Apex and the Web Services API with the following interface. Be sure to check out the custom settings docs for more detailed usage.

You can only access hierarchy custom settings in formula field and validation rules. Here is the generic syntax:


For Apex code there are a number of good examples in the docs so make sure you take a look at them.