This manual provides the reference information for CUBA Studio IDE and the features it offers to enhance your productivity when developing applications based on CUBA Platform.

CUBA Studio is based on open-source IntelliJ IDEA Platform and extends its functionality with the following CUBA-specific features:

  • Scaffolding of Gradle build scripts.

  • Scaffolding of data model, database schema and CRUD UI.

  • WYSIWYG designer of screen layout.

  • Developer-friendly features that boost the coding process: actions, intentions, inspections, references.

  • Support for easy internationalization.

  • Creating data model and UI screens for an existing (legacy) database.

  • Hot (re)deploy.

  • Easy migration to new versions of CUBA Platform and Add-ons.

Release Notes

Version 11
  1. The "CUBA Add-ons" screen has been added which allows to manage add-ons included in your project. The screen can be opened by double-clicking ProjectAdd-ons in the CUBA project tree, or from the main menu: CUBAMarketplace. Detailed description of the screen is available in the corresponding section.

    addons market small
  2. The Welcome screen has been added. It simplifies access to common project settings and actions, holds links to documentation and community web pages.

  3. Implemented UI to manage 3rd-party libraries used by the project. It is available in the Project Properties Editor.

  4. The Entity Designer has been re-implemented using native IntelliJ UI components. New designer has the following benefits:

    1. Better responsiveness, faster opening time

    2. Changes to the entity and its attributes are instantly committed into the source code

    3. Integration with IntelliJ smart refactorings such as Safe Delete of entity attributes

      v 11 entity designer
  5. Implemented Safe Delete refactoring of entity attributes. To start this refactoring, remove the attribute in the entity designer or right-click the attribute declaration and choose from the context menu: RefactorSafe Delete…​. This refactoring searches for attribute usages in views, screens and other configuration files. It automatically removes attribute usages that are safe to delete and warns about usages in the code that would need manual repair.

    v 11 safe delete attr
  6. Data Store settings have been moved out from the Project Properties screen. From now Data Store settings are available for viewing and editing in the CUBA project tree → Data Stores section. Main Data Store settings also can be opened from main menu: CUBAMain Data Store Settings. Please refer to the Managing Data Stores section for more details.

  7. An ability to use HSQLDB InMemory as an additional data store has been added.

  8. Added support for MariaDB as a main or additional data store.

  9. Added support for Amazon Redshift as an additional data store.

  10. Add attribute action has been added to the actions panel of the entity source code editor.

    v 11 add attr
  11. Actions supporting EntityChangedEvent listeners have been added to the actions panel of the entity source code editor. They allow you to create new listener or to navigate to already existing listener methods.

    v 11 entity changed action panel
  12. The Create CUBA EntityChangedEvent Listener scaffolding dialog has been improved. Now it allows you to create several listener methods in one class and to choose two additional event phases.

    v 11 new entity changed dialog
  13. Added support for more BeanValidation 2.0 annotations in the Entity designer: @NotEmpty, @Positive, @PastOrPresent and others.

  14. When adding attributes to an entity, the entity designer automatically recognizes attribute name that can be displayed as instance caption (name, caption, title etc) and generates @NamePattern annotation if it hasn’t been defined yet.

  15. View designer is now able to rename an already existing view, migrating its usages in the code.

  16. The Inject 'xxx' quick fix which allows you to inject bean based on variable name has been extended to work in the context of both screen controllers and Spring beans. The example how one can utilize this quick fix is presented below:

    v 11 inject before
    v 11 inject after

    To utilize this feature, type variable name of the desired bean in the code of a Spring bean or a CUBA screen controller. Then press Alt+Enter and choose Inject 'beanName' suggestion in the popup list. Class name of the bean is determined automatically based on variable name which must exactly match bean interface name. For example: dataManager, fileStorageService, messageBundle and clusterManagerAPI variable names will be recognized and successfully injected as corresponding CUBA beans.

  17. Added a Java code inspection checking that localization messages targeted by getMessage and formatMessage method calls exist.

    v 11 message quick fix

    Checks are performed for getMessage and formatMessage methods of MessageBundle, Messages and AbstractWindow (legacy screens) classes. If the message with given key in a given message pack does not exist, message key is highlighted in red.

    If you press Alt+Enter and choose Create message in the message bundle quick fix item, Studio will open Localization Message dialog to input localized message for all configured project locales.

  18. Standalone IDE version of the Studio has been upgraded to IntelliJ Community platform 2019.1. Previously downloaded standalone Studio IDE will not be upgraded - you should download new version from the CUBA Platform web site.

  19. CUBA plugin for IntelliJ IDEA containing this release of the Studio has been uploaded to the main (Stable) plugins channel. So it’s not necessary to set up additional plugins repository anymore. If you have used previous versions of CUBA Studio plugin, you can now remove from the list of Custom Plugin Repositories. Custom repositories list is located here: FileSettingsPlugins → "gear" icon → Manage Plugin Repositories.

  20. Numerous small improvements and bug fixes:

Version 10
  1. Code editors of entities, screen controllers and screen descriptors now have a panel on top which provides quick access to CUBA-related actions and navigation between related files. For example, below is the panel in an entity class editor:

    v 10 actions panel

    Using the panel buttons you can quickly navigate to the related DDL scripts, views and screens. Also, you can create new views, screens and JPA lifecycle callback methods.

    The actions are also duplicated in the "intentions" context menu which is invoked by pressing Alt+Enter (Option+Enter):

    v 10 actions menu
  2. Implemented scaffolding of EntityChangedEvent listeners. In order to run it, select an entity class, package, or the top-level Middleware node in the CUBA project tree and click the New > EntityChangedEvent Listener context menu item. Studio will create a Spring bean in the core module with two listener methods: one notified before and another after transaction commit.

  3. Implemented scaffolding of JMX beans. In order to run it, select the Middleware node or one of the packages under the Beans node in the CUBA project tree and click the New > JMX Bean item of the context menu.

  4. Implemented scaffolding of configuration interfaces. In order to run it, select the Project > Config Interfaces node in the CUBA project tree and click the New > Configuration Interface item of the context menu.

  5. The Inject dialog now contains the Project Beans section which allows you to inject any Spring bean available in the project.

  6. The Inject dialog now works for screen controllers written in Groovy too.

  7. Improved injection experience: now if you put the cursor inside a method and invoke the Inject dialog, the resulting field will be generated on top of the class definition and the field name will be automatically copied to the cursor.

  8. Inject component into controller intention is available on the XML element of the component. Try to position cursor on a component XML element and press Alt+Enter (Option+Enter).

  9. Implemented visual designer for entity indexes and unique constraints. See the Indexes tab at the bottom of the entity editor.

  10. Implemented inspections about duplicated entity name and table name. They are shown on the entity class if the same entity name or table name is defined for more than one entity class.

  11. Implemented intentions for adding correct JPA annotations to entity fields. It simplifies manual coding of entity attributes: you can just add a field to the entity class, generate getters/setters, and then press Alt+Enter (Option+Enter) on the field to generate annotations.

  12. In the screen controller code, you will get a warning if you inject a screen component not present in the screen’s XML:

    v 10 warn nonexisting
  13. In the entity class code, you will get a warning if the class has no @NamePattern annotation:

    v 10 warn namepattern

    You can fix the problem or suppress the warning by pressing Alt+Enter (Option+Enter) on the class name.

  14. View designer now has a master-detail layout with the list of views on the left and the selected view editor on the right.

  15. For projects based on CUBA 7.1 and above, the following features have been added:

    1. Main screen templates with side menu and responsive side menu.

    2. Support for passing properties to screens and fragments opened declaratively.

    3. Support for REST API add-on.

  16. All Resolved Issues:

