8 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?

The visual application toolbar provides access to these tools. The simplest to use is Preview Preview Button. It opens a preview window in another browser tab to the Designer’s browser tab where you develop the application.

The preview window, and the web or mobile application in it, is only visible to you. If you want to share your work with other team members or users without committing your code to your project’s Git repository branch or running the build jobs that package and deploy your visual application, use the Share entry in the Options menu of the visual application workspace toolbar. This deploys your visual application to the Visual Builder instance. You and other project members access the URL for the deployed visual application from the Deployments tab of the Environments page while users access it in the Visual Builder instance.

After you complete your visual application, test it, and it works as you expect, you are ready to deploy it to make your changes public. Publish Changes Publish Changes facilitates this task. A successful Publish Changes Publish Changes action merges your changes to the master branch and triggers the build and deploy jobs in the pipeline that VB Studio set up when you or your project owner initially created the project that contains your visual application. This pipeline deploys your visual application, with the web and mobile applications that it contains, to the Visual Builder instance.

For the deployment step to be successful, your organization must have purchased a separate Visual Builder instance that your organization administrator has set up so that you can 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 have deployed, VB Studio provides a number of tools to help you manage your deployed application. These include the ability to:

  • Undeploy an application that has been deployed
  • Roll back to a previous version of an application that you deployed
  • The ability to 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.

  • Display a version number or the word live in the URL of the deployed application
  • 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 from the visual application’s Options menu to create a URL that you can share with others.

VB Studio deploys your visual application to the Visual Builder instance that your project uses. If you make other changes after you share the visual application, you’ll need to share the visual application again for these later changes to be deployed to the Visual Builder instance.

To share a visual application:

  1. In the visual application workspace toolbar, click the Options menu.
  2. Click Share, then select your options in the Share Visual Application dialog.
    Ignore the Base URL field in the Share Visual Application dialog. To manage your application's data, you can choose from the available Data options:
    • 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.
  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 Options menu. The Open Shared Application menu option appears after you share the visual 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

VB Studio provides other options, in addition to Share, 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, you run a build pipeline that packages the content in the branch and deploys it to the Visual Builder instance. You can run a pipeline manually. You might run the pipeline manually when you are in the early stages of development, and you want to deploy the content of your working branch to the Visual Builder instance to review and test. 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) before you run the pipeline manually. Once you have verified that the package job in your build pipeline is configured to user your branch, you can run the pipeline. See Run the Pipeline.

Alternatively, you can use Publish Changes Publish Changes from the visual application toolbar. Given that Publish Changes Publish Changes merges the content of your working branch to the master branch, and runs a pipeline that deploys the content of the master branch to the Visual Builder instance, this option is probably something that you’ll use when you’ve tested your visual application and are ready to make your changes public.

The exact dialogs that appear when you click Publish Changes Publish Changes depend on a number of factors related to how your project is configured by your project owner and the changes you want to commit. If you have permission to merge directly to the master branch without requesting review from other project team members and your merge includes changes that do not conflict with other changes in the branches where you want to merge, then the dialogs that VB Studio presents to you require you to enter a commit message and click Publish Changes Publish Changes. However, if your project administrator requires merge requests to be reviewed or you yourself want your changes reviewed then the dialogs that VB Studio presents request that you specify the reviewers to be notified of your merge request. Also, if your changes conflict with existing changes in the branch, VB Studio detects this and presents you with dialogs where you can review and resolve the conflicts.

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

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

Once VB Studio performs the Git actions necessary to merge your changes to the master 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

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 screen to perform a number of tasks for the deployed applications in the visual application.

View the 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 navigation menu, click Environments Environments.
  2. Select the Visual Builder environment.
  3. Click the Deployments tab.
  4. Click the Visual Applications toggle button.
  5. If the Visual Builder instance is from a different identity domain, provide the personal access token or its access credentials.
  6. 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.

    Example:

Lock, Unlock, or Roll Back Deployed Applications in VB Studio

You can lock and unlock deployed visual applications, and the web applications that they contain, as well as roll back a deployed visual application.

Use the ability to lock and unlock 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. 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 this task from the Deployments tab of your Environments page.

The Rollback menu option is available to use when you have deployed your visual application more than once without including the application version in the URL. That is, the word 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 and then to version 1 by using the Rollback menu option.

Visual Applications Deployment Tab in Environments Page

