Skyve 9 is a major platform update by the team. This release includes a number of significant changes and improvements to the Skyve platform, including several major version upgrades of the underlying libraries, a new role-based feature flag system, new view controls, data sensitivity controls, and a new version of the Flutter generator.

Most notably, this breaks backwards compatability by updating the minimum version of Java used by Skyve from 11 to 17 (Java 21 has been tested and is supported), and moving from Java EE 7 to Jakarta EE 10, which provides support for Wildfly application server versions after 26.

New role-based feature flags

Some additional flags have been added when defining roles in the customer configuration file. This allows for more granular control over the features available to users with different roles. Roles can now explicitly enable the ability to switch mode (switch between the desktop and responsive renderer), the ability to perform indexed text search and the ability to flag records.

<customer ...>
    ...
    <textSearchRoles>
        <role module="admin" name="BasicUser" />
    </textSearchRoles>
    <flagRoles>
        <role module="admin" name="BasicUser" />
    </flagRoles>
    <switchModeRoles>
        <role module="admin" name="BasicUser" />
    </switchModeRoles>
    <interceptors>
        ...
    </interceptors>
</customer>

These new permissions default to off. If you are upgrading an existing Skyve application to Skyve 9, and you have existing roles which require the ability to switch mode, perform text search or flag records, you will need to update your role definitions in each customer.xml.

Sidebar and collapsible form layouts

Skyve 9 adds some new widgets for specifying view layouts. A sidebar can now be defined which defines floating content which is always present as you scroll. Pixel breakpoints can be specified at which it automatically collapses on smaller screen widths. The width of the sidebar when open can also be defined.

<sidebar widgetId="sidebarWidget" floatingPixelWidthBreakpoint="1024" floatingPixelWidth="300" percentageWidth="40">
</sidebar>

An example of this in use can be seen in the whosin module Office edit view.

Forms, vboxes and hboxes can now be defined as collapsible. This allows the user to open and close the form, vbox or hbox to show or hide the content. The state of the collapsible is remembered for the session (PrimeFaces) or window object (SmartClient). When specified, the default value (open or closed) must be defined.

<form border="true" borderTitle="Building Details" responsiveWidth="12" collapsible="open">

An example of this in use can also be seen in the whosin module Officeedit view.

PrimeFaces 13

This should be a transparent upgrade for most existing projects, but PrimeFaces 13 adds support for Font Awesome 6 icons. Existing icon names may need some tweaking, see notes for upgrading.

Skyve project changes

The Skyve project has been modified to make it easier to run locally, and to deprecate support for being able to run as an ear, it is now a war only project.

• Add skyve-war module
• Removed skyve-ear module
• Deprecate skyve-ejb module
• Add skyve-quarkus (quarkus) module
• Add skyve-jar (executable jar with undertow and rest-easy)
• Add skyve-vue - vue3 project for ListGrid implementation

Dependencies

Many of the core dependencies used by Skyve were updated as a part of the Skyve 9 release. In addition to the minimum JDK version change, the H2 version change has implications for existing projects, see notes for upgrading.

• Jakarta EE 10 from Java EE 7 (adds support for Wildly > 26)
• Java 17 from 11 (also supports JRE 21)
• Spring 6.1.3
• Hibernate 5.6.15.Final
• SmartClient 13
• PrimeFaces 13.0.5
• Apache Tika 2.9.1
• Apache Lucene 9.7.0
• H2 - 2.2.220 (see notes for upgrading)
• Font-Awesome 6.5.1

Flutter

The Skyve Flutter generation was progressed as part of the Skyve 9 update. Documentation on how to generate a Flutter verison of a Skyve application will be documented in a future post.

• Generation improvements
• Form implementation and input validation
• Tabs and SliverAppBar
• Responsive layout implementation
• Support Font-Awesome 6.5.1 Icons

View

When viewing tabular data from a Skyve list menu, a new right-click option has been added which allows the user to open the record in a new browser tab. This is useful for comparing records side-by-side, or for copying data between records.

• ListGrid open in new browser tab menu option
  • Right-clicking on a row in a listGrid now provides the ability to "popout" the record into a new browser tab
