13 Preview, Share, and Deploy Visual Applications

VB Studio's Designer provides tools to preview, share, and deploy your visual applications as you go through the application development lifecycle.

What Happens When You Share and Deploy Visual Applications?

As you design and develop your application, you'll want to test it out as it will look to your user. The simplest way to do this is to use Preview Preview Button in the visual application's header. This option opens your application in another browser tab, enabling you to preview the application you're working on in the Designer.

The preview window (and the web or mobile application in it) is only visible to you. When you're ready to share your work with other team members or users, you'll use Share, a Menu option in the upper right corner of the visual application's header. This option deploys the visual application to your environment's Visual Builder instance, but without pushing your code to the project’s Git repository. As project members, you and your teammates can then access the shared visual application from the Deployments tab of the Environments page; users will need the URL of the app deployed to the Visual Builder instance.

After the visual application is tested and you are ready to make your changes public, you use the Publish option in the header to deploy your visual application. A successful Publish merges your changes to the project's default branch (usually, main) and triggers the build and deploy jobs in the pipeline set up when your visual application's project was initially created. This pipeline deploys your visual application, with the web and mobile applications that it contains, to your environment's Visual Builder instance.

For deployment to be successful, your organization must have purchased a separate Visual Builder instance that your organization administrator has set up for you to deploy applications from your VB Studio instance. This includes entering authorization details in the Oracle Deployment step of the deployment job to permit access to the Visual Builder instance. See Configure the Deployment Job in Administering Visual Builder Studio.

For applications that you've deployed, VB Studio provides a number of tools to help you manage your deployed application. These include the ability to:
  • Undeploy an application that's been deployed
  • Roll back to a previous version of an application that you deployed
  • Display a version number in the URL of a deployed app (usually, during development) or display "live" in the URL (usually, when the app is deployed to production)
  • Lock and unlock a deployed application

    When you lock a deployed application, your users see a notification message that the application is locked for maintenance. They are unable to use it, or edit data managed by the web app.

  • Specify a custom app URL (sometimes known as a vanity URL)

    You specify a custom app URL when you do not want to use the default URL that VB Studio generates for your application.

Preview a Visual Application

VB Studio opens a preview window in a separate browser tab when you click Preview Preview in the visual application workspace toolbar.

This preview window renders the pages and data from your web or mobile application.

Description of vbs-preview-visual-app.png follows
Description of the illustration vbs-preview-visual-app.png

Share a Visual Application

You can share your visual application with others without pushing changes to your project’s Git repository branch or using the build pipeline. Instead, you use the Share option in the visual application’s Menu to create a URL that you can share with others.

Much like a preview, sharing a visual application lets you and other team members try it out. But unlike a preview, the application you share is deployed to the Visual Builder instance that the project uses. If you make changes after the visual application is shared, you’ll need to share the application again for the changes to be deployed to the Visual Builder instance.

To share a visual application:

  1. In the visual application's header, click the Menu option in the upper right corner.
  2. Click Share, then select your options in the Share Visual Application dialog.

    The Share Visual Application dialog displays a list of the web and mobile applications in your visual application. The active application is the application that you're currently using and will open by default after a successful share. If you want to make another application active, select that application in the Navigator before you click Share. You can also click the Copy icon next to each application to copy the URL where the application will be shared. Use this URL to open an application that is not the active application after the share operation completes successfully.

    To manage your shared application's data, choose from the available Data options in the Share Visual Application dialog:
    • Use clean database is the default option. If you use this option, you, or the users of the shared application, must enter data in the application. Alternatively, you can import data (including sample data that you export from your workspace) into the application using the Import Data menu option in the Deployments tab. See Manage Business Object Data During Development.
    • Use development data (my workspace) if you want your shared application to automatically include sample data from your workspace.
    • Use previous data if you want your shared application to use data from a previous deployment of your application. Select this option if you want to re-use data that was included when you first shared your application.
  3. Click Share.

After the visual application is shared, you and other members of your project can open the URL for the shared instance of your visual application from the Deployments tab. As someone who shared the application, you can also open the shared instance by clicking Open Shared Application in the header's Menu:
Description of open_shared_application.png follows
Description of the illustration open_shared_application.png

