Add a Custom Preference Programmatically

You can get and set custom preferences programmatically using the Salesforce B2C Commerce APIs and via the Business Manager extension mechanism.

To configure a new custom preference:

Define the preference group and definition in the Business Manager user interface.
Embed the preference in your custom application using the GetPreferenceSet pipelet and access its values from the returned PreferenceSet object.
Extend the bm_extensions.xml file of the cartridge directory of the custom cartridge to define a preference editor for the new preferences.
You can use the Business Manager extension descriptor to assign the necessary permissions to configure the custom preferences.

Setting Preference Values

Business Manager extensions reside in a cartridge. The cartridge has a pipeline and the pipeline has two sub pipelines, one for site actions and one for admin actions. The pipelines each have one script node. The script node uses the XML file bm_extensions.xml to create the extensions.

Note: You can create a controller to replace the pipeline provided by default in the cartridge, but there is no reason to because you will still have to use the XML file. Business Manager extensions, like jobs, should be done with pipelines.

You can use the Business Manager extension mechanism to set the values of the defined preferences for a particular site. Use the CustomPreferences pipeline with the View start node. The pipeline can be configured by passing the following parameters:

PrefGroupName: (mandatory) ID of the preference group whose values are to be configured through this preference editor.
Domain: (optional) name of a domain for which the values are to be configured. By default, the preferences of the site, to which this preference editor is deployed, are configured.
instType: (optional) initial instance type that is selected when this preference editor starts.

Example

The following is an example snippet of a bm_extensions.xml file that deploys a preference editor for the preference group with the ID CreditCardPreferences into Business Manager: site > Merchant Tools > Site Preferences > Custom Preferences > site preferences.


<menuaction id="credit_card_prefs" menupath="site-prefs" position="500" site="true>
	<name xml:lang="x-default">Credit Card Preferences</name>
	<short_description xml:lang="x-default">
		Credit Card preferences
	</short_description>
	<description xml:lang="x-default">
		Configure the Credit Card preferences
	</description>
	<parameters>
		<parameter name="PrefGroupName" value="CreditCardPreferences"/>
	</parameters>
	<icon>icons/pref_ico.gif</icon>
	<exec pipeline="CustomPreferences" node="View"/>
	<permissions>
		<permission>SLD_MANAGE_SITES</permission>
	</permissions>
</menuaction>