Salesforce B2C Commerce Cloud uses custom preferences to store configurable settings for a storefront. These settings can be anything from feature settings to loyalty calculations.
Custom preferences can be created at two levels:
- global (organisation)
- site
As a Salesforce B2C Commerce Cloud developer, you must understand the differences between Global Preferences and Site Preferences and use each appropriately.
Global Custom Preferences
Global Preferences are organisation-level preferences that any site within the environment can access. These preferences are ideal for settings that are common across all sites.
For example, if all sites in an organisation use the same preference value, using a global value is your best bet. This can help reduce code duplication and make maintaining and updating settings across multiple sites more accessible.
Global Preferences can be accessed using the System Preferences API:
var System = require('dw/system');
var orgPrefs = System.getPreferences();
var myCustomPreference = orgPrefs.getCustom().myCustomPreference;
To add your preferences on this global level, head here in the Business Manager:
Administration > Site Development > System Object Types > OrganizationPreferences
Site Specific Custom Preferences
Site Preferences are site-level preferences that can only be accessed by the site to which they belong. These preferences are ideal for settings that are specific to a site.
For example, if a site has a particular loyalty program calculation not used by any other site, use Site Preferences. This can help ensure that settings are only applied to the site they belong to and do not affect other sites in the organisation.
Site Preferences can be accessed using the Site API:
var Site = require('dw/system/Site');
var sitePrefs = Site.getCurrent().getCustom();
var loyaltyEnabled = sitePrefs.loyaltyEnabled;
To add your preferences on this site level, head here in the Business Manager:
Administration > Site Development > System Object Types > Site Preferences
Code Config Files
Using a config file can be a better alternative to Custom Preferences. A config file is a file that stores application-specific settings that should not be modifiable in the Business Manager. This can be useful for settings that are not expected to change frequently, such as project-specific settings.
// config.json
{
"loyaltyCalculation": "simple"
}
// Using the config
var config = require('path/to/config.json');
if(config.loyaltyCalculation === 'simple') {
// Do some things
}
Tips & Tricks
Custom Attributes
If you have reviewed the sample code, you may have noticed that these preferences are similar to how you use custom attributes. That’s because they are custom attributes on System Objects, just like any other extensible object within the data model.
Default Values
Luckily, we have the option to set default values for our preferences. This will make it easier if you have a large set of sites, but only one uses a different value than the one you have in mind as the default.
Another advantage of setting this default is that your preference will have a preset value right after deployment!
Add Descriptions
When creating preferences in the business manager, add proper names and descriptions. This will make it easier for users and other developers to understand the purpose of this preference. Without it, it is like having a complication function in the code with no documentation to explain what it is up to!
Getting to the truth
Have you ever encountered a feature in Production that suddenly stopped working due to a preference update, leaving you scratching your head? Fear not! The “Change History” feature is here to save the day! It can help you track down the exact moment and preference that caused the chaos.
SCAPI
Right now, there is no SCAPI endpoint available to fetch site preferences. Only OCAPI endpoints are available to fetch this information.
Conclusion
Using the appropriate type of preference can help ensure that settings are applied correctly and efficiently. Each option has pros and cons, and make sure to weigh in roles and users in making these decisions!