Version 9
  1. BREAKING CHANGE: Studio now uses HSQL version 2.4.1. When you open a project using HSQL database, Studio prompts you to update the version of HSQL in the project’s build.gradle. If you accept, the project will correctly work with the Studio v.9+. However, be aware of the following issues:

    1. The application will not start if the project with the new HSQL driver is opened in a previous Studio version containing the older HSQL server;

    2. In the projects with HSQL based on CUBA version before 7.1, Scheduled Tasks do not work because their table has a column named PERIOD which is a reserved word in HSQL 2.4.1. The column is renamed in CUBA 7.1.


      If you are on CUBA 7.0 or below and need to work with HSQL and Scheduled Tasks at development time, you can make Studio to use HSQL 2.2.9 by following these steps:

      1. Exit Studio.

      2. Copy cuba-studio folder:

        • on Windows from C:\Program Files\Haulmont\CUBA Studio 2018.3\plugins\ to %userprofile%\.CubaStudio2018.3\config\plugins\

        • on macOS from /Applications/CUBA to ~/Library/Application Support/CubaStudio2018.3/

      3. Replace hsqldb-2.4.1.jar file with hsqldb-2.2.9.jar in the copied cuba-studio/lib folder. You can download the file here.

      4. Start Studio and open your project.

      5. Replace def hsql = 'org.hsqldb:hsqldb:2.4.1' with def hsql = 'org.hsqldb:hsqldb:2.2.9' in the build.gradle.

      Now both Studio and your project will use HSQL 2.2.9 and the application based on CUBA 7.0 and below can work with Scheduled Tasks on HSQL.

  2. Hot deploy mechanism now deploys all dependent classes together with the changed one, which eliminates ClassCastException on opening modified screens.

  3. When selecting MySQL or Oracle database, Studio shows a dialog where you can click a link for downloading the JDBC driver from the vendor website and then upload it from the local file system to the correct locations in the project and Studio itself. After uploading a driver, restart Studio.

    The drivers can be removed from Studio using the CUBA > Database Proprietary Drivers settings page.

  4. DataGrid and TreeDataGrid are available for browser and master-detail screen templates in the Table type field of the Create CUBA Screen wizard.

  5. Extend an existing screen and Entity fragment templates have been added to the Create CUBA Screen wizard.

  6. Undo/Redo actions now work correctly in the screen visual designer.

  7. Implemented auto-complete for data loader query in the screen designer.

  8. Screen designer now has a button in the canvas top right corner to switch to the screen controller.

  9. Warnings in screen XML when invoke and datasource attributes are used in screens based on new API.

  10. If you have added Groovy support in the Project Properties window, you can select Groovy in the Advanced > Controller language field of the Create CUBA Screen wizard.

  11. Services written in Groovy are shown in CUBA project tree.

  12. Notification about new platform versions on project opening.

  13. Refined gutter icons in source code editor.

  14. Entity attribute type can now be freely changed in the entity designer with or without refactoring.

  15. Enumeration designer has been implemented.

  16. View designer has been rewritten with native IntelliJ UI.

  17. Data model generator now contains screen templates based on the new API.

  18. All Resolved Issues:

Version 8
  1. Opening of a project for the first time is now performed through the import wizard. See Opening an Existing Project for details.

  2. The project model is now stored in a file inside the .idea folder, so the Gradle synchronization is not started each time the project is opened.

  3. The Run/Debug Configuration editor now allows you to select a JDK to be used for running the application server. See JVM field on the Configuration tab. The value of JAVA_HOME environment variable is used by default.

  4. Views can be renamed by the standard Refactor > Rename action. This action can be invoked on the view element in the CUBA project tree, on the name attribute of the view XML definition in the views.xml file, and on any reference to this view in the screen XML descriptors.

  5. A view editor can be invoked from the view field of a data container in the screen designer.

  6. Implemented auto-complete and usage reference for screen attribute of the <fragment> XML element in screen descriptors.

  7. Implemented localized message editor for menu captions. Click Generic UI > Web Menu in the CUBA project tree, switch to the Structure tab, select a menu item and click edit in the Caption field.

  8. Implemented warning for enum values without localized captions. If you see the warning, use the Create message in the message bundle quick fix to create a default caption.

  9. Implemented auto-complete for the names of the application properties declared in configuration interfaces. Press Ctrl+Space when defining a property in or files.

  10. All Resolved Issues:

Version 7
  1. If your project is based on CUBA 6.10 and uses BPM, Charts, Full-Text Search or Reports premium add-ons, you should set the premium repository access credentials in ~/.gradle/ as described in the Developer’s Manual. Studio does not pass the credentials to Gradle.

  2. All Resolved Issues:

1. Installation

Before installing CUBA Studio, make sure your system meets the requirements explained in the Setup section of the CUBA Developer’s Manual.

You can install CUBA Studio in two different forms: as a standalone IDE for your operating system or as a plugin for existing IntelliJ IDEA. The Studio standalone IDE is a special build of IntelliJ IDEA Community Edition which includes the CUBA plugin. If you haven’t used IntelliJ IDEA before, we recommend using the standalone IDE.

The IDE has a version corresponding to the IntelliJ IDEA in use, for example 2019.1. The CUBA plugin has its own version starting from 11.

Installers of the standalone IDE for Windows, macOS and Linux can be downloaded from The plugin is available in the IntelliJ plugins repository (see below).

Installation on Windows
  1. Download the cuba-studio-VERSION.exe installer.

  2. Run the installer and follow its instructions: choose the install location, launcher type, folder name, and complete the installation.

  3. Launch the installed application and see below for further instructions.

Installation on macOS
  1. Download the cuba-studio-VERSION.dmg installer.

  2. Double-click the installer, then drag and drop CUBA to the Applications folder. If you have a previous version of Studio and you want to keep it, select Keep Both in the appeared dialog.

  3. Launch the CUBA Studio application and see below for further instructions.

Installation on Linux
  1. Install the required dependency:

    $ sudo apt-get install libgconf-2-4
  2. Download the cuba-studio-VERSION.tar.gz archive.

  3. Move the archive to an appropriate folder, e.g. ~/lib and unpack it:

    $ tar -xvf cuba-studio-VERSION.tar.gz
  4. Go to the bin directory and launch the application:

    $ cd ~/lib/cuba-studio-VERSION/bin
    $ ./
First launch of the IDE

When you launch the standalone CUBA Studio IDE for the first time, you are asked a number of questions:

  • In the first dialog Complete Installation, select Do not import settings and click OK.

  • In the next dialog Customize CUBA Studio you can click Skip Remaining and Set Defaults to accept default settings. You will be able to customize the environment at any time later.

  • See the Getting Started section for how to start a new project or to open an existing one.

IntelliJ IDEA plugin installation
  1. Start IntelliJ IDEA 2018.3 or newer.

  2. Open the Plugins dialog.

  3. Switch to the Marketplace tab.

  4. Enter "CUBA" into the search field. You will see the CUBA plugin in search results.

  5. Click Install and follow further instructions of the IDE.

2. Update

Updating the standalone IDE

You can just download the newer version of the standalone Studio IDE from the website and install it on top of the existing version. All your settings will be preserved.

Instead of downloading and installing the entire IDE application, you can set up automatic update of the CUBA plugin from the plugins repository:

  1. Open the Plugins dialog.

  2. Switch to the Updates tab.

  3. If there are updates available, you will see them in the list. Click Update for the CUBA plugin, and the IDE will download the plugin.

  4. After the download process completes, you will have to restart the IDE to apply the new version of the plugin.

Updating IntelliJ IDEA plugin
  1. Click Help > Check for Update on Windows and Linux or IntelliJ IDEA > Check for Updates on macOS.

  2. If there are updates available, you will see them in the list. Select the CUBA plugin and click Update. The IDE will download the plugin.

  3. After the download process completes, you will have to restart the IDE to apply the new version of the plugin.

3. Getting Started

This section describes how to create new or open an existing project in Studio and start the application.

3.1. Creating a New Project