You have to add and configure steps in a Build Job when you want to lock, unlock, or roll back a visual application in the following scenarios:

  • Deployed your visual application to a different identity domain
  • Included the application version in the URL

VB Studio provides visual application steps that you can add and configure to a build pipeline. For information about how to configure a build pipeline that uses these steps, see Create and Manage Jobs and Configure a Job.

wegantodo

Undeploy a Visual Application

You can undeploy a visual application that's deployed to your current identity domain's Visual Builder manually from the Deployments tab of its environment, or configure a build job to undeploy it.

To undeploy a visual application that's deployed to Visual Builder of another identity domain, configure a build job and run it. You can't undeploy it manually.
Undeploy a Visual Application Manually
  1. In the navigation menu, click Environments Environments.
  2. 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 Hamburger icon and select Undeploy.
  6. In the confirmation dialog box, click Undeploy.

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 and in the URL that users use to access your web application.

The pattern for the version number is vbshare_workspaceID if you share the application (where workspaceID is an arbitrary number) and the value of the version property in the visual-application.json file if you deploy the application.

{
    "vbcs.dt.version": ".....",
    "defaults": {...
    },
    "rootURL": "something-else",
    "version": "0.1"
}

Edit the value for the version property in the visual-application.json file if you want to use a different version number. Consider using a numbering schema for deployed applications (1.0, 1.1, 1.2, and so on).

Visual Applications tab in the Environments page

You can disable the default behavior of including a version number in the deployed application URL when you deploy a web application from a visual application by clearing the Include the application version in the URL checkbox that is exposed in the Oracle Deployment step of the deployment job. This checkbox is enabled by default in the Visual-Application-Deploy job that is created in projects that use the Visual Application template. The effect of clearing this checkbox is to replace the version number in the URL with the word live. You can only deploy a visual application that includes live in the URL once. To deploy such a visual application again, you’ll first need to increment or otherwise change the value of the version property in the visual-application.json file.

In summary, the URL that you use to access a shared or deployed application takes one of the following forms:

// Shared application:
   https://host/something-else/vbshare_1/index.html

// Deployed application that includes the application version:
   https://host/something-else/0.1/index.html

// Deployed application that excludes the application version 
// by clearing the Include the application version in the URL checkbox:
   https://host/something-else/live/index.html

You can override the value of the version property in the visual-application.json file if you enter an alternative value in the Application Version field in the Oracle Deployment step of the deployment job, as shown in the image where 66 is the application version to appear in the URL. The value that you enter in the Application Version field does not update the value of the version property in the visual-application.json file.

Application Version fields in Oracle Deployment Job

For mobile applications within the visual application, you set the mobile app version information in the build configuration that you configure. See Build Mobile Applications.

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. After the visual application is deployed, the web application and the business object APIs can be accessed directly using the custom domain.

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 only contain 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 workspace toolbar, click the Options menu.
  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.

Specify Custom JET and Runtime Versions for Applications

VB Studio exposes input fields in the Application Settings page that allow you to specify custom JET and Visual Builder runtime versions for applications.

Use the Custom VB Runtime Version and Custom JET version fields if you want to make a minor change and redeploy an existing application without upgrading to the current Visual Builder runtime version or JET version. We recommend you always use the latest version of Visual Builder and JET to take advantage of new features and fixes.

If you redeploy your application again at a later date, VB Studio updates your application to the latest runtime version(s) unless you again specify the custom versions you want to use. That is, you must specify the custom versions you want to use each time. Otherwise, VB Studio upgrades your applications to the latest versions.

To specify custom JET or runtime versions:
  1. Click the Web Applications tab for a web app or the Mobile Applications tab for a mobile application or a PWA.
  2. Click the <app name> node and click the Settings icon (Settings icon).
  3. Specify a value for the Visual Builder runtime version, JET version, or both.
    You can specify one or both values. When specifying a value, ensure that the specified version matches an earlier and released version of the software. VB Studio uses the specified version when you preview, share, and deploy the application.

    Table 8-1 Behavior for custom values

    Custom VB Runtime Version Custom JET Version Behavior
    Specified Specified Specified versions of VB Runtime and JET are used
    Specified Not specified Specified VB Runtime version is used and the matching JET version specified in its versions.json is used
    Not specified Specified Specified version of JET is used and the default VB Runtime version for the build of VB Design time is used
    Not specified Not specified Default VB Runtime and JET versions for this build of VB Design time are used