Application Settings

This add-on provides a simple API and UI to work with mutable values of different types stored in the database. These values are usually used as parameters of different functionality of the application, such as default settings, thresholds, and feature flags.

Installation

For automatic installation through Jmix Marketplace, follow instructions in the Add-ons section.

For manual installation, add the following dependencies to your build.gradle:

implementation 'io.jmix.appsettings:jmix-appsettings-flowui-starter'
implementation 'io.jmix.appsettings:jmix-appsettings-starter'

Important Note for Single Menu Mode Applications

If your application uses Single menu mode, you should manually add menu items after installing an add-on.

  1. Open the Menu Designer in Jmix Studio.

  2. Navigate to the Structure tab.

  3. Available menu items are displayed in the left panel.

    add menu items

  4. To add items:

    • Select the desired items and click the > (Add Selected) button.

    • Or, drag-and-drop them from the left panel into the current menu structure on the right.

This step is required because applications in Single menu mode do not automatically merge add-on menus with the existing structure.

Usage Example

Consider you have a Customer entity and simple business logic:

  • New customers should get default grade (e.g., Bronze/Gold/Platinum) and default country that business users can change at runtime.

  • There is also a notification text that might be used in UI or reports.

  • All these values must be changeable without rerunning the application.

This can be implemented in two steps.

Step 1. Define a settings entity

Create an entity extending the io.jmix.appsettings.entity.AppSettingsEntity class:

@JmixEntity
@Table(name = "CUSTOMER_SETTINGS")
@Entity
public class CustomerSettings extends AppSettingsEntity {

    @AppSettingsDefault("B")
    @Column(name = "DEFAULT_GRADE")
    private String defaultGrade;

    @Column(name = "COUNTRY")
    private String country;

    @Column(name = "NOTIFICATION_TEXT")
    private String notificationText;

    // getters and setters

After this, the Application settings view in your app will allow business users to edit defaultGrade, country, and notificationText.

app settings menu view

Step 2. Use the settings in business logic

To get settings in the application code, use the AppSettings bean. For example, in a Customer detail view or in an entity initializer you can set default values based on settings:

@Autowired
private AppSettings appSettings;

@Subscribe
public void onInitEntity(InitEntityEvent<Customer> event) {
    CustomerSettings customerSettings = appSettings.load(CustomerSettings.class);
    CustomerGrade defaultGrade = customerSettings.getDefaultGrade();

    Customer customer = event.getEntity();
    customer.setCountry(customerSettings.getCountry());
    customer.setGrade(defaultGrade);
}

Currently:

  • When a business user updates the default grade from Bronze to Gold, all newly created customers will be initialized with that setting.

  • When a business user specifies a default country, all new customers will be initialized with that setting.

app settings initialize entity

Similarly, you can use notification text for UI labels or hints by binding it to a label or tooltip.