CUBA Studio provides an easy way to create new CUBA projects from scratch. Just use the New Project wizard and follow the steps below:

  1. In the Welcome to CUBA Studio window, click Create New Project.

  2. Select CUBA Project.

  3. In the Project SDK field, select a JDK corresponding to JAVA_HOME which is set in your environment. If you see the <No SDK> value, click New and select the folder where the JDK is installed, for example C:\Java\jdk8u202-b08 on Windows or /Library/Java/JavaVirtualMachines/jdk8u202-b08/Contents/Home on macOS.

  4. Accept the default repositories configuration, or customize it for the project, and click Next.

  5. Specify the name of the new project in the Project name field. The name should contain only Latin letters, numbers and underscores. Think carefully on the project name at this stage, as changing it later on will require complex manual intervention.

  6. The following fields below will be automatically populated:

    • Project location – the path to the new project directory. You can select another directory by typing it in the field or clicking the ellipsis button next to the field.

    • Project namespace – the namespace which will be used as a prefix for entity names and database tables. The namespace can consist of Latin letters only and should be as short as possible.

    • Root package − the root (or base) package of Java classes. It can be adjusted later, but the classes generated at project creation will not be moved.

    • Platform version – the platform version used in the project. If you don’t have any specific requirements, use the latest released version, i.e. without BETA or SNAPSHOT suffixes. The platform artifacts will be automatically downloaded from the repository on project import.

  7. Click Finish. The empty project will be created in the specified directory, and Studio will start building the project information from Gradle files and indexing the project.

  8. When the project synchronization and indexing process is completed, you will see the CUBA project tree in the Project tool window.

  9. Open the Gradle tool window which is docked on the right side by default. Click the "wrench" icon (Gradle Settings) and select Use JAVA_HOME in the Gradle JVM field. If you don’t see such item in the drop-down list, make sure you have set up your development environment correctly as described in the Setup section of the CUBA Developer’s Manual. Click OK.

  10. Now you can start working with the project.

3.2. Opening an Existing Project

Opening an imported project

If the project has already been opened by CUBA Studio on this computer, do the following:

  1. Use recent projects list; or click Open, select the project’s folder in the file system dialog and click Open button.

  2. Wait for Gradle synchronization and project indexing process to complete. As soon as the CUBA project tree appears in the Project tool window, you can start working with the project.

Opening a project for the first time

If the project has not been opened by CUBA Studio on this computer, for example, just checked out from VCS, do the following:

  1. In the welcome window, click Import Project. If another project is already opened, click File > New > Project from Existing Sources in the main menu.

  2. In the file system dialog, select the project’s root folder containing the build.gradle file, then click Open button.

  3. In the Import Project window, select Import project from external model radio-button and choose CUBA in the list below. Then click Next.

  4. Click Finish on the next page of the import wizard.

  5. Wait for Gradle synchronization and project indexing process to complete. The CUBA project tree should appear in the Project tool window.

  6. Click File > Project Structure in the main menu.

    • Make sure that the Project SDK field has a value corresponding to JAVA_HOME which is set in your environment. If you see the <No SDK> value, click New and select the folder where the JDK is installed, for example C:\Java\jdk8u202-b08 on Windows or /Library/Java/JavaVirtualMachines/jdk8u202-b08/Contents/Home on macOS.

    • Make sure that the Project language level field has a value corresponding to the JDK version. For example, if the JDK is 1.8, the language level must be 8 - Lambdas, type annotations, etc.

Opening a project based on CUBA 6.10 for the first time

CUBA Studio supports projects based on CUBA 6.10+ and 7.0. You can open your existing projects created in a previous version of Studio and import them into the new Studio.

Keep in mind that CUBA 6.10 supports only Java 8, so your JAVA_HOME environment variable must point to the JDK 8 installation. Later after migrating to CUBA 7, you will be able to use a newer JDK if needed.

Follow the steps below to open an existing project based on CUBA 6.10 for the first time:

  1. If your project uses premium add-ons (Reports, BPM, etc.) and you have a subscription, you should set the premium repository access credentials in ~/.gradle/ as described in the documentation.

  2. Remove old IntelliJ project files using the gradlew cleanIdea task in the command line.

  3. If the project is under Git version control, add .idea line to the .gitignore file located in the project root. It will ensure your local IDE settings will not be shared between all developers of the project.

  4. Import the project as described in the Opening a project for the first time section above.

3.3. Upgrading a Project

This section covers the process of upgrading a project to a newer CUBA version.


It is recommended to put the project under version control and commit all pending changes before upgrade. It will allow you to see what changes are performed and quickly roll back to a previous version if the upgrade fails for some reason.

  • Open the project as described in the previous section.

  • Click CUBA > Project Properties in the main menu or double-click Project > Properties in the CUBA project tree.

  • In the CUBA Project Properties dialog, select the desired CUBA version in the Platform version field.


    SNAPSHOT versions are available if you use the repository. They are strongly not recommended for use in production.

  • Click OK, then confirm.

  • If you are upgrading to a newer feature release (for example, from 6.10.X to 7.0.X or from 7.0.Y to 7.1.Y), the Migration Required dialog appears. This dialog contains information about migration steps which will be performed automatically by Studio. Review the information and click Migrate.

  • Studio performs automatic migration (if needed) and runs Gradle clean and undeploy tasks.

  • If you are upgrading to a feature release, review Breaking Changes section in Release Notes and make changes in your project accordingly.

  • Try to assemble your project by executing CUBA > Build Tasks > Assemble. Watch the output and fix your code if it doesn’t compile.

  • Execute CUBA > Update Database to incorporate possible framework schema changes into your project’s database.

3.4. Starting the Application

When Studio imports a CUBA project, it creates a Run/Debug Configuration specifically tailored to run local Tomcat server with the deployed application. So in order to run the application and connect to it with the debugger, just click the debug button next to the selected CUBA Application configuration in the main toolbar:

app start 1

See the status in the Console tab of the Debug tool window. You can click to the link printed after the Server started at message to open the application UI in the default web browser.

app start 2

You can also open the running application in the web browser using the Runs At…​ CUBA tree section:

runs at

In order to view the application server output, switch to the catalina.out tab:

app start 3

You can stop the application server by selecting Run > Stop 'CUBA Application' in the main menu or by clicking the button in the Debug tool window:

app start 4

Use of Run/Debug Configuration is the preferred way to start the application in development, but Studio also allows you to control the local Tomcat application server through the CUBA main menu items:

cuba menu appserver

When starting the server by the Start Application Server main menu command, on Windows you will see a console window with the server output. On Linux and macOS, the console is not shown, but you can see the server log by executing tail -f deploy/tomcat/logs/app.log in the Terminal tool window. The Stop Application Server command stops Tomcat by sending the SHUTDOWN signal to the shutdown port specified in the project properties (8005 by default).

4. Studio User Interface

This section describes the user interface of the IDE elements specific to CUBA. For all features of the IntelliJ IDEA, refer to its documentation.

4.1. CUBA Project Tree

The CUBA Project Tree is designed to represent the project structure and its significant elements. It normally opens in the Project tool window on the left side of the IDE. You can always switch to the project tree using the CUBA > Project Tree main menu command or by selecting CUBA in the top drop-down list of the Project tool window.

The project tree contains the following elements:

cuba tree
  1. Project

    • Properties - lets you configure the basic settings of your project.

    • Add-ons - opens the screen to configure CUBA add-ons used in your project

    • Build Script - contains two main project scripts: build.gradle (defines the build configuration) and settings.gradle (defines the project name and the set of modules).

    • Modules - displays all project modules.

    • Data Stores - displays and manages the list of data stores the project is connected to. By default there is only one Main data store.

    • Deployment - enables defining the project deployment options.

  2. Data model - displays and manages the data model of the project.

  3. Middleware - displays and manages middleware services and managed beans.

  4. Generic UI - contains everything related to the project user interface, such as screens, themes, and so on.

  5. REST API - lets you configure the REST API functionality.

  6. Runs At…​ - allows you to open the running application in the external or embedded web browser.

Use the context menu opened by right-clicking on the tree elements to execute actions specific for this project element. For example, using the context menu of the Data Model item, you can generate database scripts, generate model from the database, and create new entity or enumeration:

cuba tree context menu

4.2. CUBA Menu

The CUBA main menu provides quick access to the CUBA-specific features of the IDE. Some of the menu items duplicate the functionality available through the CUBA Project Tree and its context menus.

