This document highlights major changes in CUBA Platform and Studio version 6.8.


Known Issues

  • The initial implementation of Entity Attribute Access Control handlers as Spring application event listeners caused a number of issues (see for example this and this). In version 6.8.1, we have introduced a new recommended way of defining such handlers. See documentation for details.

Breaking Changes

  1. The build system requires Gradle 4.3.1 or above. If you are using Studio, it will create a corresponding Gradle wrapper in your project on first opening.

  2. The login process and some mechanisms of the Web Client have been changed significantly.

    • Removed AbstractConnection, DefaultConnection classes.

    • Removed cuba-web-auth artifact.

    • The App and Connection beans now must have vaadin scope in Spring context.

    • The cuba.web.externalAuthenticationProviderClass application property is set to com.haulmont.cuba.web.auth.NoOpAuthProvider by default. If you use LDAP authentication, you have to enable it explicitly using cuba.web.ldap.enabled property.

    • Deprecated CubaAuthProvider interface - use LoginProvider and HttpRequestFilter beans instead.

    • Deprecated application properties: cuba.web.externalAuthentication, cuba.web.externalAuthenticationProviderClass.

    Please note that the old LdapAuthProvider and IdpAuthProvider settings should work as before.

    See documentation for details.

  3. AuthenticationManager uses separate session with user "server" for authenticate and login processing. This server session is instantiated directly without login procedure. See details in the issue.

  4. UserSessionsAPI has been changed; now it contains two sets of methods for obtaining a session by id:

    • get() and getNN() do not refresh the session last request timestamp in the cache (i.e. do not prolong the session)

    • getAndRefresh() refreshes the session in the cache, and optionally propagates the last request timestamp to the cluster.

    So now if you get a session directly from UserSessionsAPI, you have to explicitly decide whether these operation should prolong the session life in the cache (normally you don’t need it).

  5. A user password is required even if you use LDAP authentication. You can disable this using cuba.web.requirePasswordForNewUsers application property.

  6. DOM of the Label component with an assigned icon has been changed, so if you have some custom CSS, you may need to adjust it appropriately.

    DOM before:

    <div class="v-widget v-has-caption v-caption-on-top">
        <div class="v-caption v-caption-icon v-caption-c-label-caption-on-left" id="gwt-uid-3" for="gwt-uid-4">
            <span class="v-icon FontAwesome"></span>
        <div class="v-label v-widget icon v-label-icon c-label-caption-on-left v-label-c-label-caption-on-left v-label-undef-w v-label-empty" id="gwt-uid-4" aria-labelledby="gwt-uid-3">Label</div>

    DOM now:

    <div class="v-label v-widget icon v-label-icon v-label-undef-w">
        <span class="v-icon FontAwesome"></span>Label
  7. In order to reduce size of CUBA applications using the Full-Text Search premium add-on, the following dependencies were removed:

    group: 'edu.ucar', module: 'netcdf4'
    group: 'edu.ucar', module: 'grib'
    group: 'edu.ucar', module: 'cdm'
    group: 'edu.ucar', module: 'httpservices'
    group: 'com.github.junrar', module: 'junrar'
    group: 'edu.usc.ir', module: 'sentiment-analysis-parser'
    group: 'org.apache.cxf', module: 'cxf-rt-rs-client'
    group: 'org.apache.sis.core', module: 'sis-utility'
    group: 'org.apache.sis.core', module: 'sis-metadata'
    group: 'org.apache.sis.storage', module: 'sis-netcdf'
    group: 'org.gagravarr', module: 'vorbis-java-tika'
    group: 'org.gagravarr', module: 'vorbis-java-core'
    group: 'org.opengis', module: 'geoapi'
    group: 'com.healthmarketscience.jackcess', module: 'jackcess'
    group: 'com.healthmarketscience.jackcess', module: 'jackcess-encrypt'
    group: 'org.tallison', module: 'jmatio'
    group: 'org.codelibs', module: 'jhighlight'
    group: 'com.pff', module: 'java-libpst'
    group: 'org.apache.opennlp', module: 'opennlp-tools'
    group: 'com.rometools', module: 'rome'
    group: 'com.googlecode.mp4parser', module: 'isoparser'
    group: 'org.bouncycastle', module: 'bcmail-jdk15on'
    group: 'org.bouncycastle', module: 'bcprov-jdk15on'

    If you are experiencing any problem with indexing files of specific formats, try to add some of these dependencies to your project.

  8. The CATALINA_HOME and CATALINA_BASE global environment variables are not used by the Tomcat installed by Studio and setupTomcat Gradle task. So if you deploy your application by copying Tomcat from the development environment and rely on these variables in production environment, edit catalina.sh or catalina.bat scripts and remove the commands right after the CUBA comment.

  9. In the ProcInstance entity of the BPM module the entityId field of the UUID datatype was replaced with the entity field of the ReferenceToEntity type. This will break JPQL queries that use the entityId field. For example, the following query:

    select pi from bpm$ProcInstance pi where pi.entityId = :entityId

    should be transformed to the:

    select pi from bpm$ProcInstance pi where pi.entity.entityId = :entityId

    This modification was made to support references to entities that have primary keys with non-UUID types. For example, in case of referenced entity with String primary key, a reference to such entity in JPQL query should be defined this way:

    select pi from bpm$ProcInstance pi where pi.entity.stringEntityId = :entityId

    Along with entityId and stringEntityId fields a ReferenceToEntity entity has other properties: intEntityId and longEntityId.

