Elastic Path Commerce Manager Settings

In Elastic Path Commerce 6.1, most application settings were moved from the web applications’ commerce-config.xml files to the database. These settings can now be edited from the Commerce Manager application.

In addition, some services were created to facilitate retrieval and storage of setting related information.

The settings framework also provides fine-grained control over when setting changes are applied to the system. In the past, most setting changes required restarting the server. Now, when the setting change is applied depends on how you’ve configured its refresh strategy.

Setting Types

There are four setting types:

• System settings: these settings apply globally across the system

  For example, the assets folder location is a system setting.

• Store-specific settings: these settings can be configured differently for individual stores

  As an example, the theme setting is store-specific; each store can have a different value for this setting.

• Application-specific settings: these settings can be configured differently for different applications

  In Elastic Path there are some settings that can have different values depending on whether the context is a web service, one of the web applications (Cortex, Search Server, Integration Server), or the Commerce Manager.

• Search settings: search settings are used to configure the search indexes

  These settings can be configured differently for each combination of store, application, and search index

Refresh Strategies

Application administrators can change setting values at any time. However, changes are not necessarily applied immediately. In many cases, applying changes immediately would not be desirable, but in others it would. Administrators have complete control over when setting changes take effect. Note, only settings that affect end user experience have a refresh strategy. Other settings are updated as required. By default, there are three refresh strategies:

• Application: Settings that use the application refresh strategy are only applied after the application is restarted

  Prior to 6.1, this was the strategy used by most settings, since many of them were stored in properties files and XML configuration files that are only read when the web application is started. Many of these settings are now in the database, which means that other refresh strategies are now available.

• Interval: Settings that use the interval refresh strategy are cached for a specified period of time

  Users do not see changes until the cache expires.

• Immediate: Settings that use the immediate refresh strategy are not cached; values are updated immediately

  As soon as the administrator changes a setting that uses this strategy, the change is applied everywhere. This results in faster retrieval times and ensures that the value is always current, but incurs some additional performance overhead because the data is retrieved from the database every time it is requested

Elastic Path assigns refresh strategies based on performance test results and only after careful consideration of the impact on both performance and overall user experience. Before you change the refresh strategy of a setting, make sure you have carefully assessed the impact. Test your changes in development before applying them in a production environment

Assigning a refresh strategy

To assign a refresh strategy, edit the setting in the Commerce Manager and add a metadata named apiRefreshStrategy. Then set the value to one of the following:

• application
• interval:timeout=<cache_setting_name>
  • <cache_setting_name> - is the name of the cache setting that specifies the timeout period
• immediate

Database

Settings related information is stored in three tables:

• TSETTINGDEFINITION

  This table contains the definitions of the settings: the path, the description, the default value, etc.

• TSETTINGVALUE

  Each setting can have different values in different contexts. For example, the theme setting (COMMERCE/STORE/theme) can have a different value for each store. This table associates the setting values to their setting definitions.

• TSETTINGMETADATA

  Each setting can have metadata associated with it. For example, the refresh strategy is implemented as a metadata item. This table associates the setting metadata to their setting definitions

Setting definitions and values can be added to the database directly through these tables, but the preferred way is to use the new settings service APIs

SettingsService and SettingsReader

The ep-settings module contains services that allow developers to manage settings in Elastic Path. One of them is the settings service. The com.elasticpath.settings.SettingsService interface provides a set of methods for retrieving, creating, updating, and deleting setting values and setting definitions. The following example shows how to retrieve the value of the pagination setting for a store.

String settingName = "COMMERCE/STORE/CATALOG/catalogViewPagination";

// get the settings service
SettingsService settingsService = this.getSettingsService();

// get the pagination for the specified store
SettingValue settingValue =   settingsService.getSettingValue(settingName, storeCode);
String itemsPerPage = settingValue.getValue();

Setting value information is stored in com.elasticpath.settings.domain.SettingValue objects.

The settings service bean is defined in com.elasticpath.core/WEB-INF/conf/spring/service/service.xml. Elastic Path services that require access to settings have been refactored to use this new bean. If you have a custom service that needs access to settings, simply inject this bean into your service’s bean definition.

The SettingsReader interface exposes most of the same functionality but does not support writing. If you do not need to update setting information, use the SettingsReader interface.

warning

Whenever possible, you should be using instances of com.elasticpath.settings.impl.CachedSettingsReaderImpl to read settings. SettingsServiceImpl ignores the refresh strategy and bypasses caching, which can have a negative impact on performance.

SettingFactoryBean

You can also inject a setting value directly from Spring using the SettingFactoryBean. This is easier than injecting the SettingsReader into your class and hand-coding the calls to read the value. The following example shows a bean definition that injects a settings value for the value of a bean property:

<import resource="classpath:spring/settings/ep-settings.xml" />

<bean id="beanWithPropertyHoldingSettingValue" class="com.something.YourBean">
     <property id="valueFromSettingsDb">
          <bean parent="settingFactoryBean">
               <property name="path" value="PATH/TO/SETTING/value" />
          </bean>
     </property>
</bean>