cuba menu

You can add frequently used menu items to the main toolbar by clicking on the toolbar and selecting Customize Menus and Toolbars. In the Menus and Toolbars dialog, expand the Main Toolbar item and use Add Action command to add items from the Main Menu > CUBA tree.

4.3. Welcome Screen

Welcome screen is always opened in the workspace after new project is created. It also can be opened from the main menu: CUBAWelcome.

This screen provides quick access to main project settings, commonly used actions, documentation and community web pages. It also shows CUBA version used in your project, Studio version and subscription information.

welcome screen

4.4. CUBA Settings

If you click the CUBA > Settings main menu item, you will see the IDE settings window filtered by the cuba word. Find the CUBA section under Languages & Frameworks.

The CUBA section itself contains the settings common to all projects opened in this Studio instance.

  • Ask before saving DB scripts with DROP statements - suggest to exclude update scripts containing DROP statements from automatic execution.

  • Show warning if application server port is in use - show a warning when you open a project and its Tomcat port is currently busy.

  • Use embedded browser to open application - if selected, the embedded web browser will be used when you double-click to the application URL in the Runs At project tree section.

  • Visual designer theme - theme of visual designers. Use Autodetect to select automatically depending on your IDE theme.

  • Visual designer zoom - default zoom of visual designers. You can adjust it in a concrete designer using context menu opened by right-click.

  • Old Studio integration enabled - select this checkbox if you want to integrate this IDE instance with the old Studio SE or Studio Browser Edition. You will be able to open projects from the old Studio in this IDE.

  • Listening port - a port for the old Studio integration. Make sure it is the same as specified in the old Studio IDE Port field.

  • Enable transaction block folding - if selected, Java code editor will fold old-style try-finally blocks used for transaction control.

The nested Project settings section contains the settings of the currently opened project. All non-default values are stored in the studio-intellij.xml file in the project root directory, which can be added to the version control system to share project settings between all developers in your team.

  • Check compatibility between data model and database scheme - show a warning whenever you start the application server and the current state of the data model differs from the database schema.

  • Generate DROP statements in separate update scripts - generate more safe update scripts when you remove an entity, an attribute, or change an attribute’s datatype. Such scripts are split into two parts: in the first part, the column or table is renamed to *__UNUSED, and in the second part these objects are actually dropped.

  • Use NVARCHAR when generating scripts for MS SQL Server - if this option is on, NVARCHAR column type will be used for all String attributes if the database type is Microsoft SQL Server.

  • Generate script name in format - specify yyMMddHHmm to add current time to the names of generated database update scripts, which may help to ensure correct sequence of scripts when working in a team.

  • Do not delete columns started with - this field allows you to specify a prefix for table columns, that should not be tracked by Studio. If you add a column to a table mapped to an entity, and not map the column to an entity attribute, Studio will generate an update script dropping this column. To avoid dropping, you can exclude this script in the Database Scripts dialog, and it will not be generated again. Alternatively, you can set a common prefix for such columns in the Do not delete columns started with field and name the column accordingly. For example, enter NOT_MAPPED_ in the field and name the column NOT_MAPPED_CODE.

  • Column length for enums with ID of String type - this field allows you to set a length of the database column which is mapped to an attribute of enum type with the identifier of String type. For example, if you use short identifiers always consisting of one character, you can set 1 in this field to save database space.

  • Make plural forms - make plural forms of nouns according to English grammar.

  • Repeat entity parent package for screens - if the entity is located in an additional package inside entity, Studio will add this package for Generic UI screens generated by templates. For example, if the Customer entity is inside, the default package for its screens will be

  • Use underscores in generated package names - if selected, package names will include underscores separating words according to camel case in a corresponding entity name. For example, when generating screens for the entity, the package of the screens will be If the option is off, the package name will be

  • Default parent package name for screens - this field allows you to specify a default package to be used instead of screens when generating a Generic UI screen from template not associated with an entity. It is also added before the package with entity name for templates associated with an entity. For example, if you set ui in this field and create a blank screen, the default value for the package will be

  • Default access modifier - sets the modifier which Studio uses when generates entity fields.

  • Generate entity name with underscore symbol - if selected, entity names will have namespace_ClassName format, for example sales_Customer. Otherwise it will be namespace$ClassName.

  • Show module prefix migration dialog - on project opening, suggest migrating build scripts to the new format with module prefix defined in a variable.

  • Instant hot deploy - this checkbox allows you to turn off hot deploy. If hot deployment is enabled, Studio dynamically updates the UI of your deployed web application as you apply or save changes to views, screens, messages or the main menu.

  • Hot Deploy Settings - opens a dialog to customize hot deployment directories. For example, you might want to add folders where your web portal HTML and JavaScript files are located. When you change these files, Studio will copy them to respective destinations inside Tomcat. So you can just reload your web portal page to view the changes.

  • Fold messages in - allows you to control message folding in screen descriptors and controllers. If selected, the message keys will be replaced with actual values from the appropriate message pack.

  • Message folding locale - what message file to use when folding messages.

5. Studio Features

This section of the documentation describes all Studio features that can help you in the developing CUBA applications. The information is mostly structured by the project elements which you see in the project tree.

Some Studio features may conflict with those of IntelliJ Ultimate Edition or some third-party plugins. For example, to avoid conflicts of gutter icons, do the following to disable conflicting Ultimate icons:

  • Select Settings > Editor > General > Gutter Icons in IDEA menu,

  • Uncheck Injection points and Producers for Disposer methods options,

  • Apply the changes.

5.1. Project

This section describes available editors and commands for managing the project infrastructure.

5.1.1. Project Properties Editor

The Project Properties editor allows you to configure your project. You can open it from the CUBA main menu or by double-clicking the Project > Properties item of the project tree.

Basic settings
  • The Repositories field display the repositories currently used in the project. Studio scans these repositories to discover what platform versions are available. Use the buttons next to the field to configure the access to repository. For more details see documentation. You can also manually register in build.gradle any number of additional repositories containing application components.

  • The Platform version field allows you to select a version of the platform. If you choose a newer version, an automatic migration will be performed if required.

  • Groovy support checkbox enables Groovy code within the application: for example, in screen controller classes.

  • The App components group allows you to specify additional platform components that will be used in your project. Custom application components are managed in a separate CUBA Add-ons window.

  • If you need to change the path to the application server, specify the new path in the Tomcat path field. The next execution of gradlew deploy or gradlew start will install Tomcat into that location.

  • The Tomcat ports group allows you to assign non-standard ports for the Tomcat application server installed in the deploy/tomcat folder as a result of fast deployment.

  • In particular, the HTTP port field affects the port Tomcat is listening on for HTTP connection, as well as cuba.webPort, cuba.webAppUrl, cuba.restApiUrl and cuba.connectionUrlList application properties.

  • In the AJP port field, you can set the port for AJP Connector.

  • In the Shutdown port field, you can set the port Tomcat is listening on for SHUTDOWN command.

  • In the Debug port field, you can set the port Tomcat is listening on for Java debugger connection. If you change this port, you should also change it in the debug configuration of your IDE.

  • Available locales field allows you to set locales used in your application. Open the locales editor by clicking the button next to the field. The Locale select visible checkbox located in the editor window controls the value of the cuba.localeSelectVisible application property. The editor also enables defining or overriding format strings for parsing and formatting data.

Dependencies section

The Dependencies section displays and allows to manage 3rd-party dependencies (libraries) connected to your project.


Project dependencies are displayed in a table grouped by module into three or more sections, depending on how many modules your project consists of. If library is added to global module - it effectively becomes globally accessible in the project, because all other CUBA project’s modules depend on the global module.

The Type column in the table shows dependency type:

  • compile - library is used for compilation and runtime

  • provided - for dependencies that are necessary to compile your production code but shouldn’t be part of the runtime classpath (JDBC drivers, Servlet API implementation etc.)

  • runtime - library is only used in runtime

  • testCompile - library is used to compile and run tests

  • testRuntime - library is used by tests, only in runtime