If you copied a share URL using an application's Copy icon, you can use the URL to open that application.

To view shared applications from your environment's list of deployments, navigate to the Deployments tab in the Environments page and view the shared visual application in the Visual Applications tab. You access the applications within the shared visual application by clicking the link under the node for the shared visual application. For web applications and PWAs, any project team member with access to the Environments page in VB Studio can open the application in their browser. Other users, who access the application from the Visual Builder instance, need an appropriate user role if the application does not support anonymous access. See Secure the Application.

Shared Visual Applications in the Deployment Tab of Environments Page

Deploy a Visual Application

In addition to Share, VB Studio provides other options to deploy your visual application to the Visual Builder instance.

Unlike the Share option, the deployment options described here require you to commit and push the changes in your workspace to a Git repository branch. Once you’ve pushed your changes from the workspace to the branch, a build pipeline that packages the content in the branch and deploys it to your environment's Visual Builder instance is triggered. You can run a pipeline manually in the early stages of development, when you want to deploy the content of your working branch to the Visual Builder instance for review. Before you run the pipeline manually, you’ll need to verify that your working Git repository branch is specified in the pipeline job that packages your visual application (see Access Project Git Repositories). Once you've verified that the package job in your build pipeline is configured to use your branch, you can run the pipeline. See Run the Pipeline.

Alternatively, you can use Publish in the header. Given that Publish merges the content of your working branch to the default branch (main, for example) and runs a pipeline that deploys the content of the main branch to the Visual Builder instance, this option is probably something you’ll use when you’ve tested your visual application and are ready to make your changes public.

Note:

To deploy your visual application, the pipeline's deployment job must be configured with the credentials of a user who is authorized to connect and deploy to the Visual Builder instance. If your project owner hasn't provided these credentials, you'll be prompted to provide them when you click Publish the first time. If your credentials don't allow you to deploy to the Visual Builder instance, talk to your project owner or an administrator to get credentials that you can use. The credentials that you enter when prompted, if valid, will be permanently saved in the deployment job. Your administrator can also choose to enter the credentials directly in the build job, so you aren't prompted for them when you try to deploy your app. See Configure the Deployment Job in Administering Visual Builder Studio for details on how an admin can add the missing credentials.

The options available to you when you click Publish depend on how your project was set up and the changes you want to commit. If you have permission to push directly to the main branch without requesting review from other project team members (and you have uncommitted changes), then you can commit and publish your changes. If your project administrator requires merge requests to be reviewed, or you yourself have chosen to have your changes reviewed, then you can add reviewers. VB Studio will notify the reviewers of your merge request.


Description of vbs-publish-dialog.png follows
Description of the illustration vbs-publish-dialog.png

If your changes conflict with existing changes in the branch, VB Studio detects this and provides a message—you'll then need to use the Git Panel to review and resolve the conflicts.

Whatever tasks you have to complete in order to submit a merge request, you can't create another merge request until your pending merge request is merged to the branch. However, you can use the Git Commit and Push menu options to update the pending merge request.

Once VB Studio performs the Git actions necessary to merge your changes to the main branch, it starts the pipeline to deploy your changes to the Visual Builder instance associated with your project.

Description of vbs-publish-git-actions-complete.png follows
Description of the illustration vbs-publish-git-actions-complete.png

Any time a build is triggered to merge your changes (typically, when you click Publish), you'll see notifications about its progress right within the Designer. You can keep track of the jobs that deploy your changes to know which job has been triggered and whether it completed successfully (as shown below). You can also readily navigate to the job to view details or to take action when a job fails.
Description of build-notifications.png follows
Description of the illustration build-notifications.png

Set Version Information for Your Application

You can specify a version number for the visual applications that you share and deploy from VB Studio.

VB Studio includes a version number by default in the web and mobile applications that you create and deploy from your VB Studio projects. For web applications, this version number appears in the Deployments tab of VB Studio's Environments page (as shown here) and in the URL that users use to access your web application:

