Create Custom Preferences

In Salesforce B2C Commerce, you can create custom preferences for sites, and then view and edit them both locally and across multiple sites. Custom preferences enable site developers to make properties of the system modules configurable in Business Manager.

Custom preferences can:

  • Define a preference type
  • Define a preference group
  • Group preference types into preference groups
  • Set the value of a preference for a particular site or across multiple sites
  • Read the value of a preference from a custom application (for example, a pipeline or B2C Commerce script)

One way to achieve higher flexibility when implementing customized functionality for a system is to make certain features and properties configurable. Making them configurable allows for easy adaptation of the system functionality to changing requirements later.

You can create custom preferences for your sites to make your settings configurable. Custom site preferences are defined in the context of the SitePreferences system object.

Note: You must have write permission for System Object Types to configure site custom preferences. If you have read-only permission, you can view the settings, but you can't change them. This permission also applies to changes via B2C Commerce API calls.

You can also get and set custom preferences programmatically.

Note: The list of preferences and groups appear in the order in which they were configured in the system object definition.
  1. Create an attribute grouping and corresponding set of attribute definitions.
    1. In Business Manager, select Administration > Site Development > System Object Types.
    2. Select SitePreferences.
    3. Click the Attribute Definition tab.
    4. Click New and define custom site attributes:

      Enter or select these values:

      • ID: processingDays
      • Display Name: Sample custom preference
      • Help Text: This is the number of days to process an order
      • Value Type: Enum of Strings
    5. Click Apply.
    6. You can now select the following:
      • Mandatory: The field must be selected or contain text.
      • Externally Managed: The field is populated externally.
      • Select Multiple: (Applies only for Enum of Strings.) The user can select multiple choices. This field shows as a list of elements. The user must use standard keyboard elements, such as Ctrl on Windows or Command on a Mac to select more than one element.
        Note: The customizable options vary based on the value types selected previously.
    7. Click Apply.
    8. Enter these Value | Display Value definitions and click Apply after each entry, as follows:
      • 5 | orderProcessing (make this value the default)
      • 6 | shipDays
      • 11 | totalDays
    9. Click <<Back and click the Attribute Grouping tab.
    10. Enter the following:

      ID: processTime

      Name:totalProcessTime

    11. Select the language and click Add.
  2. To assign attributes to an attribute group:
    1. Select SitePreferences.
    2. Click the Attribute Grouping tab.
    3. You can assign attributes to the group.
    4. At the processTime row, click Edit.
    5. Click ..., select the processingDays attribute, and click Select.
  3. You can search for an existing custom preference group.
    1. In Business Manager, select site > Merchant Tools > Site Preferences > Custom Preferences
    2. To search for an existing preference group, enter an ID or name and click the search icon.
      You can view up to 200 preference groups on page.
    3. Click the filter icon, select Description, enter text (for example, storefront), and click Add Filter to include only preferences that include this text in the Description field.
  4. You can edit the values of custom preference.
    Note: If you’re making edits for your production instance, make the edits from your staging instance. Select Production from the Instance Type dropdown, and make your edits. To replicate the changes to your production instance, perform a data replication from staging to production using the Custom Preferences replication task.
    1. From your staging instance of Business Manager, select site > Merchant Tools > Site Preferences > Custom Preferences. On the Custom Site Preference Groups page:
    2. From the Instance Type dropdown, select the instance where you want the changes replicated, sandbox, staging, or production.
    3. To edit an existing preference, click a preference group ID.
      You can search and filter on this page. You can also select an instance type, and enter preference values for each instance type.
      Click Save after you set values for your preferences. If you don't have permission to create custom site preferences on the current site the Save button isn’t available.
    4. To create a custom preference, click New.
      The New button is only available if you have permission to edit the System objects types.

      The Attribute Grouping tab opens for the SitePreferences system object, where you can create you're an attribute grouping (see 2).

      If you click <<Back to List, the System Object Type List page opens.

      You can create an attribute (see 1) and assign it to the group.

    5. Click Apply.
  5. To view site preferences across sites:
    1. Select site > Merchant Tools > Site Preferences > Custom Preferences. On the Custom Site Preference Groups page, click View (in the View Across Sites column) to view an individual site preference group. You can also click the View Across Sites button at the top of the page.
      For a setting that is too long to appear in the field, hover over the field, and a tooltip shows the entire setting. To show the tooltip continuously, click the lock icon.
    2. On the Custom Site Preference Groups - Multisite View page, you can search for and filter preferences by ID.
      To search or filter on this page, you must first select a preference group.
    3. Select a preference group.
      This value is preselected when you click the individual View button on the Custom Site Preference Groups page.
    4. Select an instance type.
    5. Click the expand icon for a preference that you want to edit or view.

      Multi-select enum of string attributes appears with a line item for each value.

      You see only the sites for which you have permissions.
    6. To edit the preference for that site, click a site name. On the preference page for that site, you can edit the preference.
  6. To edit a site preference across sites:
    1. From your staging instance of Business Manager, select Merchant Tools > site > Site Preferences > Custom Preferences. On the Custom Site Preference Groups page, click a preference group.
    2. On the preference page, click the Edit Across Sites link in the preference row.
      On the Custom Site Preference Groups - Multisite View page, you can also click the Edit Across Sites link in the preference row.
    3. From the Instance Type dropdown, select the instance where you want the changes replicated, sandbox, staging, or production.
    4. On the Edit Preference Values Across Sites page, you can specify the same or a different value for each site.
      To change the preference and instance type, use the breadcrumb beneath the page title.
      You can only view or edit the preference values if you have permissions for the site (read or write).
    5. Click Save.
      This button only appears if you have write permissions.
  7. To apply a bulk edit across sites, perform the following steps:
    1. From your staging instance of Business Manager, select site > Merchant Tools > Site Preferences > Custom Preferences. On the Custom Site Preference Groups page, click a preference group.
    2. From the Instance Type dropdown, select the instance where you want the changes replicated, sandbox, staging, or production.
    3. On the preference page, click the Edit Across Sites link in the preference row.
      On the Custom Site Preference Groups - Multisite View page, you can also click the Edit Across Sites link in the preference row.
    4. Click Bulk Edit.
      This button only appears if you have write permissions.
    5. On the Select Update Value window, enter the new preference value, select from an existing value, use the default, or remove all values.

      For multi-select attributes (set of X, and enum with multi select enabled) a grid with checkboxes appears, from which you can select one or more values.

      For existing values on a password field, click the spy button to unmask the passwords so you can select the correct value.

    6. Click Next.
    7. On the Site Selection window, you can search by ID.
    8. Select from a matrix of sites and instances.
      The sites for which you don't have write permission are disabled. Instances don't have permissions on their own; but if you don't have permission for the site, the instance is also disabled.
    9. Click Apply. The Edit Preference Values Across Sites page reopens.
  8. To apply a site's site preference values to other sites:
    1. From your staging instance of Business manager, select site > Site Preferences > Custom Preferences. On the Custom Site Preference Groups page, click a preference group.
    2. From the Instance Type dropdown, select the instance where you want the changes replicated, sandbox, staging, or production.
    3. Change one or more preference values.
    4. Click Save.
    5. On the preference page, click Apply to Other Sites.
    6. On the Preference Selection page, select the preferences you want to apply to other sites, and then click Next.
    7. On the Site Selection page, select all sites, or one or more sites, by instance (Sandbox, Staging, or Production) and click Next.
      You can select every site (or instance) at once, or you can select every site for an instance with a single click.
      If you can't select sites and instances on this page, you don't have permission to do so.
    8. On the Summary page that shows your changes, click Apply to save them.
      On the summary page, click Preference Selection or Site Selection on the left to return to a previous step.