• New collapsible attribute on vbox/hbox/form (see Sidebar and collapsible form layouts)
• New sidebar widget for floating content (see Sidebar and collapsible form layouts)
• Handle appending asterisks to required fields titles in ViewRenderer for SC and PF
• Upgrade Skyve to FontAwesome 6.5.1
  • The previous version of font-awesome can be uncommented in template xhtml files for icon backwards compatibility

Responsive Renderer

The layout of labels can now be changed to be on the side of the input (the default when not specified), or to be on the top of the input. This can be controlled by the formLabelLayout attribute on each module element in the customer.xml.

<customer ...>
    ...
    <modules homeModule="admin">
        <module name="admin" formLabelLayout="side" />
    </modules>
</customer>

Or can be specified at the individual form level:

<form labelLayout="top">
    ...
</form>

• Add blocking ajax UI to prevent multiple user actions over slow connections
• Fix ListModel parameter coercion
• Tweak editorial layout
• Version all theme resources URLs to prevent caching when upgrading theme versions
• Use flex-box for form item and form grid layouts
• Ensure process and update properties are set to default values for data grid add, remove and zoom buttons
• Changed the process attribute of the remote command invoked after the upload dialog is closed to the default processing scope instead of @none to enable unposted values to be reflected
• Responsive layout of device preview
• Add sessionId property to meta-data User object
• Add user session-scoped repository capability to DefaultRepository

Desktop Renderer

• Expose snapshot and tag tools/menu items for extension
• Fix UI switcher in Firefox

MetaData/Repository

• Validate all customers on startup and validate the current customer when in dev mode and metadata is changed
• Allow metadata/security data store queries to be overridden in ProvidedRepository
• Unconditionally validate domain against H2 reserved words since it is the default unit test database
• Add StringFormatter for sanitisation and escaping Skyve expressions
  • RelaxedHTML, RelaxedEscapedHTML, SimpleHTML, SimpleEscapedHTML, BasicHTML, BasicEscapedHTML, TextHTML, TextEscapedHTML, EscapedHTML, EscapedJSONString, EscapedJSString
• Update TextValidator credit card regular expression to allow 15 digits for Amex
• Add validation to ensure conditions and attributes conform to Java property name spec
• Add URL decoding of schema/common.xsd URL to handle spaces and punctuation encoded by ClassLoader.getResource()
• Add null safety to Repository interfaces and implementations
• Check attribute and condition names are valid Java property identifiers and check for duplicate attribute/condition names after this check
• Add Binder.validateBinding() used by expression validation and gen domain validation
• Add validation of collection ordering “by” attribute binding to gen domain
• Allow implicit bindings in chart category bindings
• Check that order by bindings in collections are scalar (as they need to be SQL orderings, if simple bindings)
• Validate Collection ordered and ordering are mutually exclusive
• Add extra hints about gen domain or compilation problems to hibernate related and class loading exceptions when in dev mode
• Add Attribute.isScalar() helper method
• Enable view models to be used and validated at generate time
• Validate DynamicImages separately from other view models when validating accesses
• Remove Decimal2TwoDecimalPlacesPercentage as it cannot store 4 decimal places in the data store

Behaviour

• Load BrowsCap and warm metadata asynchronously post deployment to improve startup time
• Add support for public (not-logged in user) uploads
• Allow public (not-logged in user) downloads
• Allow public access to CustomerResourceServlet
• Use non-pooled connections and local package H2 for H2 embedded to support spatial queries
• Change the default unit test engine from JUnit 4 to JUnit 5
  • Rename AbstractH2Test to AbstractH2TestForJUnit4
  • Rename AbstractH2TestForJUnit5 to AbstractH2Test
• Place common test functions in InternalBaseH2Test
• Fix unique constraint checking on inserts in the Data Stores
  • Inserts temporary SHA256 hashes to allow DB locking between transactions (ie gap locking)
  • Respects unique constraint scope
