23 Manage Runtime Dependencies for Visual Applications

In Visual Builder, runtime dependencies refer to a set of client-side libraries that, along with the accompanying version of Oracle JET, determine features and other improvements available to your visual application, like what JET components you can use.

To see what the runtime dependencies are for your visual app, click Menu in the upper right corner, then select Settings:

A visual app's runtime dependency comprises three values:

• Release: The latest certified combination of Visual Builder Runtime and JET within a major release, such as 24.04, 24.01, or 23.10.
• Visual Builder Runtime Version: A set of client-side libraries hosted on a Content Delivery Network (CDN). These libraries help the constituent files in your app talk to each other at runtime. For example, when you include a component (like a button) from the Component Palette in your app, the code for that component is stored in your app’s HTML file. If you then add an action chain to that button to navigate to a new page, the action chain code is stored in your app’s JSON metadata file. At runtime, the Visual Builder Runtime enables the HTML, JSON, and other dependent files in your app to communicate with each other, so that your app behaves as intended.
• Oracle JET Version: A JET release hosted on CDN. Each Visual Builder Runtime Version is certified to be compatible with one or more JET versions. If you’d like to see what’s in the latest JET release before deciding to upgrade, go to JET Release Notes and select the JET version stated on the Settings page.

Runtime dependencies are set for a visual application as a whole; you can’t set different versions for individual web (or mobile) apps within the visual app.

When you create a new visual app, Visual Builder automatically sets your runtime dependencies to the latest Visual Builder Runtime and JET versions. If you’ve already staged or published an app, however, it’s up to you to decide when to upgrade, as long as you do so within a certain time period. As a general rule, the Designer supports applications built on the current Runtime Version, as well as the three previous versions. So for 24.04, for example, the Designer supports not only the 24.04 Runtime Version, but also apps built with 24.01, 23.10, and 23.07. Once 24.07 comes out, however, support for the 23.07 Runtime Version will drop off, so we'll ask you to upgrade those apps before you can work on them in the Designer. If you choose not to upgrade at that time, you run the risk that newer browser versions will break your app. You also won’t be able to take advantage of any important security and performance improvements. For all of these reasons, we encourage you to build time into your development cycle to keep abreast of current changes, and to make sure you upgrade your app (you should version it first) before support for your current runtime version expires.

Upgrade Your App

If you see a banner in the header telling you to upgrade your runtime dependencies, here's what to do:

1. Click Oracle Visual Builder in the top left corner to return to the list of visual applications.
2. On the row pertaining to your app, click the hamburger menu to display the list of actions.
3. Click New Version:
   
   Description of the illustration newversion.png
   
4. In the New Application Version dialog, enter a new version for your app, then click Create.
5. On the list of visual applications, click your app to re-open it in the Designer.
6. In the banner, click Upgrade.
7. In the Upgrade Runtime Dependency dialog, choose the release you want to move up to, then click Upgrade:
   
   
   
   

Note:

You don't have to wait until you see a message to upgrade your app. If the Upgrade button under Runtime Dependency (on the Settings page) is active, that means you can—and should—upgrade as soon as you can. Once the message appears in the header, you're likely close to the end of your window according to Visual Builder's upgrade policy

Be sure to create a new version of your app before upgrading it.

After Upgrading

Once you trigger an upgrade, Visual Builder makes changes to your app to better align it with the upgraded release. We may, for example, address deprecated properties or move things from one file to another.

You'll see details of all the changes made to your application during the migration, so you know exactly what happened behind the scenes. If your app has syntax errors and migration fails—conveniently displayed in the upgrade dialog—you'll need to fix those issues before you can upgrade. Here's an example of what you may see when a migration succeeds and when a migration requires your action:

Description of the illustration upgrade_success.png

Immediately after migration, if you decide you don't want the upgrade, you can close the Upgrade Runtime Dependency dialog, then use the Undo icon in the header to roll back all the changes, though upgrading is the recommended course of action.

After you’ve upgraded your app, you still have to stage or publish the app for the upgrade to take effect for your running application.

Note:

If your app was last opened in the Designer before 19.4.3, the next time you open the app, it will be automatically upgraded to the latest Visual Builder Runtime/JET versions. The ability to control when to upgrade is available only to apps last opened in 19.4.3 or later.