The Text column displays library coordinates in the format of Gradle dependency string: "group:name:version".

Dependency management actions are located right of the dependencies table:

  • Add dependency - add new dependency to your project. Specify Maven dependency declaration or Gradle dependency string. The dialog automatically validates that dependency declaration is correct.

  • Remove dependency - remove dependency from your project.

  • Edit dependency - change dependency declaration text.

Read more about 3rd-party dependencies in the Gradle documentation.

Adding new 3rd-party dependency

Adding a 3rd-party dependency to your project requires the following steps:

  • Find out Maven dependency declaration or Gradle dependency string for the required library.

newdep gradle
newdep maven
  • Copy dependency declaration into the clipboard

  • Open Project Properties dialog

  • Choose the module to attach the dependency to, or use global module to make the library globally available in the project.

  • Press + button right of the Dependencies table. The Dependency Editor dialog opens. Dependency declaration from the clipboard is automatically pasted into the text area.

  • Click OK in the Dependency Editor dialog. Fix the declaration if validation errors are prompted.

  • Click OK in the CUBA Project Properties dialog to apply the changes. Studio will add necessary declarations to the project build script and refresh project configuration.

  • Now you can use library’s classes in your code.


Gradle implementation 'a.b.c' dependency type is not supported yet, please use compile 'a.b.c' instead of it.

5.1.2. Managing Add-ons

Add-ons are publicly distributed full-stack libraries extending your project with additional functionality. More information about add-ons and application components can be found in the CUBA Developer’s Manual.

The CUBA Add-ons dialog allows you to manage add-ons included in your project. It can be opened:

  • by double-clicking ProjectAdd-ons in the CUBA project tree,

  • from main menu: CUBAMarketplace…​

The dialog has three tabs: Marketplace, Installed and Updates.

Marketplace tab

The Marketplace tab displays published add-ons that are compatible with your project.

addons market small

Add-ons are grouped into categories. Searching by filter is available, e.g. "email" or "category:Translation".

Clicking on add-on title leads to the page with detailed overview, compatibility, licensing information:

addon details

In order to install one or more add-ons, press Install for the ones you’re interested and then click Apply or Apply & Close button. After the confirmation Studio will make necessary changes to your project’s build scripts and configuration files, download new libraries and refresh Gradle project configuration.

Installing add-on by coordinates

Add-on coordinates is simply a Gradle dependency string, e.g. "com.mycompany.cuba-addons:myaddon:0.1.5". This string can be published on CUBA platform web site or by author of the add-on. In order to install necessary add-on by coordinates (or by Gradle dependency string), click "gear" icon located right to Updates tab header, and then choose Install by coordinates:

addon by coords
Installed tab

The Installed tab displays add-ons that are already connected to current project.

addons installed

Installed add-ons are grouped into two categories. Marketplace Add-Ons are those which are installed from CUBA Marketplace. Custom Add-Ons are those which are developed by 3rd parties and hosted in 3rd-party repositories, including local Maven.

In order to detach add-on from your project, select corresponding item in the list and press Delete, or right-click → Uninstall. Then click Apply in the dialog. Studio will remove the add-on from the list of project dependencies and update project configuration.

Updates tab

Studio automatically checks whether there are any updates available for add-ons included in your project. The Updates tab displays information about add-ons that can be updated.

addons updates

In order to update the add-on, click Update button, then Apply or Apply & Close button. Studio will upgrade the dependency, download required libraries and refresh project configuration.

Additionally, after the project is opened, notification about available updates is displayed in the down-right corner of the screen:

addon update notification

5.1.3. Managing Modules

Studio lets you create, edit and remove optional modules of your project: core, gui, web, web-toolkit, portal and front. You can do it using CUBA > Advanced > Manage Modules main menu or from the context menu of the Project > Modules item of the project tree.

The Modules section of the project tree displays modules currently used in the project. When you create a new project, it contains global, core and web. For each module, Studio displays configuration files located in this module.

5.1.4. Managing Data Stores

Main Data Store Properties

The Main Data Store Properties dialog displays settings of the main data store. It can be opened:

  • by double-clicking ProjectData StoresMain Data Store in the CUBA project tree

  • from main menu: CUBAMain Data Store Settings…​

You can select the type of your database server in the Database type field. The fields below allow you to change the database URL and specify the username, password and optional connection parameters.

Format of connection parameters depends on the selected DBMS. The string should include a separator between the database name and parameters. For example, to specify a Microsoft SQL Server 2008+ instance name, use the following string in the field:


A custom database connection URL can be specified if Custom database URL checkbox is enabled. Host and Database name should be provided in this case, as they are used in build.gradle separately.

In case of HSQLDB the Studio itself serves the database and stores its files in the build/hsqldb directory.

Additional Data Stores

In order to create the additional data store in the project, right-click Data Stores item in the CUBA project tree and choose NewAdditional Data Store context menu item. Additional data stores registered in the project are displayed as sub-items under the Data Stores section:

additional stores

By right-clicking on an additional datastore item, a context menu is opened:

  • Delete Data Store - remove the data store from the project

  • Edit Data Store - open the dialog to edit data store settings

  • Generate Model…​ - generate data model from the selected data store

The Data Store dialog appears when you create or edit an additional data store. It has the following fields:

  • Data store name - the name of the data store. It may contain only alphanumeric characters and underscores and should be different from the project name.

  • Data store type - the type of the data store: either RdbmsStore or Custom, see the documentation for details. The fields explained below should be set in case of RdbmsStore.

  • DataSource JNDI name - automatically set by Studio on the basis of the data store name.

  • Database type, URL, etc. - database connection parameters.

add store settings

5.1.5. Deployment Settings

Studio contains editors for setting up Gradle tasks that build deployment artifacts. These editors can be opened through the CUBA > Deployment main menu or by double-clicking the items in Project > Deployment project tree section.

WAR Settings editor allows you to set up building of WAR files. After completing the setup, the buildWar task will be created in your build.gradle.

  • Build WAR - if checked, the buildWar task is configured in build.gradle.

  • Include JDBC driver - whether JDBC driver should be included in WAR file.

  • Include Tomcat’s context.xml - whether context.xml (Tomcat deployment descriptor) should be included in WAR file.

  • Custom context.xml path - a path relative to the project root to the context.xml Tomcat deployment descriptor. Enabled if Include Tomcat’s context.xml is checked. Click Generate to create this file automatically.

  • Single WAR for Middleware and Web Client - whether to build a single WAR comprising the Middleware and Web Client application blocks.

  • Custom web.xml path is the file to be used as a special web.xml of the single WAR. Click Generate to create this file automatically.

  • Logback configuration file - a path relative to the project root to the logback.xml configuration file. Click Generate to create this file automatically.

  • App properties - a set of application properties to define for this deployment. The properties will be added to the /WEB-INF/ file inside the WAR.

UberJAR Settings editor allows you to set up building of an Uber JAR. After completing the setup, the buildUberJar task will be created in your build.gradle.

  • Build Uber JAR - if checked, the buildUberJar task is configured in build.gradle.

  • Single Uber JAR - if checked, the buildUberJar task creates a single Uber JAR from all application modules.

  • Logback configuration file - a path relative to the project root to the logback.xml configuration file. Click Generate to create this file automatically.

  • Custom Jetty environment file - a path relative to the project root to the jetty-env.xml configuration file to be used by the embedded Jetty server. Required field. Click Generate to create this file automatically.

  • App properties - a set of application properties to define for this deployment. The properties will be added to the /WEB-INF/ file inside the Uber JARs.

  • Core port, Web port, Portal port fields allow you to set ports for the embedded servers of the corresponding application blocks. Not available if Single Uber JAR checked. Default port values are described in the documentation. You can also set ports when running the JARs using the -port command line argument.

5.2. Data Model

In this section, we explain how to work with the data model of your application.

5.2.1. Working with Entities