• Add system monitoring data through JVM to /health endpoint
• Replace Persistence.setDocumentPermissionScopes() and Persistence.resetDocumentPermissionScopes() with Persistence.withDocumentPermissionScopes() functional method
• Add concurrent read/write locking to MutableCachedRepository
• Add state.directory property for cache folder that can be set outside of the content directory but defaults to <content.directory>/SKYVE_CACHE/
• Add backup.directory property for backup folder that can be set outside of the content directory but defaults to <content.directory>/
• Add User.getContactAvatarInitials()
• Falsey EL boolean evaluation in Skyve expressions (eg null == false)
• Add driver and CCM definitions in skyve-war/javaee/
• Add MySQL bug fix for determining type and length of DB fields in MySQL spatial dialects
• Maven Assemble now includes jboss-deployment-structure.xml for freemarker CSS processing in itext

Security

Skyve 9 now provides the ability to specify the sensitivity of attributes. This serves two initial purposes, one is as a way to document and capture the data sensitivity at the metadata-level within the application, and the second purpose is part of the backup implementation within Skyve 9. Sensitive attributes can now be obfuscated during backup, allowing non-production systems to easily have a redacted copy of data.

• Bolster user access and document permission security
• Add report, dynamicImage and content access control
• Add textSearchRoles, flagRoles, switchModeRoles to customer metadata (see New role-based feature flags)
• Redacted data backup based on attribute sensitivity
• Add UTF8 character encoding to all server output
• Log all Servlet activity in the filter and configure by prefix exclusion (of static resources)
• Only process accesses from modules the user has a menu for and only process role accesses for roles the user has
• Prevent import of report templates that contain SQL datasets in multi-tenant applications for Freemarker reports
• Redirect to web.xml error pages on SecurityException in Faces AJAX requests.
• Ensure a conversation belongs to the current user’s session when reinstated
• Ensure error.jsp has appropriate security headers applied when forwarded to by web container error processing

Admin

• Add captcha during registration as part of Skyve's built-in self-registration
• Ability to easily re-run a completed job
• Add reorder snapshots function
• Upgrade admin module icons to use FontAwesome 6.5.1
• Include/exclude content and/or audits from backup
• Set the default minimum password configuration to 12 with upper lower and numeric, no special
• Add data sensitivity config to admin module
• Backup embedded associations correctly
• Check length on auditBizKey in RDBMSAuditInterceptor
• Add child collection, embedded association and hierarchical support to BizPort and default to xlsx format
• Moved ModulesUtil bizport methods to EXT

Notes for Upgrading

To upgrade your Skyve project to this version, change the Skyve version in your pom.xml to 9.0.0 and perform an assemble.

If you are upgrading from a version older than 8.3.0, please see the previous release notes and also apply those changes.

See the complete upgrade instructions on GitHub.

This is a major upgrade to the Skyve platform, and is not backwards compatible with existing installations. Please read through and all the notes below carefully, and apply any changes that are applicable to your system.

Upgrade Java JDK version

Upgrade your installation of Java version to 17 or later for both local development and production systems. Skyve 9.0.0 is built with Java 17 and is not compatible with earlier versions of Java. After downloading and installing, you may need to update your IDE preferences to make use of the new version. You will also need to update your project pom.xml to reference the new version of Java in the maven-compiler-plugin. Note the source and target version below:

<build>
    <finalName>$</finalName>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                </configuration>
            </plugin>

Also change the Skyve dependency library name from skyve-ee to skyve-web, and remove the javaee-api dependency if it is included.

<dependencies>
        <dependency>
            <groupId>org.skyve</groupId>
            <artifactId>skyve-web</artifactId>
            <version>$</version>
        </dependency>

In many cases it may be easier to update your existing project pom.xml and then re-apply your customisations back. Please click the button below to start with an updated pom.xml template for Skyve 9 projects.

Create a new jboss-deployment-structure.xml file within src/main/webapp/WEB-INF/ to make the CSS library available to Wildfly for Freemarker reprots to continue to work under Java 17:

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.1">
    <deployment>
        <dependencies>
            <system export="true">
                <paths>
                    <path name="org/w3c/dom/css" />
                </paths>
            </system>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

Upgrade Wildfly application server version

