1. Building Responsive Applications with Visual Builder Studio
  2. Manage Applications
  3. Manage Runtime Dependencies for Visual Applications
  4. Upgrade Your Application

Upgrade Your Application

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

Tip:

You don't have to wait until you see a message in the Designer to upgrade your app. Once the message appears in the Designer, that means you're nearing the end of runtime support for your app. (Remember, the Designer supports applications built on the current runtime version, as well as the three previous versions.) But you can keep your app's dependencies up-to-date from the Settings editor. If the Upgrade button under Runtime Dependency is active, that means you can—and should—upgrade as soon as you can. Be sure to create a new branch before upgrading your app.

Note:

If you don't see the option to upgrade, it's likely your app's runtime dependencies were set to a custom version. This can happen if your app uses the Redwood Starter App template (with hard-coded versions in it). To upgrade your app then, click Revert to Default, then follow these steps once the Upgrade button shows.
  1. Click the arrow next to the Git branch name in the header:
    Description of gitrepoarrow.png follows
    Description of the illustration gitrepoarrow.png
  2. In the Switch Branch dialog, select Create new branch based on parent branch, then enter a new name for the branch where your app will be stored:
    Description of switchbranchandcommit.png follows
    Description of the illustration switchbranchandcommit.png
  3. If the selected parent branch exists both locally as well as in the remote repository, select Use parent branch from remote repository to use the remote branch as your new branch's parent. You'd typically want to do this if the remote branch is more current than the local branch. Otherwise, the local branch will be used.
  4. If there are changes in your current branch that you hadn't saved yet, enter a commit message.
  5. Click Commit and Switch (or just Switch if you cleared the Commit changes before switching (recommended) checkbox).
  6. At this point, click Upgrade in the header (or the Settings editor): Description of bannerwithheader.png follows
    Description of the illustration bannerwithheader.png
  7. In the Upgrade Runtime Dependency dialog, choose the release you want to move up to and click Upgrade:
    Upgrade Runtime Dependencies

After Upgrading

Once you trigger an upgrade, VB Studio 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:
Description of upgrade-success-vbs.png follows
Description of the illustration upgrade-success-vbs.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. If you do keep the upgrade, click Commit Changes, then Commit to commit the changes to your Git repository.

After you’ve upgraded your app, you still have to share or deploy 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:
Set Custom Version URLs dialog

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:
Runtime Dependency section when a custom version is set. The option to Revert to default is enabled.

Understand What’s Happening in visual-application.json

When you use the UI to influence your upgrade preferences, VB Studio 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": "20241210-25.04.0",
    "dependencies": {
        "upgrade": "micro",
        "paths": {
            "jet": "https://static.oracle.com/cdn/jet/17.1.1",
            "telemetry": "https://static.oracle.com/cdn/trace/10.0.0",
            "visualRuntime": "https://static.oracle.com/cdn/vb/2504.0.2",
            "oracleImageGallery": "https://static.oracle.com/cdn/fnd/gallery/2504.0.0"

        }
    },
    "source.version": "2504"
}

  • The upgrade property is set to micro. This means that if VB Studio releases a minor version of the software (with numbers like 25.01.1, 24.10.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 17.0.2, while the Visual Builder Runtime version is 2501.0.0 (a minor version would have 2501.0.1).