Creating new entity
  1. Select Data Model section or a package below it in the project tree and choose New > Entity from the context menu.

  2. The New CUBA Entity dialog appears. Enter the name of the entity class in the Entity name field, select the type of the entity and its id.

  3. Studio will create the entity class and register it in persistence.xml or metadata.xml, depending on the entity type. The created class will be opened in the source code editor. Three tabs will be displayed at the bottom of the editor:

    • Text contains the source code.

    • Designer shows the entity designer where you can configure the entity and its attributes using graphical interface instead of writing Java code.

    • DDL Preview contains the read-only DDL code of the corresponding table and its referential constraints.

Creating entity attributes

There are multiple ways of adding an attribute to an entity.

  • Using graphical interface of entity designer: switch to the Designer tab, click New below the Attributes table and fill the required fields in the New Attribute window.

    The globe button in the right part of the Name field lets you immediately set a user-friendly name of the attribute. It is stored in the file and used by default in UI components. If you have defined multiple languages for your application, you can specify the localized name for all languages.

    attribute l10n
  • Using a separate window opened from the source code, using the button Position the cursor below the last existing field and press Alt+Insert (Cmd+N). In the Generate menu, select Add Attribute…​. Studio will show the New Attribute window as it would be opened from the graphical designer. The same window can be opened by clicking the Add attribute button located in the code editor actions panel.

    new attribute 2
  • You can also write attribute fields by hand, generate getters and setters, and then select JPA Annotations in the Generate menu to add JPA annotations with default parameters.

Studio can help you to add the new attribute to UI screens created for this entity. Position the cursor to the line containing the attribute and press Alt+Enter (Option+Enter) or click the light bulb icon and select Add entity attribute to screens:

add attribute to screens

Press Enter, and Studio will open a dialog with the list of screens working with the edited entity. You can select a screen and Studio will add the attribute to the appropriate UI components of this screen, for example to a table or a form.

Creating the instance name

An entity that can be used as a reference attribute of another entity (for example Customer can be an attribute of Order) requires a pattern to generate the meaningful name of an instance. This pattern is defined by the @NamePattern annotation on the entity class. It can be created in Studio if you position the cursor on the class name, click Alt+Enter (Option+Enter) and select Add name pattern (this item is shown only if the entity has no @NamePattern annotation):

create name pattern

Press Enter, and Studio will show the list of all entity attributes. Select one or several attributes and press Enter. Studio will generate the @NamePattern on the entity class.

Creating messages for new attributes

When you create a new entity attribute manually, its name will be highlighted to remind you of creating a user-friendly attribute name in the corresponding message pack:

create message 1

Click Alt+Enter (Option+Enter) on the highlighted attribute and select Create message in the message bundle:

create message
Removing entities

When you remove an entity class, use the Safe delete option to find and clean up references to this entity:

remove entity

Some references like usages in persistence.xml and metadata.xml files will be deleted automatically. If there are other references, you will see a dialog that shows these references. Click View Usages in the dialog, review the references in the Find tool window and click Cancel or Do Refactor.

5.2.2. Working with Views

To create a new view for an entity, select the entity in the project tree and click New > View in the context menu.

create view

The view designer will be opened. It contains the following fields:

  • Entity name - the name of the entity the view is created for.

  • Name - the name of the new view.

  • Extends - a built-in or custom view which attributes are extended by the new view. There are three built-in views available for any entity:

    • _local contains all local attributes of an entity (the attributes which are not references to other entities),

    • _minimal contains the attributes listed in the name pattern,

    • _base includes all local non-system attributes and attributes defined by @NamePattern (effectively _minimal + _local).

  • Configuration file - a views configuration file to store this view. By default, Studio generates a single views.xml file in the global module.

The full list of attributes of the current entity is displayed in the tree below the fields. You can select which attributes will be included in the view by setting the checkboxes accordingly.

If your view extends another view, all inherited attributes are selected with the checkboxes disabled.

If you select a reference attribute, the following properties will appear in the right panel:

  • Entity - the referenced entity name.

  • View - an optional view to load the referenced entity. It is recommended to use references to named views instead of ad-hoc graph of view attributes, as it makes it easier to maintain complex views. Also, even if you define a view name, you can still add attributes not included in this view by setting the checkboxes in the tree.

  • Fetch - an optional property of reference attributes, specifies how to fetch the related entity from the database. See documentation for details.

When you click OK and close the designer, you can find the new view in the project tree under the entity:

create view 2

If you double-click the view item in the project tree, Studio will open views.xml in the code editor and position the cursor on the view definition. The code editor has two tabs at the bottom: Text and Structure. The latter displays the list of views defined in this configuration file.

When editing a view definition in XML, use Ctrl+Space for auto-completion of attribute names:

view edit 1

and pay attention to highlighted attributes, most probably they do not exist:

view edit 2

You can open the graphical designer for a view in a number of ways:

  • Select the view in the project tree and click the Edit View context menu item.

  • Position the cursor on the view element in the configuration file code, press Alt+Enter (Option+Enter), select Edit view in the popup menu and press enter.

  • Switch to the Structure tab of the configuration file code editor, select the view and click Edit button.

5.2.3. Database Migration

Studio is capable of creating DDL scripts for keeping your database schema up-to-date with the project’s data model. The generated scripts can be executed either from Studio, directly by Gradle tasks or by the application itself on startup.

In order to start generation of DDL scripts, click CUBA > Generate Database Scripts in the main menu or select Data Model in the project tree and click Generate Database Scripts in the context menu.

Studio will open the Database Scripts window with the following tabs:


The Updates tab displays scripts for updating the database to the current state of the data model. Saved scripts are located in the modules/core/db/update directory. The scripts have autogenerated names with prefixes that ensure the order of execution. Scripts containing DROP statements are highlighted in red.

You can add an arbitrary script by clicking the Create button, and it will be saved and executed later together with auto-generated scripts.

The newly generated scripts can be edited or completely deleted by clicking the Remove button.

If you click Exclude selected (exclude), you will have two options:

  • Move the script to the directory of manually executed scripts: modules/core/db/update-manually. Then the script will not be executed automatically when you run Update database, but you will be able to run it manually when needed. This option is useful for scripts that drop columns or tables renamed earlier to *__UNUSED.

  • Exclude the script: it will not be saved to the modules/core/db/update directory, but remembered in the studio-intellij.xml file in your project folder. When you generate scripts next time, Studio will ignore changes, corresponding to the excluded scripts. This allows you to have differences between the database and the model entities.

    For example, you may want to add a database field to a table, corresponding to a project entity, but do not map it to an entity attribute. When Studio generates a script to delete the field from the database, just exclude it, and Studio will never generate it again.

Init Tables

The Init Tables script creates all tables when you execute Create Database. It is executed before the Init constraints and Init data scripts. You can edit the script, but keep the comments dividing tables. The script is saved into the 10.create-db.sql file.

Init Constraints

The Init Constraints script creates referential integrity constraints. It is executed immediately after the Init tables script. You can edit the script, but keep the comments dividing tables. The script is saved into the 20.create-db.sql file.

Init Data

The Init Data script allows you to insert additional data or schema information not present in the data model. It is executed at the end of initialization. The script is saved into the 30.create-db.sql file.

If the project contains an application component (add-on) that does not provide DDL scripts for the current database, Studio generates scripts for this component and shows them in the Init {component} tables and Init {component} constraints tabs. The scripts are saved in 01.{component}-create-db.sql and 02.{component}-create-db.sql files respectively.

Click Save and close to save all generated scripts. You can find the scripts in the Project > Data Stores > Main Data Store project tree section.

In order to run the update scripts, stop the application server if it is running and execute Update Database from the CUBA main menu. If you want to re-create the database from scratch with the init scripts, execute Create Database.

5.2.4. Generating Data Model

Studio allows you to create the data model and standard UI screens for an existing database. Click CUBA > Advanced > Generate Model main menu item or select Project > Data Stores in the project tree and click Generate Model in the context menu. If you have several data stores, Studio shows a dialog where you should select one.

Then Studio opens the Generate Model from Database wizard.

Step 1

This is the first step of the model generation wizard.

generate model step1

Optional step: click Settings to set up a Java package where to create new entities, and default mappings for system attributes.