Visual Applications tab in the Environments page
The application version takes the following format:
  • When you share an application, it's vbshare_workspaceID, where workspaceID is an arbitrary number, for example, vbshare_1. The application URL in this case would be https://host/something-else/vbshare_1/index.html.
  • When you deploy an application, it's the value of the version property in the visual-application.json file, for example, 0.1:
    {
        "vbcs.dt.version": ".....",
        "dependencies": {
        ...
        },
        "source.version": "...",
        "rootURL": "something-else",
     "version": "0.1"
    }

    The application URL in this case would be https://host/something-else/0.1/index.html.

To change the version in visual-application.json, open the visual application's Settings editor in the Designer and modify the Version field. Consider using a numbering scheme (for example, 1.0, 1.1, 1.2, and so on).

If you want to override the version coming from visual-application.json, you can set a different value in the Application Version field of your visual application's deployment job. To do this, edit the job's Oracle Deployment step and set a value in the Application Version field, as shown here where 66 is the version to appear in the application URL:

Application Version fields in Oracle Deployment Job

Changing the Application Version in your deployment job does not update the version property in the visual-application.json file.

By default, the application version number is always included in the deployed application's URL. You won't usually need to remove the version during development, but when your application is ready to be deployed to production, it's a good idea to replace the application version with "live" (see the subsequent section for details on how to do this). In this case, the application URL would be https://host/something-else/live/index.html.

For mobile applications within the visual application, the version information is configured in the Version Name field of the mobile app's build configuration. See Build Mobile Applications.

Deploy a Live Version of an Application

When your visual application is fully developed and thoroughly tested, you are ready to deploy a live version of your application to a production instance.

The process to deploy a live version is similar to deploying other application versions, but your project must be configured to build and deploy visual applications to a Visual Builder production instance. See Set Up the Project to Deploy for Production in Administering Visual Builder Studio.

