Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. The Developer Center continues to support Commerce 6.13.0 through 7.4.1.Visit new site

Injecting System Settings

Injecting System Settings

Overview

The Elastic Path bean framework supports adding variability to classes and modifying the behavior of default classes without modifying default code by injecting Elastic Path system settings into the bean class.

Use system setting injection if you must implement any of the following in a bean:

  • Functionality that is context-specific. For example, a business implementing fraud detection behaviour at a particular purchase threshold across stores which utilize different currencies.
  • Functionality that must be enabled or disabled without redeploying Elastic Path. For example, disabling system emails in a development environment.
  • Functionality using system settings defined by business users in the Admin Console. For example, dynamically changing cart cleanup behaviour to encourage sales completion.

To use system setting injection:

  1. Inject the system setting into the Spring bean definition using the custom Spring element, <settings:setting>.
  2. To retrieve the system setting from the Spring bean definition, use an instance of com.elasticpath.settings.provider.SettingValueProvider<T> for each setting value injected.

Injecting a system setting into a bean definition

To inject a system setting into a bean definition, use the <settings:setting> element in your bean definition, where:

  • PATH/TO/THE/setting is the setting string listed in the system settings, or a new system setting implemented for your project.
  • The <settings:setting> element is wrapped in a <property> element has a name attribute value of the setting value provider instance which uses the setting.
<property name="SettingValueProviderInstance">
    <settings:setting path="PATH/TO/THE/setting"/>
</property>

Retrieving setting values with SettingsValueProvider

To retrieve a setting value using com.elasticpath.settings.provider.SettingValueProvider<T>:

  1. Instantiate a SettingValueProvider<T> where the generic type is the same as the data type of the setting to retrieve. See system settings to see the data type of each system setting.
  2. Use one of the following methods defined in SettingValueProvider to retrieve the value of the setting:
    1. SettingValueProvider.get(): returns the value of the setting.
    2. SettingValueProvider.get(String context) returns the value of the setting based on the context value provided.
For example, if you want to use the COMMERCE/SYSTEM/emailEnabled system setting, which has an underlying type of Boolean, define the following SettingValueProvider:
private SettingValueProvider<Boolean> emailEnabledProvider;

Example: Implementing Fraud Checking

This section provides an example use case for setting injection.

Consider the following business requirement:

In order to prevent fraudulent purchases, the business requires that orders above a certain total value are flagged for manual review. The amount varies based on the currency of the country: in the US, the threshold is $1000, whereas in Japan the threshold is ¥100,000.

To enable this, two new setting values were created:

  • COMMERCE/STORE/fraudCheckEnabled, with a type of Boolean.
  • COMMERCE/STORE/fraudCheckOrderValueThreshold with a type of BigDecimal.

In this example, these settings are injected into the FraudCheckEvaluatorImpl bean to implement fraudulence checking.

Step 1: Defining the FraudCheckEvaluatorImpl Spring bean

To inject the settings into theFraudCheckEvaluatorImpl bean, provide the settings described above to the bean definition:
<bean id="fraudCheckEvaluator" class="com.elasticpath.extensions.fraudcheck.FraudCheckEvaluatorImpl">
    <property name="fraudCheckEnabledProvider">
        <settings:setting path="COMMERCE/STORE/fraudCheckEnabled"/>
    </property>
    <property name="fraudCheckOrderValueThresholdProvider">
        <settings:setting path="COMMERCE/STORE/fraudCheckOrderValueThreshold"/>
    </property>
</bean>

Note that the context parameter is omitted from the Spring configuration. This example provides the context value (i.e. the store code or selected currency code) at runtime, once the customer has provided the information to Elastic Path. Elastic Path recommends providing the context value in the Spring configuration if the context value is known at wiring time, not at runtime.

When the context is supplied within the Spring wiring configuration, it is not necessary to include it in the Java code. In other words, it is not necessary to call the SettingValueProvider.get(String context) method, as calling the SettingValueProvider.get() method uses the context provided by the Spring configuration.

Step 2: Creating SettingValueProvider instances

Define two SettingValueProvider instances, one with a generic type of Boolean, and one with a generic type of BigDecimal:

public class FraudCheckEvaluatorImpl {

    private SettingValueProvider<Boolean> fraudCheckEnabledProvider;
    private SettingValueProvider<BigDecimal> fraudCheckOrderValueThresholdProvider;

    // getters and setters
}

This example assumes that the context values for the settings are storeCode and currency. To retrieve the current setting value, use the SettingValueProvider.get() or SettingValueProvider.get(String context) method:

String storeCode = ...;
Currency currency =  ...;

Boolean fraudCheckEnabled = fraudCheckEnabledProvider.get(storeCode);
BigDecimal orderValueThreshold = fraudCheckOrdervalueThresholdProvider.get(currency.getCurrencyCode());