In order to use Skyve 9 with Wildfly application server, please upgrade Wildfly to 27.0.0.Final or later. Skyve 9.0.0 uses the Jarkarta namespace and is not compatible with earlier versions of Wildfly.

Update H2 data source connections

Critical: If you are using H2, you must make a Skyve backup of your application before upgrading, as the version of H2 in Skyve 9.0.0 is not backwards compatible with previous versions.

Your ds.xml file for H2 connections will no longer be used, the connection will need to be specified as part of your application json configuration file:

// Datastore definitions
    "dataStores": {
        // Skyve data store
        "skyve": {
            // Connection
            "driver": "org.h2.Driver",
            "url": "jdbc:h2:file:~/content/skyve/skyve;IFEXISTS=FALSE;IGNORECASE=TRUE;AUTO_SERVER=TRUE",
            "user": "sa",
            "password": "sa",
            // Dialect
            "dialect": "org.skyve.impl.persistence.hibernate.dialect.H2SpatialDialect",
            // Timeout for data store connections employed in general UI/forms processing - 0 indicates no timeout
            "oltpConnectionTimeoutInSeconds": 30,
            // Timeout for data store connections employed when running jobs and background tasks - 0 indicates no timeout
            "asyncConnectionTimeoutInSeconds": 300
        }

Note: remove the JNDI definition from the dataStore definition for H2, it is no longer required and will cause your application to not deploy if it is left in.

Additionally, if you are using Skyve Foundry to deploy your application, you will also need to update the docker/h2/projectName.json file to reflect the new connection details:

// Datastore definitions
    "dataStores": {
        // Skyve data store
        "skyve": {
            // Connection
            "driver": "org.h2.Driver",
            "url": "$",
            "user": "$",
            "password": "$",
            // Dialect
            "dialect": "$",
            // Timeout for data store connections employed in general UI/forms processing - 0 indicates no timeout
            "oltpConnectionTimeoutInSeconds": 30,
            // Timeout for data store connections employed when running jobs and background tasks - 0 indicates no timeout
            "asyncConnectionTimeoutInSeconds": 300
        }

Update Skyve content zip and recreate existing content index

The skyve-content zip contains new libraries versions upgraded by the security uplift. After assembling, replace your existing skyve-content-x.x.x.zip in your project with the new skyve-content-9.0.0.zip. The latest content zip can be obtained by running a maven install against your Skyve 9 project (prior to deployment).

Important: As part of the library uplift, the existing content index needs to be deleted and recreated.

1. From your project content directory, delete the SKYVE_CONTENT folder (not SKYVE_STORE).
2. Login to your application as an administrator
3. Switch to Desktop mode
4. Select Admin -> Data Maintenance menu item
5. Select Content tab
6. Click the Reindex button to kick off a reindex of data and content

Upgrade premium themes

As part of the PrimeFaces version change, any premium themes installed in your Skyve application will need to be upgraded to the latest version (>= 7.0.0).

For example, to upgrade a project using the Ecuador theme:

1. Login to the PrimeTek store and download the latest version of the Ecuador theme.
2. Extract the zip file
3. delete primefaces-ecuador.taglib.xml from src/main/webapp/WEB-INF/ if present in your project, it is no longer required
4. in WEB-INF/lib, replace the previous version jar with the 7.0.0-jakarta jar from the extracted zip file
5. delete any existing ecuador-layout from WEB-INF/resources and replace it with the new ecuador-layout from the extracted zip file
6. delete any existing sass from WEB-INF/resources and replace it with the new sass from the extracted zip file
7. recompile any custom theme and layout CSS files from the new SASS files in the extracted zip file

Update application icons

If you are making use of icons in your Skyve application, they will also need to be updated as Skyve 9 has deprecated FontAwesome 4.7 that was previously in use and moved to 6.5.1. The new version of FontAwesome is not backwards compatible with the old version. You can find the new icons at FontAwesome.

For example, where referencing an outline icon (*-o), this typically becomes fa-regular iconName without the -o, but some have been renamed. Solid icons in 4.7 typically become fa-solid iconName. For example:

4.7: fa fa-floppy-o
6.5: fa-regular fa-floppy-disk

4.7: fa fa-user-circle
6.5: fa-solid fa-circle-user

The Skyve admin module has been updated to use the new FontAwesome 6 icons, but you can uncomment the FontAwesome 4.7 css in the template.xhtml for your project theme if you need to use the old icons.

Update annotations

javax annotations have been replaced with jakarta annotations in Skyve 9.0.0 as part of the new version of Java required. Replace all instances of:

import javax.enterprise.inject.Default;
import javax.inject.Inject;

with

import jakarta.enterprise.inject.Default;
import jakarta.inject.Inject;

In addition, managed beans should be named with @Named, as the javax.faces.bean.ManagedBean annotation has been removed in Jakarta EE 10. Replace all instances of:

import javax.faces.bean.ManagedBean;
import javax.faces.bean.ViewScoped;

with

import jakarta.inject.Named;
import jakarta.faces.view.ViewScoped;

e.g. @ManagedBean(name = "myView") becomes @Named("myView").

Update module role permissions

If any existing users require the ability to switch mode, flag records or perform indexed text search, at least one role will need to have the permissions added in the customer.xml.

Update privelege escalations

Instead of wrapping query privelege escalations in a try / finally block, these are now provided by Persistence.withDocumentPermissionScopes(). Two variants have been added, one for Function and one for Consumer.

Functional variant:

return CORE.getPersistence().withDocumentPermissionScopes(DocumentPermissionScope.customer, p -> {
            DocumentQuery q = p.newDocumentQuery(Audit.MODULE_NAME, Audit.DOCUMENT_NAME);
            q.getFilter().addGreaterThan(Audit.millisPropertyName, UserDashboardExtension.TWO_WEEKS_AGO);

            ChartBuilder cb = new ChartBuilder();
            cb.with(q);
            cb.category(Audit.auditDocumentNamePropertyName);
            cb.value(Bean.DOCUMENT_ID, AggregateFunction.Count);
            cb.top(6, OrderBy.category, SortDirection.ascending, true);
            cb.orderBy(OrderBy.category, SortDirection.ascending);
            
            return cb.build("System activity by context - last 14 days","Context");
        });

See UserDashboardExtension#createFavourites() for an example of the consumer variant.

And there are some new newInstance methods to increase the scope when extending SingletonBizlet or SingletonCachedBizlet:

@Override
    public ConfigurationExtension newInstance(ConfigurationExtension bean) throws Exception {
        // temporarily elevate access to find existing configuration regardless of user
        return newInstance(bean, DocumentPermissionScope.customer);
    }

Update JUnit 5 from 4

The default test runner has been updated to use JUnit 5 instead of 4 from Skyve 9 onwards. Update the test dependencies within your pom.xml to remove any existing imports for JUnit 4, and update the JUnit 5 dependencies:

<dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter-engine</artifactId>
            <version>5.10.2</version>
             <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>org.junit.vintage</groupId>
             <artifactId>junit-vintage-engine</artifactId>
            <version>5.10.2</version>
             <scope>test</scope>
         </dependency>

There is a new base unit runner (InternalBaseH2Test) inherited by AbstractH2Test (now JUnit 5) and AbstractH2TestForJUnit4. The customer specified must be changed to the customer specified in your project's src/main/java/customers or the tests extending the base test classes will all fail. This will be fixed in Skyve 9.0.1.

Update list models

Override and migrate any logic from the constructor into the postConstruct method, and remove the constructor. See BatchesModel in the admin module for an example.

If access to Skyve persistence is required, it must be wrapped in a runtime check as shown below.

@Override
    public void postConstruct(Customer customer, boolean runtime) {
        if (runtime) {
            Persistence p = CORE.getPersistence();
            ...
        }
    }

Update Azure SDK version

If you are using Azure for cloud backups in your application, you will need to update the Azure SDK version in your pom.xml to 12.25.2, and the groupId is now com.azure.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>12.25.2</version>
</dependency>

Restoring previous backups

Backups made prior to Skyve 9 will not restore unless the ADM_UserMonthlyHits.csv is updated or removed from the backup zip. The year and month columns are now hitYear and hitMonth.