Set a Custom Version

Use the Set Custom Version option only when directed to do so by Oracle. This option is provided in case you temporarily need to freeze your runtime dependencies for some reason, or point to a version of JET or the Visual Builder Runtime that may not yet be widely available.

The versions you specify must be compatible with each other; if they aren’t, you’ll see an error message, like this:

Although not recommended, you can ignore the warning message and click Apply to apply your changes.

The versions you specify in the Set Custom Version URLs dialog remain in effect until you set another custom version or use Revert to default to upgrade to the latest Visual Builder Runtime and JET versions:

Understand What’s Happening in visual-application.json

When you use the UI to influence your upgrade preferences, Visual Builder makes the corresponding changes to your visual application’s underlying visual-application.json file. Although you don’t have to change any values physically, it can be helpful to understand what’s going on behind the scenes.

In this example:

{
    "vbcs.dt.version": "20231205-24.04.0",
    "dependencies": {
        "upgrade": "micro",
        "paths": {
            "jet": "https://static.oracle.com/cdn/jet/15.1.3",
            "telemetry": "https://static.oracle.com/cdn/trace/8.0.0",
            "oracleImageGallery": "https://static.oracle.com/cdn/fnd/gallery/2404.0.0",
            "visualRuntime": "https://static.oracle.com/cdn/vb/2404.0.0"
        }
    },
    "source.version": "2404",
    "migration": { 
    ...
    }
}

• The upgrade property is set to micro. This means that if Visual Builder releases a minor version of the software (with numbers like 24.04.1, 24.01.2, etc.), your application will be automatically upgraded to that version the next time you open your application in the Designer. (Incompatibilities, while rare, tend to occur when shifting to major releases, especially when changes to a major JET release are also involved.) The micro setting is the default for new applications.

  If you are directed by Oracle to set custom versions for the Visual Builder Runtime and JET, the upgrade property is set to none, which means your app won’t be upgraded to newer available minor versions, should they become available. In effect, your changes are frozen until you use the Revert to Default option, at which point the upgrade property is set back to micro.

• The version of JET (under paths) is 15.1.3, while the Visual Builder Runtime version is 2404.0.0 (a minor version would have 2404.0.1).

Resolve Upgrade Issues

When you access an application following an upgrade, Visual Builder tries to update the application's metadata for compatibility with the newer version. If this update fails, Visual Builder opens your application in recovery mode to let you manually resolve the issues and retry the upgrade.

In addition to server-side upgrade issues, recovery mode may be triggered if the JSON information in the application's configuration file (visual-application.json) cannot be parsed. This can happen when there's an unresolved merge conflict or the JSON syntax is invalid.

If your app launches in recovery mode (as shown here), you no longer have access to the Navigator and Design view in the Designer:

Description of the illustration vb-app-upgrade-fails.png
Use the subset of features (Source view, Code view, Audits, and Find in Files) that Visual Builder makes available to find and resolve the issues that prevent the upgrade. The file information in the notification can help you navigate to the file that needs to be fixed.

Once you resolve all issues, click Upgrade to restart and complete the upgrade. Click the button as often as required until all issues are resolved.

Importing an application exported from an older version than the target instance also triggers an application upgrade. If the upgrade fails, the app is imported with the issues, but will be placed in recovery mode to help you fix the issues. However, if the imported application zip file contained entity or setup data, this data will not be imported if the import triggers recovery mode. Instead, once the application has been upgraded, you'll need to import the data in the application zip using the Data Manager on the Business Objects page (see Work with the Data Manager).

What Happens During Software Maintenance?

Visual Builder will occasionally need to undergo planned maintenance to bring the software to the most current release.

Your service will not experience any downtime during the update. Once the update is complete, you’ll be able to start using the new features immediately. While the update should not affect existing published applications, Oracle recommends that you update applications still in development to the latest version of the Oracle JET and Oracle Visual Builder runtime libraries. Not only will this allow you to take advantage of the new features and bug fixes they offer, but you’ll also be on a supported platform.

For published applications, we recommend that you create a new version of the application, update the runtime libraries in Application Settings, and test your application to make sure it functions properly. Once confirmed, publish the new version of the app. See Upgrade Your App for more information.