When you are ready to deploy your application to production, you'll want to remove the version that VB Studio includes by default in the web and mobile application's URL (for example, https://host/something-else/0.1/index.html) and replace it instead with "live" (for example, https://host/something-else/live/index.html). This configuration is controlled by the deployment job used to deploy your visual application and is enabled by default in the Visual-Application-Deploy job that's created for projects that use the Visual Application template.

To remove the version and deploy a live version of an application:

  1. In the left navigator, click Builds Builds.
  2. In the Jobs tab, find your visual application's deployment job, usually the Visual-Application-Deploy job.
  3. Click Configure Configure icon for your deployment job.
  4. On the Job Configuration page, click the Steps tab, deselect the Include the application version in the URL check box, and click Save:

    Deselected application version checkbox in the Oracle Deployment job

With this configuration, the deployed application will include live in its URL instead of a version number.
A visual application can be deployed live only once. If you want to deploy it again, you’ll need to update the value of the version property in the application's visual-application.json file.

Update the Live Version of an Application

If you want to make changes to the live version of your application, you need to create a new version of the application.

A visual application can be deployed live only once. To make changes to the live version, you’ll first need to increment or otherwise change the value of the version property in the visual-application.json file. This creates a development version that you can work on while the deployed version stays live. When you are ready to make your changes public, you'll need to re-deploy the new version with your updates.

To create a new version of a live application:

  1. Open the visual application you want to update in your workspace. You can either open an existing workspace or create a new one by cloning the visual application's Git repository.
  2. In the visual application's workspace, click the Menu option in the upper right corner and select Settings:
  3. Update the Version property in the Application tab. Consider using a numbering scheme, perhaps 1.0, 1.1, 1.2, and so on.
  4. Make updates to this version of your app as required. When you are done, click Publish to push your changes to the Git repo and trigger your application's deployment job.

Manage Deployed Visual Applications

After VB Studio successfully packages your visual application and deploys it to the environment associated with your project, you can use the Environments page to perform a number of tasks for the deployed applications in the visual application.

View Deployed Visual Applications

After the deployment job has successfully run, you can view the deployed applications in the Deployments tab of the Environments page.

  1. In the left navigator, click Environments Environments.
  2. If necessary, select the Visual Builder environment.
  3. Click the Deployments tab.
  4. If the Visual Builder instance is from a different identity domain, provide its access credentials.
  5. Expand the app's name to see the deployed app's link.

    The Deployments tab displays the applications you've deployed from the current project. It doesn't show applications deployed by other users of the project, or applications deployed from other projects.

View Database Schemas Used During an App's Lifecycle

As your application progresses through its development lifecycle, you might want to know which database schemas store the app's business objects in each phase (development, shared, and live).

VB Studio automatically manages the schemas and tables for apps and business objects in your database. It also re-creates the development and shared schemas with different names for every new version of your app. (The live schema for a deployed app doesn't change if you choose to not replace the data.)

If you are using your own Oracle database, knowing the name of the schema associated with each phase of your app can help you access data using other tools for import or export, or access the tables for your own purposes.

To view the schema associated with a particular phase of an application's lifecycle:
  1. In the left navigator, click Environments Environments.
  2. Click the Deployments tab.
  3. Locate your shared or deployed visual application, then look in the Schema column. Hover over the text to see the full schema name in a tooltip.

  4. To copy the schema name, select the Copy to Clipboard icon (Copy to clipboard icon), then paste it in a text editor of your choice.

Undeploy a Visual Application

You can manually undeploy a visual application that's deployed to your development Visual Builder instance (or one that's deployed to your current identity domain's Visual Builder instance) from the Deployments tab of its environment.

Undeploying an application is a permanent action that completely removes application metadata and any data stored in its database. This action can't be undone. Before you undeploy, consider the impact of removing your application, especially if the version is live, because once a version has been removed from the system, it can't be recovered.

  1. In the left navigator, click Environments Environments.
  2. If necessary, select the environment where the visual application is deployed.
  3. Click the Deployments tab.
  4. Expand the application.
  5. For the visual application to undeploy, click Actions Three horizontal dots and select Undeploy.
  6. In the confirmation dialog box, click Undeploy. If your application was deployed without the version in the URL (indicating a live application), you'll need to select Yes, I'm sure to confirm your selection, then click Undeploy.

Lock, Unlock, or Roll Back Deployed Visual Applications

If your visual application was deployed without the application version in the URL, you can lock and unlock deployed visual applications (and the web applications that they contain). You can also roll back a deployed visual application.

These lifecycle operations (lock, unlock, roll back) can be managed manually from the Environments page through the Deployments tab or automated with Visual Application build steps.

Use the lock and unlock options for a visual application when you have maintenance tasks to complete and you don’t want users accessing the web applications in the deployed visual applications during the maintenance period.

Use the rollback option when you have deployed your visual application more than once without including the application version in the URL. That is, "live" appears in the application URL, rather than the application version. If, for example, you have deployed three versions of your visual application to https://host/something-else/live/index.html, you can roll back to version 2, then to version 1.

If you deploy a visual application to a Visual Builder instance in the same identity domain as your VB Studio and you do not include the application version in the URL, then you can perform these tasks from the Deployments tab of your Environments page:
Visual Applications Deployment Tab in Environments Page

You'll need to add and configure steps in a build job to lock, unlock, or roll back a visual application in the following scenarios:

  • If your visual application is deployed to a different identity domain
  • If your application URL includes the version

VB Studio provides these build options as Visual Application steps that you can add and configure in a deployment job:


Build options available for a visual application when you click Add Step for a deployment job

For information about how to configure a build pipeline that uses these steps, see Create and Manage Jobs and Configure a Job

Specify a Custom App URL

Sometimes it’s not appropriate to use the default URL that VB Studio generates for your application. For example, if you’re building an application for your customers, you can use a custom domain for the application to shield customers from the details of your server’s host and domain name.

To use a custom domain for your application, your Visual Builder instance service administrator must configure your instance to support the custom domain. To do this, they’ll need to open a service request with Oracle Support to set up the URL redirection. They’ll also need to protect your Visual Builder instance with Oracle Cloud Web Application Firewall. For more information about the configuration tasks to support custom domains, see Configure Support for a Custom Domain in Administering Oracle Visual Builder Generation 2. After the visual application is deployed, the web application and the business object APIs can be accessed directly using the custom domain. You can also access web applications deployed as PWAs.

Only one custom domain can be mapped to a visual application, and it can only be used to access one web application in the visual application. It is recommended that your visual application contain only one web application if you are going to use a custom domain to ensure that the correct web application is loaded.

Multiple custom domains can be used in an instance, but each must be mapped to a different visual application. For example, if the visual application myvisualapp1 is mapped to the subdomain mysubdomain1, if you want to map mysubdomain2 to an application it must be mapped to a different visual application (for example, myvisualapp2).

To map a custom domain to a visual application:

  1. In the visual application's header, click the Menu option in the upper right corner.
  2. Click Settings.
  3. Open the Applications tab in the Settings editor.
    Application tab in Settings window
  4. Type the URL in the Vanity URL text field. Click Close.
    The URL must be the full URL that you want to use and use a valid form (for example, https://foo.example.org).
After you deploy the visual application, a visitor can type the custom domain (for example, https://foo.example.org) in the browser to open the web application. The URL will not contain any additional path parameters because the app is loaded as the root domain.

Manage Runtime Dependencies for Visual Applications

In VB Studio, 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:
Runtime dependency section in the Settings editor

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 22.01, 22.04, or 22.07.
  • 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, VB Studio automatically sets your runtime dependencies to the latest Visual Builder Runtime and JET versions. If you’ve already deployed (shared 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 two previous versions. So for 22.07, for example, the Designer supports not only the 22.07 Runtime Version, but also apps built with 22.04 and 22.01. Once 22.10 comes out, however, support for the 22.01 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.

When you are ready to move up, create a new version of your application. Then, click Upgrade in the Settings editor and choose the Release you want to move up to. You can see the Visual Builder Runtime and JET versions defined by the Release in the dialog itself:
Upgrade Runtime Dependency Dialog

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, you'll need to fix those issues—conveniently flagged for action in the upgrade dialog—before you can upgrade. Here's an example of what you may see when a migration succeeds and when a migration requires your action:


Combined image of the Upgrade Runtime Dependency dialog showing a successful migration, with details of what changed during the upgrade, and a failed migration, with links that you click to fix those issues.

Immediately after migration, if you decide you don't want the upgrade, you can 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 Show Changes to view the changed files in the Git Panel, then click Commit All 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": "20220315-22.07.0",
    "rootURL": "myvisualproject",
    "version": "0.1",
    "dependencies": {
        "upgrade": "micro",
        "paths": {
            "jet": "https://static.oracle.com/cdn/jet/12.0.1",
            "telemetry": "https://static.oracle.com/cdn/trace/6.0.0",
            "visualRuntime": "https://static.oracle.com/cdn/vb/2207.0.0"
        }
    },
    "source.version": "2207", 
    ...
}
  • The upgrade property is set to micro. This means that if VB Studio releases a minor version of the software (with numbers like 22.04.3, 22.07.1, 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 12.0.1, while the Visual Builder Runtime version is 2207.0.0 (a minor version would have 2207.1.0).

What Happens During Upgrade?

VB Studio 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 Manage Runtime Dependencies for Visual Applications for more information.

Resolve Upgrade Issues

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

In recovery mode, you no longer have access to features such as the Navigator and Design view in the Designer, as shown here:
Description of vb-app-upgrade-fails.png follows
Description of the illustration vb-app-upgrade-fails.png

You can only use the Source view, Code view, Audits, and Find in Files to identify and resolve issues that prevent the application from upgrading.

Here's a scenario describing what happens when you're placed in recovery mode for an application:

  1. You pull code from the Git repository and get a merge conflict. This creates a file in your visual application that is syntactically invalid. VB Studio flags this, the Designer will not open the file, and you can only edit the file in Code view. The Audits feature also notifies you that your file is invalid. However, you ignore the warnings, leave the file in an invalid state, and exit the visual application.
  2. Your VB Studio instance is upgraded to a newer version.
  3. When you re-enter the application, VB Studio compares the application version in its database to the version in the code. As they differ, it starts an upgrade of the application to the newer version. The upgrade tries to read the file that you left in an invalid state and fails because it is unable to parse the file. The upgrade stops. VB Studio enters recovery mode.
  4. You use the subset of features (Code view, Audits, and Find in Files) that VB Studio makes available in recovery mode 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.