For example, if all or most of the tables in your database contain Modified and ModifiedBy columns, you can map them to Updatable.updateTs and Updatable.updatedBy attributes of created entities. In this case, you don’t need to map them individually for each table. Use Exclude columns from mapping list to not map certain columns automatically for all tables.

The wizard displays the list of tables that have no corresponding entities in the project’s data model. You can use the filter field above to find a table by its name.

Select tables that you want to map to the data model. Some tables depend on others through foreign keys, so when you select a table, all tables that it depends on are also become selected. If you deselect a table, all dependent tables become deselected too.

You can click on the checkbox on the right to select or deselect all available tables.

Click Next.

Step 2

At this step, you can review and edit automatically generated mappings for the selected tables.

generate model step2

The Status column describes the result of the automatic mapping:

  • OK - the automatic mapping was successful, and all columns are mapped to a new entity.

  • Join table - a link between entities is recognized and mapped as a many-to-many join table.

  • There are unmapped columns - some columns cannot be mapped to a new entity.

  • New PK will be created - the table has no primary key. A new PK of UUID type will be created.

  • Composite PK will be replaced - the table has a composite primary key, but no other tables reference it. The composite PK will be replaced by the primary key of UUID type.

  • Composite PK referenced by other tables - the table has a composite primary key and some tables reference it. Studio cannot map such table.

  • Unsupported PK type - the table has a primary key of an unsupported type. Studio cannot map such table.

  • Choose primary key for DB view - it’s a database view and you should select a column or a set of columns suitable for the entity identifier. In this case, click the Choose PK button and select columns for the primary key.

The Refresh mapping button allows you to re-launch automatic mapping for the selected table. For example, you can go to a database SQL tool, make some changes in the database schema, then return to the wizard and launch the mapping procedure again.

The Edit mapping button opens a dialog window with the mapping details. There you can change the entity name and the list of system interfaces implemented by the entity class. It will affect the number of system columns being created for compatibility with CUBA entities.

generate model step2 2

The Choose PK button appears instead of Edit mapping when a database view is selected and you need to select columns for the entity identifier.

By clicking Back, you can go to the previous step to select or deselect tables.

Click Next to go to the next step.

Step 3

At this step, you can specify what UI screens should be created for new entities.

generate model step3

If you deselect the Create standard screen checkbox, Studio will not generate UI for the new entities.

Use the In module, Package and Menu fields to specify where to place the screens source code and where to display them in the main menu.

Use the drop-down list in the Standard screens column to select what types of screens to generate.

You can safely skip this step and generate UI screens for your entities later after finishing the model generation process.

Click Next to go to the next step.

Step 4

This is the last step of the model generation wizard.

The Import scripts table contains the list of scripts that should be executed on the database to make it compliant with the entities being created.

Until this point, nothing is created in the project nor even saved to disk. Studio actually generates entities and screens and saves the scripts only when you press Run all scripts or Run script.

You can review and edit the scripts on this page, then run them or just save and run later by a database management tool. The import scripts are saved in the modules/core/db/import directory.

5.2.5. Integrating with Custom Database

As described in the documentation, the framework allows you to use any DBMS supported by EclipseLink ORM as your project database. And Studio can help you to create files required for such integration.

Select CUBA > Advanced > Define Custom Database in the menu.

The opened window allows you to set properties for a new custom database that you want to work with. Based on these properties, Studio will generate code to support the database both at design and run time.

  • DB type id - the identifier of the database type to use in the cuba.dbmsType application property.

  • DB type name - a user-friendly name of the database type to show in Studio.

After you click OK, Studio will generate Java classes in com.haulmont.cuba.core.sys.persistence and Groovy classes in{db_id} packages of your project. The sample auto-generated implementation is suitable for Microsoft SQLServer database. You should change it appropriately.

First, fix the{db_id}.{db_id}DbProperties class. When it is ready to fit your database, you will be able to switch your project to this database in Studio. Reopen the project to see your database in the Database type drop-down list.

In order to connect to your database at runtime, fix {db_id}DbmsFeatures and {db_id}DbTypeConverter classes of the com.haulmont.cuba.core.sys.persistence package. The {db_id}SequenceSupport class is used only for generating integer identifiers and unique numbers.

Finally, fix the{db_id}.{db_id}DdlGenerator class for correct generation of init and update database scripts by Studio, if needed. Skip this step if you don’t need to generate DDL scripts for this database.

If you use the custom database as a main data store, when you generate database scripts, Studio will create init scripts for all application components, including CUBA. These scripts won’t include some required initialization data, so you have to add the following to the Init data script of your project (30.create-db.sql):

values ('0fa2b1a5-1d68-4d69-9fbd-dff348347f93', current_timestamp, 0, 'Company', null)^

values ('60885987-1b61-4247-94c7-dff348347f93', current_timestamp, 0, 'admin', 'admin',
'Administrator', '0fa2b1a5-1d68-4d69-9fbd-dff348347f93', 1)^

values ('a405db59-e674-4f63-8afe-269dda788fe8', current_timestamp, 0, 'anonymous', 'anonymous', null,
'Anonymous', '0fa2b1a5-1d68-4d69-9fbd-dff348347f93', 1)^

5.3. Middleware

The project tree displays all your middleware services and managed beans in one place. In the sections below, we explain how to create new services and beans.

5.3.1. Creating Services

Services are container-managed components that form the middle tier boundary and provide the interface to the client tier. Services may contain the business logic themselves or delegate the execution to managed beans.

In order to create a new service, select the Middleware project tree section and click New > Service in the context menu:

create service

When you enter the name of the service interface, the corresponding bean name and the service name constant are generated automatically:

create service 2

After that, the service interface will be created in the global module, and its implementation - in the core module. Also, the new service will be automatically registered in web-spring.xml configuration file.

You can easily switch from the interface to service bean and back using the marker on the gutter:

service interface

As soon as you create a method in the service interface, Studio inspection will suggest you implementing it in the bean class:

service interface 2

5.3.2. Creating Managed Beans

Studio shows all managed beans of the middle tier (including entity and transaction listeners) in the Middleware > Beans section of the project tree.

studio beans

In order to create a managed bean, create a Java class by selecting a package in the project tree and clicking New > Java Class in the context menu. Then add the @Component annotation to the class as in the example above. To minimize the risk of name conflicts, especially if you are developing an application component, provide a name to the bean explicitly by specifying it in the annotation.

5.4. Generic UI

Studio provides a lot of features that facilitate working with Generic UI of your application.

In the project tree, you can find the following elements of Generic UI:

  • Web Menu opens the graphical editor of the main menu.

  • Main Message Pack section contains messages for main menu entries and common UI elements.

  • Screens section displays existing application screens.

  • Themes are used to manage the visual presentation of the application.

5.4.1. Creating and Removing Screens

To create a new Generic UI screen, select Generic UI in the project tree and click New > Screen in the context menu. If you want to create a CRUD screen for an entity, select this entity or one of its views in the project tree and click New > Screen in the context menu:

create screen

Studio will show a list of available templates. The list is divided into two sections: Screen Templates and Legacy Screen Templates. The former contains the templates for the new screen API available since framework version 7, while the latter contains templates for screens that can be used in projects based on version 6 too.

create screen 2

If you are creating the screen for an entity or view selected in the project tree, the Entity and Entity view fields will be filled automatically:

create screen 3

The Advanced section lets you modify the automatically generated descriptor and controller names and the screen id. It is useful when you have more than one screen for some entity.

When you click Finish, the screen XML descriptor and Java controller files are created and opened. For a legacy screen not annotated with UiDescriptor and/or @UiController annotation, its descriptor is registered in the web-screens.xml file.

When you remove screen files, use the Safe delete option to find and clean up references to this screen:

safe delete screen 1

Some references like usages in web-menu.xml and web-screens.xml files will be deleted automatically. If there are other references, you will see a dialog that shows these references. Click View Usages in the dialog, review the references in the Find tool window and click Cancel or Do Refactor:

safe delete screen 2