Data Model

Generation of Integer Identifiers

In the previous versions, the Metadata.create() method assigned Long and Integer identifiers only to entities from the main data store. Now identifiers are assigned to all persistent entities inherited from BaseLongIdEntity and BaseIntegerIdEntity. The new identifiers are fetched from automatically created database sequences. By default, the sequences are created in the main data store. However, if the cuba.useEntityDataStoreForIdSequence application property is set to true, sequences are created in the data store the entity belongs to.

Generic UI

Context Help Icons

Introduced new attributes for UI fields: contextHelpText, contextHelpTextHtmlEnabled. If contextHelpText is set, then a special ? icon will be added for a field. If the field has an external caption, i.e. either caption or icon attribute is set, then the context help icon will be displayed next to the caption text, otherwise next to the field itself.

In the Web Client the context help tooltip appears when the users hovers over the ? icon, in the Desktop Client the user has to click on the ? icon to see the tooltip.

See details in the documentation

Icon Sets

Icon sets allow you to decouple usage of icons in visual components from real paths to images in theme or font element constants. They also simplify overriding of icons used in the UI inherited from application components. See details in the documentation.

Default Screen

We have added a number of application properties to manage a default screen opening after login. It can be the same screen for all users, or users can choose for themselves. Also, there is an option for disabling close button on such screen. See details in the issue.

Default Filter

A default filter is the one that is selected automatically when the screen is opened. You can now assign a default filter for all users - see Global default checkbox on the filter editor dialog:

gui filter editor

The Default for me checkbox makes the filter default for the current user. It has a higher priority then the global default.

Pluggable Component Factories

The pluggable component factories mechanism extends the standard component creation procedure and allows you to create different edit fields in FieldGroup, Table and DataGrid. It means that application components or your project itself can provide custom strategies that will create non-standard components and/or support custom data types. See details in the documentation.

SuggestionField Options

SuggestionField can work not only with entities, but also with strings or enum values. See examples in the documentation.

Polymer UI

Polymer 2.0 Class-based Templates

