Skip to content

Getting started with Configuration Manager

This guide explains two ways to start using Configuration Manager: generating a new application with Configuration Manager already integrated, or integrating it by hand into an existing application.

Quick Start with Craft

The fastest way to try Configuration Manager is to generate a new application with Craft, the AppJars project generator. Craft produces a runnable Spring Boot and Vaadin project with Configuration Manager already integrated, so none of the manual integration steps are needed.

  1. Open craft.appjars.com and select the Configuration Manager card in the Modules section. Other AppJars can be selected as well; Craft wires them together.
  2. Adjust the Project and Appearance settings if needed, and click Download project.
  3. Extract the downloaded archive and run docker compose up -d from the extracted folder. The first start takes a few minutes while the application image is built. To run the application with Maven instead, run mvn spring-boot:run.
  4. Open http://localhost:8080; the Configuration Manager views are in the navigation drawer.

When User Manager is selected as well, per-user configurations belong to the signed-in account and the administrator view lists the application users.

Unless User Manager or Issue Tracker is selected as well, the generated application has no login page and every view is accessible without signing in.

The Craft Project Generator page describes every option and the contents of the generated project. Continue with Testing the Application to try Configuration Manager.

Manual Integration

Prepare the Application

The following steps integrate Configuration Manager into an existing Spring Boot and Vaadin application. To follow them from a blank application, open Craft, leave every module unselected, and click Download project. Extract the archive, import it into your IDE of choice, and verify the application starts correctly by running the main class. A project generated by Craft already declares the AppJars repository, so the next step can be skipped.

Add the AppJars Repository

AppJars artifacts are published to the public AppJars Maven repository. Add it to your pom.xml so that Maven can resolve the AppJars dependencies:

<repositories>
    <repository>
        <id>appjars</id>
        <name>AppJars Public Repository</name>
        <url>https://maven.appjars.com</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Add the Dependencies

Given that it is a monolithic application, the following dependencies representing the three layers of the appjar must be added:

<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-configuration-manager-flow</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-configuration-manager-data-impl</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-configuration-manager-business-impl</artifactId>
</dependency>

After adding them, build the application to confirm that the dependencies are resolved correctly.

Implement the User Provider

Configuration Manager needs to identify the currently authenticated user and retrieve the list of all usernames in the application. The appjar does not ship an implementation, so provide one by implementing the UserProvider interface and registering it as a Spring component:

@Component
public class AppUserProvider implements UserProvider {

    @Override
    public String getPrincipalUsername() {
        return SecurityContextHolder.getContext().getAuthentication().getName();
    }

    @Override
    public List<String> getAllUsernames() {
        // Return the list of all usernames in the application
        return userRepository.findAllUsernames();
    }
}

The import for UserProvider is com.appjars.configurationmanager.service.UserProvider.

  • getPrincipalUsername: Returns the username of the currently logged-in user. This is used to display and save that user's personal configurations.
  • getAllUsernames: Returns the full list of usernames available in the application. This is used in the administrator view to manage configurations on behalf of any user.

Configure the Router Layout

Inject the RouteConfigurer provided by Configuration Manager and configure the router layout in a @PostConstruct method so that the appjar views share the same layout as the rest of the application:

@Autowired
@Qualifier("ConfigurationManagerRouteConfigurer")
RouteConfigurer routeConfigurer;

@PostConstruct
public void configure() {
    routeConfigurer.setViewsRouterLayout(MainLayout.class);
}

The import for RouteConfigurer is com.appjars.configurationmanager.flow.util.RouteConfigurer.

Add the Views to the Navigation

Configuration Manager provides three views. Add them to the application's navigation menu by inserting the following snippet at the end of the method createNavigation() in MainLayout, before returning nav:

if (accessChecker.hasAccess(SystemConfigurationsListView.class)) {
    nav.addItem(new SideNavItem("System Configurations", SystemConfigurationsListView.class, LineAwesomeIcon.SLIDERS_H_SOLID.create()));
}
if (accessChecker.hasAccess(UsersConfigurationsListView.class)) {
    nav.addItem(new SideNavItem("User Configurations", UsersConfigurationsListView.class, LineAwesomeIcon.USERS_COG_SOLID.create()));
}
if (accessChecker.hasAccess(MyConfigurationsView.class)) {
    nav.addItem(new SideNavItem("My Configurations", MyConfigurationsView.class, LineAwesomeIcon.USER_COG_SOLID.create()));
}

The imports for the view classes are:

  • com.appjars.configurationmanager.flow.view.SystemConfigurationsListView
  • com.appjars.configurationmanager.flow.view.UsersConfigurationsListView
  • com.appjars.configurationmanager.flow.view.MyConfigurationsView

The System Configurations and User Configurations views are intended for administrators. The My Configurations view is accessible to all authenticated users and shows only their own configuration values.

Configure Application Properties

Add the following properties to application.properties:

spring.jpa.hibernate.ddl-auto=update
spring.jpa.generate-ddl=true

Finally, add com.flowingcode and com.appjars to the list of whitelisted packages in application.properties:

vaadin.allowed-packages = com.vaadin,org.vaadin,dev.hilla,com.example.demo,com.flowingcode,com.appjars

Testing the Application

Start the application by running the main Spring Boot class. After it starts, log in and navigate to System Configurations in the menu.

Create a new configuration entry by clicking the New configuration button, providing a key, a type, and a default value. Once saved, the entry appears in the grid, and the Edit value action changes its value at runtime without restarting the application.

To confirm that the value reaches application code, name the entry after a property the application already reads. For example, with a bean holding:

@Value("${com.myapp.report.pageSize:20}")
private int pageSize;

create a system configuration named com.myapp.report.pageSize of type INTEGER. Its value now takes precedence over both the fallback 20 and any value set in application.properties. Because a @Value field is resolved when its bean is created, the running instance keeps the value it started with; read the property through Environment.getProperty() to observe changes immediately, or see the Developer Guide for the optional restart mechanism.

Finally, navigate to My Configurations to verify that a user configuration is visible and editable from the user's own perspective.