Migration from Classic UI

Due to the major incompatibility between Classic and Flow UI, the automatic upgrade from Jmix 1.x Classic UI to Jmix 2.3 is impossible.

There are two methods of manual migration. The first one is more generic and applicable to projects using both Jmix 1.5 and 1.6, but it is also more laborious. This method is described in detail in the guide on the forum.

The second method relies on the fact that Jmix 1.5 includes an experimental implementation of Flow UI, and Studio can automatically migrate projects using Flow UI from version 1.5 to the latest version 2.x. This method can only be used for projects based on Jmix 1.5.

Below we provide instructions on how to upgrade an application based on Jmix 1.5 Classic UI using the second method.

Converting Project to Flow UI

First, you need to remove Classic UI from the project and adapt the project structure and build scripts to Flow UI.

  1. Open the Classic UI project in the IDE.

    Later in this guide we will refer to this project as the "migrating" one.

  2. Create a new project on the latest Jmix 1.5 version in a different folder using the Full-Stack Application with Incubating FlowUI template. Choose the same name and base package as in the migrating project.

    Later in this guide we will refer to this project as the "created" one.

  3. Copy the following files from the root of the created project to the migrating one:

    .gitignore
build.gradle
package.json
tsconfig.json
types.d.ts
vite.config.ts

    Here and below do the copying by executing Copy in the Project tool window of the source project, then executing Paste on the appropriate node of the destination project.

  4. In the migrating project, remove the following directories (turn off Safe delete to avoid useless IDE warnings):

    1. src/main/java/<base_package>/screen

    2. src/main/resources/<base_package>/screen

    3. src/main/themes

    4. src/main/resources/<base_package>/theme

  5. Copy the following directories from the created project to the migrating one:

    1. frontend

    2. src/main/java/<base_package>/view

    3. src/main/resources/<base_package>/view

    4. src/main/resources/META-INF

  6. In application.properties of the migrating project:

    1. Remove jmix.ui.* properties.

    2. Copy jmix.flowui.*, ui.*, vaadin.* properties from the created project to the migrating one.

  7. Copy the src/main/resources/<base_package>/menu.xml file from the created project to the migrating one and overwrite the existing file.

  8. Open src/main/resources/<base_package>/messages_en.properties file of the migrating project and remove <base_package>.screen.* and <base_package>/menu.application messages from it. Copy <base_package>.view.* and <base_package>/menu.application.title messages from the same file of the created project.

  9. Copy FullAccessRole and UiMinimalRole classes of the <base_package>.security package from the created project to the migrating one.

  10. In other existing roles of the migrating project, remove the io.jmix.securityui.role.annotation.MenuPolicy and io.jmix.securityui.role.annotation.ScreenPolicy annotations.

  11. Add the following code to the main application class:

    @Push
@Theme(value = "<project_name>")
@PWA(name = "<project_name>", shortName = "<project_name>")
class ... implements AppShellConfigurator

    For example:

    // ...
import com.vaadin.flow.component.page.AppShellConfigurator;
import com.vaadin.flow.component.page.Push;
import com.vaadin.flow.server.PWA;
import com.vaadin.flow.theme.Theme;
// ...

@Push
@Theme(value = "onboarding")
@PWA(name = "Onboarding", shortName = "Onboarding")
@SpringBootApplication
public class OnboardingApplication implements AppShellConfigurator {

  12. Run the Reload All Gradle Projects action in the Gradle tool window to re-import the project in the IDE.

  13. Upgrade the project to the latest Jmix 2.3 using the standard Studio upgrade procedure.

  14. Add required add-ons using the Marketplace or by adding starters manually as described in the add-on documentation.

  15. Execute Build → Build Project and resolve compilation errors if any.

  16. Run the application.

    1. Studio will show the Liquibase Root Changelog Check window and suggest to remove the include statements that refer to modules not available for Jmix 2.3 Flow UI project (for example, /io/jmix/uidata/liquibase/changelog.xml). Accept the changes and proceed.

    2. Studio will create a few changesets for dropping UI_FILTER_CONFIGURATION, UI_SETTING and UI_TABLE_PRESENTATION tables. You should save and apply these changesets because these tables do not contain any useful data for Flow UI.

    3. If your database contains tables of add-ons not present in Jmix 2.3, make sure you don’t drop these tables. Either click Remove from Changelog → Remove and Ignore for the corresponding dropTable changesets in the Liquibase changelog generation window, or cancel the process and add the main.datasource.studio.liquibase.exclude-prefixes application property before running the application again. For example:

      main.datasource.studio.liquibase.exclude-prefixes = FOO_

After the application is started, you should be able to log in and open the standard user management views.

Developing New Views

At this point, you have a working application based on Jmix 2.3. The user interface includes only views provided by the new application template: LoginView, MainView, UserListView and UserDetailView.

The next step is to create CRUD views for your data model entities using the View Creation Wizard.

As a result, you will have the application with the old data model and backend logic and a new user interface that allows you to manage data through the standard list/detail views. After that, you will need to customize the user interface using the Flow UI API and set of components.