Studio now generates Polymer UI components which use class-based syntax instead of Polymer factory method:

  /** * @extends {Polymer.Element} */
  class MyappLocaleSelect extends Polymer.Element {
    static get is() {
      return 'myapp-locale-select';

    static get properties() {
      return {
        locale: {
          type: String,
          value: function () {
            return cuba.getApp().locale;

  customElements.define(MyappLocaleSelect.is, MyappLocaleSelect);

Improved Login Form Style

The login form generated by Studio has more sophisticated design now:

polymer ui login

Running "polymer serve" from Studio

Now in order to run native Polymer development server - polymer serve, you do not need to have Node.js installed locally. Studio allows you to do it from UI using project’s node and polymer-cli. Use Run > Start "polymer serve" item in the main menu:

studio polymer serve

Watch the console output for the URL server is launched at:

studio polymer serve address

Specify absolute api-url in index.html in case of using polymer serve.


Refresh Token

When you request an OAuth token, now by default you get a JSON object with two tokens: access_token and refresh_token. The latter cannot be used for accessing protected resources, but it has a longer lifetime than the access token and it can be used to obtain new access token when the current one is expired. See details in the documentation.


HSQL Database Migration Issue

In case of migrating the project with BPM module and HSQL database from the release 6.7, database update scripts errors may occur. To prevent it, perform a migration according to the next instruction:

  1. Change the platform version to the latest one available for the release 6.7 (6.7.8+).

  2. Run the Update database command in Studio.

  3. Execute the Generate DB scrips command in Studio. Studio will generate the following script:

    alter table BPM_PROC_INSTANCE drop column STRING_ENTITY_ID__UNUSED cascade ;
    alter table BPM_PROC_INSTANCE drop column INT_ENTITY_ID__UNUSED cascade ;
    alter table BPM_PROC_INSTANCE drop column LONG_ENTITY_ID__UNUSED cascade ;
  4. Apply the script.

  5. Only after that change the platform version to 6.8


Application Lifecycle Events

The application events mechanism can now be used for registering listeners notified after full initialization and before termination of the application. It can be used instead of adding listeners by the AppContext.addListener() static method. See the documentation for details.

Dynamic Attributes in Entity Log

Entity Log can now track changes in dynamic attributes of an entity.

Updated Dependencies


com.fasterxml.jackson = 2.9.2
com.thoughtworks.xstream/xstream = 1.4.10
com.vaadin = 7.7.13.cuba.2
org.hibernate/hibernate-validator = 5.4.2.Final
org.springframework = 4.3.12.RELEASE
org.thymeleaf = 3.0.8.RELEASE
tomcat = 8.5.23


Node.js 8.9.1 (LTS)


Known Issues

If you use in-place update in Studio SE on macOS, it will completely replace your application folder. If you previously added some JDBC drivers to /Applications/Cuba Studio SE.app/Contents/Resources/app/studio/lib, they will be lost and you have to add them again.

New Features Confirmation

Sometimes, new features which we introduce in new versions of Studio affect your existing projects. At the same time they are often optional, i.e. you can continue working with the project without them. An example of such feature is the generation of index on a foreign key in a one-to-one relationship, introduced in this release. On one hand, it’s a useful improvement, on the other hand it will generate additional update scripts and may be not needed for your project. So when you open an existing project in the new Studio, you will see a dialog asking you whether you want to enable the new feature for this project:

studio new func

If you select Enable or Disable, your decision will be saved in project’s studio-settings.xml. If you are not sure at the moment, select Ask me later and Studio will ask you again next time you open this project.

Theme Variables Editor

This editor enables managing variables which are used to quickly customize a Generic UI theme. It is available via the Manage theme > Edit Halo theme variables link on the Project properties tab. The link becomes active if you have created a theme extension in your project.

studio theme variables

Application Properties Editor

This editor allows you to edit application properties manually. Later we are going to add code completion and validation to it.

studio app props

Build Scripts

In the previous Studio version, when you changed the module prefix (which is app by default), Studio completely rewrote build.gradle and settings.gradle, which might cause the loss of a custom code in these files. In the new version, when you create a new project, its build scripts have the modulePrefix variable, which is used instead of string literals. Thus, when you need to change the module prefix, Studio simply replaces the value of this variable and doesn’t rewrite the whole file. For an old project which doesn’t have such variable, rewriting is still needed, but it happens only once, and after that the variable is added to the scripts.

Gradle Versions

As you know, Studio can work with projects based on different platform versions. These projects can also require different versions of Gradle, which are specified for the project’s Gradle wrapper in gradle/wrapper/gradle-wrapper.properties. Now Studio determines which version of Gradle is required when opening the project, and downloads it if it is not yet cached locally. When downloading and installing Gradle, Studio shows a modal window.

Import Project from Git

The Import project dialog allows you to import a project directly from a Git repository, if it doesn’t require authentication. Select Git option, enter a URL and select a local directory where to create the project. Studio will clone the repository and immediately open the project.

studio git import

Project Artifact Version

The Advanced tab of the Project properties page now contains the Artifact section which allows you to set the project artifact version. If the Snapshot checkbox is selected, artifact names will have the SNAPSHOT suffix.

The version parameter is stored in the build.gradle file in the cuba.artifact section. This section also specifies the artifact group, but we don’t provide an option to change it in UI because by convention the artifact group must be equal to the project root package.

studio artifact version

Database Scripts for Application Components

If your project uses an application component, there is a chance that the component does not contain database initialization scripts for your database. For example, if the component was developed on HSQLDB and you are using PostgreSQL. In such case Studio generates scripts for the component and shows them on the Init component tables and Init component constraints tabs of the Database scripts page:

studio comp db scripts

Safe Database Updates

Now Studio generates more safe update scripts when you remove an entity, an attribute, or change an attribute’s datatype. Such scripts are split to two parts: in the first part, the column or table is renamed to *__UNUSED, and in the second part these objects are actually dropped. In the example below, the foo attribute was removed from the Customer entity. The first script renames the column:

studio no removal 1

The second script drops it:

studio no removal 2

As you can see, the script containing DROP statement is highlighted in red to emphasize the fact that you can lose some data.

Additionally, we have added an ability to exclude scripts from automatic execution, but still have them in the project to be able to execute manually when needed. If you click the Exclude selected button, you will have an option to move the script to a special directory: modules/core/db/update-manually. The script will not be executed automatically, so the FOO__UNUSED column will remain in the table, but you will be able to execute the script manually and drop the column later.

Support for Custom Databases (experimental)

At the moment, the platform and Studio supports a limited number of databases out-of-the-box. These are HSQL, PostgreSQL, Microsoft SQL Server, MySQL and Oracle. But now you have an ability to implement support for a different DBMS right in your project.

This feature works in the following way:

  • You click Custom database link on the Project properties panel and enter ID and user-friendly name of your database type, e.g. firebird and Firebird.

  • Studio generates two sets of files in the core module of your project:

    • In the com.haulmont.cuba.core.sys.persistence package, implementations of the DbmsFeatures, DbTypeConverter and SequenceSupport interfaces of the platform. These implementations will be used by the application at runtime.

    • In the com.haulmont.studio.db.{db_id} package, files that will be used by Studio at design time:

      • {db_id}DbProperties, which defines database properties that are needed to configure projects using the custom database.

      • {db_id}DdlGenerator, which is used by Studio for generation of database init and update scripts and for creating model from an existing database.

  • All these files contain sample code suitable for Microsoft SQL Server 2012. You should fix the generated files to conform to your database properties, SQL and DDL statements.

  • After that, you can switch your project to use the custom database. It will appear in the Project properties > Database type list after you reopen the project.

  • 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 (as described above), including CUBA. These scripts won’t include some required initialization data, so you have to add it 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)^

Please keep in mind that this is an experimental feature and its implementation can be changed significantly in the future versions of Studio. This is especially relevant to the {db_id}DdlGenerator class, which is not clear and convenient enough at the moment.

. . .