Setting Utilities
Essential knowledgeCore knowledge to understand Fluent Commerce
Intended Audience:
Technical User
Author:
Kirill Gaiduk
Changed on:
10 July 2025
Overview
The`SettingUtils` class in the `util-core` bundle provides a robust set of tools for retrieving configuration settings from the Fluent Commerce API. A key feature of this utility is that it automatically respects the platform's setting hierarchy, ensuring that the most specific setting value is always returned.Key points
- Automatic Hierarchy:
`SettingUtils`automatically respects the Fluent Commerce setting hierarchy (Location > Retailer > Account > Global), so you always get the most specific value without any extra work. - Type-Safe Conversion: The
`.as(MyClass.class)`method allows you to convert a setting's value to any type—from simple primitives (`String`,`Integer`) to complex POJOs—in a single, null-safe operation. - Efficient Bulk Fetching: You can retrieve multiple settings (
`getSettings`) or a group of settings by a common prefix (`getSettingsByNamespace`) in a single API call, which is more performant than fetching them one by one.
The Setting Hierarchy
Fluent Commerce allows settings to be defined at multiple levels. When you request a setting, the platform searches for a value in the following order of precedence:- Location: Settings for a specific location (also known as Agent).
- Retailer: Settings for a retailer.
- Account: Settings across the account.
- Global: Reserved for platform use.
`SettingUtils` automatically handles this hierarchy for you. When you request a setting, it returns the value from the most specific context that has one.Core Methods
`getSetting`
This is the simplest method for retrieving a single setting. You provide the setting's name, and it returns a `Setting` object. The `Setting` Object
The `getSetting` method returns a `Setting` object, which has a powerful `.as()` method. This allows you to convert the setting's value into the data type you need, including complex POJOs if the setting is stored as JSON.`getSettings`
If you need to retrieve multiple settings at once, `getSettings` is more efficient than calling `getSetting` repeatedly, as it fetches all specified settings in a single API call.You provide a `Map` where the keys are your own identifiers and the values are the setting names. The method returns a new `Map` with the same keys, but with each value replaced by a `Setting` object containing the corresponding setting value.`getSettingsByNamespace`
This method allows you to fetch all settings that share a common prefix or "namespace". This is useful for retrieving a group of related settings without having to know all their individual names.If a setting contains both a `value` and a `lobValue` (line-of-business-specific value), this method will prioritize `value`, giving preference to the primary configuration over the business-specific one. The result is returned as a `Map`, where the keys match those provided in the request, but each value is replaced with a `Setting` object containing the resolved setting value.