5.4.2. Working with Screen Descriptors

The screen XML descriptor editor contains two tabs at the bottom: Text and Designer. On the Text tab, you can edit the XML directly, while the Designer tab contains a visual editor of the screen layout.

xml descriptor

You can switch from the screen descriptor to its controller and back using the marker on the gutter or by selecting the descriptor in the project tree and clicking Go to controller in the context menu.

Studio inspects the screen layout for errors and inconsistency, checks the internal and external references. It will alert you with warnings or by highlighting XML elements in the following cases:

  • The screen layout cannot be assembled due to an XML error.

  • Components property paths and names do not correspond to the application data model.

  • Components size conflicts: conflicting width, height and expand attribute values.

  • dataContainer and dataLoader attributes don’t reference any existing data containers or data loaders.

  • Fields inside a form don’t define the property XML attribute explicitly: in this case, the id will be used as property implicitly.

  • The form element semantic error: fields are duplicated or located out of the column.

  • The number of columns in a gridLayout does not match the stated number.

  • Duplicated element attribute in an extended screen, when attributes are declared identically in both parent and extended screens.

  • Elements in an extended screen are named not like in parent screen or placed incorrectly.

  • messagesPack descriptor attribute does not belong to a valid package which contains at least one file.

  • Outdated XSD reference.

  • id values are not unique within the screen.

The inspections can be configured in the Settings window (CUBA > Settings > Editor > Inspections).

Studio intentions facilitate working with screen components. Use Alt+Insert (Cmd+N) to find out the features for working with particular UI and data components. For example, to add a new field to a Form component, you can move the cursor inside the form element and do one of the following:

  • Press Alt+Insert (Cmd+N), select Add field, then choose the property and the field tag,

    gui Form add
  • Type field and press TAB, then choose the property and the field tag.

    gui Form add tab

The Designer tab displays the visual designer which allows you to develop the screen layout and set UI components properties in WYSIWYG style.

xml descriptor 2

The designer workspace is divided into four panels:

  • Canvas is the workspace where you can arrange the components in the desired layout. Components can be resized and aligned using the controls:

    • expand horizontally,

    • expand vertically,

    • align the component vertically/horizontally.

  • The Palette panel displays the set of available screen component:

    • Containers;

    • Components;

    • Data components: containers and loaders;

    • Non-visual components: actions, dialog mode settings, timers.

In order to add a component to the layout, drag it from the palette onto the canvas or the hierarchy panel.

  • The Hierarchy panel displays the tree of components added to the layout. Elements of the tree can be rearranged using drag-and-drop, as sometimes this is more convenient than doing the same on the canvas. You can remove, copy, cut or paste an element in the hierarchy using its context menu opened by right-click.

  • The Properties panel displays visual component properties.

5.4.3. Working with Screen Controllers

This section describes the features that Studio provides for working with the source code of screen controllers.

Gutter icons enable quick switching to the corresponding XML descriptor, locating the XML definition of an injected component and other navigation options.

Dependency injection

Dependency injection is the main way of getting references to visual components and API endpoints in the screen controller code. Of course, you can write a field of the required type and annotate it manually, but Studio has a special window that allows you to select an object from the list and create the appropriate field automatically. This window is opened if you press Alt+Insert (Cmd+N) and select Inject…​ in the Generate popup menu:

controller injection

The following objects can be injected into controllers:

  • Visual and data components defined in the XML descriptor,

  • Screen API interfaces,

  • Infrastructure interfaces,

  • Middleware services,

  • Configuration interfaces.

Event handling

By creating event handlers, you can execute code at various points in the screen lifecycle and react to user actions. A handler is a controller method annotated with @Subscribe and having the event as a parameter. You can create such method in Studio if you press Alt+Insert (Cmd+N) and select Subscribe to Event in the Generate popup menu:

subscribe dialog

Each event in the window is provided with a description on the right which is extracted from the event’s Javadoc.

The following events are available in the opened window:

  • Controller events represent the lifecycle of the screen.

  • Components events allow you to react on buttons clicks, table selections, actions etc.

  • Frame events represent the lifecycle of the outer frame component of this screen.

  • Data context events allow you to react on the data context changes and execute code before and after data commit.

  • Data containers events enable receiving notifications on changes in the state of data containers and entities.


Using delegates, you can provide code that will be used by various screen mechanisms instead of their standard implementations. For example, you can provide your own function to commit data or to select icons for table rows.

A delegate is a controller method with a specific signature and annotated with @Install. You can create such method in Studio if you press Alt+Insert (Cmd+N) and select Install Delegate in the Generate popup menu:

install dialog

Each event in the window is provided with a description on the right which is extracted from the framework Javadocs.

5.4.4. Working with Application Menu

The menu designer allows you to define the application main menu and store it in the web-menu.xml configuration file. The Structure tab displays the graphical designer, the XML code of the menu can be edited on the Text tab.

web menu

The menu can be created in two modes:

  • In the Single mode the menu contains items from the project’s web-menu.xml file only. In this case you need to create all items, including those existing in the app components if necessary, but you have full control over the menu structure.

  • In the Composite mode the menu contains items from the project’s menu.xml plus from the menu configuration files of all application components. This mode helps to easily include all inherited items and insert the project’s specific items at any place of the menu structure. The inherited menu items can not be edited.

    Additionally, on the Text tab, you can define for the menu items the ìnsertBefore or insertAfter attribute. These attributes define where to insert the current item. These attributes help to combine the project menu items with the items inherited from the application components in the Composite mode.

    For example, if you want to place your menu structure to the left of the Administration item, set insertBefore="administration" for the root item of your hierarchy.

The list of menu configuration files is defined by the cuba.menuConfig application property, which is updated when you select the mode.

In order to add a menu item, select an existing item (or the configuration file to create a top-level item) and click +. The Menu item editor window will be opened in a modal window.

You can create the following types of menu items:

web menu create

A menu item which opens an application screen.

You should specify the following properties for a Screen item:

  • Screen - non-unique ID of screen that is opened by this menu item.

  • Id - an arbitrary unique ID of the item.

  • Open type - defines whether the screen should be opened in a new tab or in a modal window (NEW_TAB or DIALOG). NEW_TAB is used by default.

  • Shortcut - a keyboard shortcut which opens the screen. Possible modifiers (ALT, CTRL, SHIFT) are separated by a "-", for example ALT-C.

  • Style name - defines a style name for the menu item. See Themes for details.

web menu create 2

A menu item which contains other items (submenu).

You need to specify the following properties for a Menu item:

  • Id - an arbitrary unique ID of the item.

  • Style name - defines a style name for the menu item.

web menu create 3

A menu item which invokes a method of a managed bean.

You need to specify the following properties for a Bean item:

  • Id - an arbitrary unique ID of the item.

  • Bean - the name of bean which can be obtained by AppBeans (e.g. cuba_Messages).

  • Bean method - the name of method from bean to be invoked.

  • Shortcut - a keyboard shortcut which invokes the method. Possible modifiers (ALT, CTRL, SHIFT) are separated by a "-", for example ALT-C.

  • Style name - defines a style name for the menu item.

web menu create 4

A menu item which executes the run() method of a given class.

You need to specify the following properties for a Class item:

  • Id - an arbitrary unique ID of the item.

  • Class - a fully qualified name of class which extends Runnable.

  • Shortcut - a keyboard shortcut which invokes the method. Possible modifiers (ALT, CTRL, SHIFT) are separated by a "-", for example ALT-C.

  • Style name - defines a style name for the menu item.


A horizontal line separating menu items.

5.4.5. Working with Themes

Studio facilitates creation of theme extensions and custom themes in your project.

theme extension

When you create a theme extension or a custom theme, the special directory structure is created and the build.gradle file is modified.

The created themes will be displayed in the Themes section of the project tree.

halo ext

After extending or creating a theme, you can modify its variables manually in the SCSS file or in the visual editor: in the context menu of the new theme, select Open Variables File. This file can also be opened from CUBA main menu: select Advanced > Manage themes > Edit theme variables.

theme variables