There a 2 scenarios that developers need to consider when publishing a new version of an application:

1. A new application version is published that utilizes new features that aren’t supported on the client version that is installed by one or more end users.

2. A new application version is published, but end users have existing open sessions started from a prior application version. In this scenario, if a breaking change was introduced it is possible that session data could be come corrupt or cause other issues with the application.

Handling New Client Features

The compatibility version is a tool that allows you to understand and compare feature compatibility between different components of the Skylight platform. When new features are released, the compatibility version number is bumped. The Compatibility Version Feature Matrix tracks which features are included for each compatibility version. The Release Notes for each client also document which compatibility version they support.

Checking the Compatibility Version in Application Builder

To view the compatibility version of an application in Application Builder, select the Application page on the sidebar. You can view the compatibility version in the Info section.

Accessing Compatibility Versions in Event Scripts

The application.compatibilityVersion property returns the compatibility version of the currently loaded application.

The environment.application.compatibilityVersion property returns the compatibility version of the client.

You can query these properties in an event script to check if there is a compatibility difference between the application and client, and if necessary, handle with logic. For example, you could:

• Present a non-blocking notification to the user recommending that they upgrade their client.

• Present a view that blocks the user until they upgrade their client.

• Display an entirely different view that doesn't utilize the new feature.

Handling Open Sessions

When publishing a new version of an application there is a possibility that if a user has an existing session (that was started with the prior version of the application) with the new version, that it could corrupt the session or cause other issues with the application. Application Builder provides you with tools to manage application upgrades.

Application Upgrade Behavior

To configure the application upgrade behavior in Application Builder, select the Application page on the sidebar, and then select Upgrade.

You can choose between 2 upgrade options:

• Optional (default): Presents a dialog that allows the user to choose between upgrading immediately or wait until the next time the application is opened.

• Forced: Presents a dialog that an upgrade is required and forces the user to upgrade.

Application Upgrade Event Script

The applicationUpgrade event script triggers on the first time that a new version of an application is opened and every time a draft version is opened on a client. This gives you the opportunity to handle existing open sessions that may causes issues with the application. For example, you could:

• Close an old session

• Migrate the session data to support a new data model in the new application version

To edit the applicationUpgrade script in Application Builder, select Edit Script on the application upgrade settings page (shown above), or select File > Application Scripts > applicationUpgrade.

​