21 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 for your web (or mobile) app 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 applications 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.

Note:

Sharing or deploying a visual application will generate corresponding "app clients" on the target Visual Builder runtime instance. An app client is needed for the services and IDCS roles in your application to work. You can delete an app client when it is no longer needed, for example, when you no longer need a shared application, you can delete the shared app's app client.

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 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 see the URL where the application will be shared. When your visual application contains multiple apps, you can use these URLs to open an application that is not the active application after the share operation completes successfully. You can also click Copy (Copy icon) next to each application to copy the share URL.

    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, 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. Keep in mind that you'll need a production instance of Visual Builder to deploy your changes to production.

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 deploy from your VB Studio projects. 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 application:

Description of vbs-versions.png follows
Description of the illustration vbs-versions.png
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). The application URL in this case would be https://host/something-else/0.1/index.html.
Here's how you can set an application's version:
  • To change the version in visual-application.json, go to 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, configure the deployment job and set a value in the Application Version field for the Oracle Deployment step under Steps. Here is an example where 66 is the version to appear in the application URL:
    Description of app-version-includecheckin.png follows
    Description of the illustration app-version-includecheckin.png

    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 is always included in the deployed application's URL. You won't 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". In this case, the application URL would be https://host/something-else/live/index.html. See Deploy a Live Version of an Application.

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.

Note that 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. To ensure that the correct web application is loaded when using a custom domain, your visual application must contain only one web application.

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. In the Settings editor's Applications tab, enter the custom domain you want to use in the Vanity URL field. The domain must be a complete URL and use a valid form, for example, https://foo.example.org.

After you've set the vanity URL, it's important you work with the visual app using its custom domain. For example, if the app's vanity URL is https://foo.example.org, access it in a browser at https://foo.example.org/ic/builder, then proceed to share and deploy the app.

Note:

Working with a vanity app from a non-vanity host can cause issues when you try to access the deployed app, so make sure you access the Designer using the app's custom domain.

After you deploy the visual application, a visitor can enter 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.

Deploy to Test and Production Instances

If you're a developer who's fairly comfortable with Git and the development lifecycle, you'll probably want to set things up so you have control of moving your visual app from the development phase into test, and finally to production.

When a project is first created and configured, it's typically set up so that changes committed to the main branch automatically kick off a pipeline that packages the visual app and deploys it to whichever Visual Builder instance was named as the project's Development instance. To deploy your visual applications to other non-production instances, like a test pod or another Development environment, you'll need to create new packaging and deployment jobs and create a pipeline to run the jobs.

Note:

Before you proceed, contact your Visual Builder administrator and make sure that the Visual Builder test and production instances are properly configured and running. For example, you may want to confirm that security options are configured for each instance and the instance points to the correct database for test and production.

Set Up the Project for Testing

When your development cycles are complete, configure the VB Studio project to build and deploy visual applications to a Visual Builder test instance. This involves the following steps:

To perform this action: Do this:
1. Create an environment for the Visual Builder test instance. Your test instance can reside either in your current identity domain or in another identity domain. From the current identity domain:
  1. In the left navigator, click Environments Environments.
  2. Click + Create Environment. In Environment Name and Description, enter a unique name and description, and click Create.
  3. In the Service Instances tab, click Add Instance.
  4. In the Add Service Instances dialog box, click Visual Builder.
  5. Select Identity Domain.
  6. Select the Visual Builder instance you want to add.
  7. Click Add.

If your test instance resides in another identity domain, see Add Additional Deployment Instances.

2. Create a new test branch in your project's Git repo.
  1. In the left navigator, click Git Git.
  2. Click Refs, then click Branches Branches.
  3. From the Repositories drop-down list, select the repository.
  4. Click + Create Branch.
  5. In the New Branch dialog box, in Name, enter the branch name. From the Base drop-down list, select the main branch as the base branch.
  6. Click Create.
3. Create copies of your existing development packaging and deployment jobs and modify them to deploy to the test instance. Create a copy of the packaging job used for development and modify it:
  1. In the left navigator, click Builds Builds.
  2. In the Jobs tab, click + Create Job.
  3. In the New Job dialog box, in Name, enter a unique name.
  4. In Description, enter the job's description.
  5. Select the Copy From Existing check box.
  6. In Copy From, select the packaging job used for development.
  7. In Template, change the build executor template if needed.
  8. Click Create.
  9. In the Job Configuration screen, click Save.
Create a copy of the deployment job used for development and modify it:
  1. Click Jobs Overview to return to the Jobs tab. Or click Builds Builds in the left navigator.
  2. Click + Create Job.
  3. In the New Job dialog box, in Name, enter a unique name.
  4. In Description, enter the job's description.
  5. Select the Copy From Existing check box.
  6. In Copy From, select the deployment job used for development.
  7. In Template, change the build executor template if needed.
  8. Click Create.
  9. In the Job Configuration screen, click Before Build.
  10. In From job, select the packaging job that you created for the test instance.
  11. Click Steps.
  12. In Target Instance, select the test instance.
  13. In Username and Password, enter the credentials of a user who can access the test instance.
  14. Click Save.
4. Set up a pipeline for the test instance.
  1. In the left navigator, click Builds Builds.
  2. Click Pipelines.
  3. Click + Create Pipeline.
  4. In the Create Pipeline dialog box, in Name and Description, enter a unique name and description.
  5. Click Create.
  6. Right-click the Start node, and select Add New Start Jobs.
  7. Select the packaging job you created for the test instance and click Save.
  8. To run the deployment job after the packaging job successfully completes, right-click the packaging job, select Add, then Add New on Success Jobs.
  9. Select the deployment job you created for the test instance and click Save.
  10. Click Save on the Pipeline Configuration page.
5. Run the pipeline. In most cases, you'll want to have this pipeline automatically triggered when anyone commits to main, but you do have the option to run the pipeline manually. (As an developer working alone or with just a few others on a project, it's unlikely that this option would appeal to you, but it does exist.)
  1. Click the Pipelines tab and locate the pipeline you want to run.
  2. From the Actions Actions menu menu, click Run Pipeline.

    You can also click the pipeline name to get to the Pipeline Details page, then click Run.

Set Up the Project for Production

When you're ready to move your visual app to production, the process is similar, with a few additional steps:
To perform this action: See this:
1. Create an environment for your Visual Builder production instance. Add the Visual Builder Production Instance to an Environment
2. Create a new branch in your project's Git repo for changes that are ready for production. After creating this branch, any changes pushed to the main branch won't be added automatically to the production branch. Instead, you must create a merge request or manually push the changes to the production branch, as a means of protecting the branch against untested or unwanted additions. Create a Production Branch
3. Create and configure the production build jobs:
  • Create a packaging job
  • Create a deployment job
4. (Optional) Restrict users who can edit the production jobs or run their builds. Configure a Production Job's Privacy Setting
5. Set up the pipeline. Create and Configure a Pipeline
6. Run the pipeline. Run the Pipeline

See Set Up the Project to Deploy for Production in Administering Visual Builder Studio.

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 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 check box in the Oracle Deployment job

With this configuration, the deployed application will include live in its URL instead of a version number.
Only one version of an app can be live at a time. If you want to make changes to the live version, you’ll need to first update the value of the Version field in the application's Settings editor (which corresponds to the version property in the 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 specific version of 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 application's version. 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 field 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. For the visual application you want to undeploy, click Actions Three horizontal dots and select Undeploy.
  5. 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

When your visual application is deployed without the application version in the URL, you have the option to lock and unlock the visual application (and the apps it contains). You can also roll back a deployed visual application.

Lock/unlock and rollback are lifecycle operations that 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 live more than once (that is, "live" appears in the application URL instead of 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 deployed a visual application to a Visual Builder instance in the same identity domain as your VB Studio instance and didn't include the application version in the URL, you can perform these tasks from the Deployments tab of your Environments page:
  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. For the visual application you want, click Actions Three horizontal dots, select the operation to perform, and follow the prompts:

If your visual application is deployed to a different identity domain or your application URL includes the version, you'll need to add and configure steps in a build job to lock, unlock, or roll back a visual application. See Configure a Build Job to Manage Deployed Visual Apps.

Configure a Build Job to Manage Deployed Visual Apps

If your visual application is deployed to a different identity domain or your application URL includes the version, you'll need to add and configure steps in a build job to perform lifecycle operations. VB Studio provides these options as Visual Application steps that you can configure in a build job and include:

  • Importing and exporting business object data to and from deployed visual applications
  • Locking and unlocking live deployments
  • Rolling back updates to a live version
  • Auditing and testing visual apps before deploying them
  • Undeploying visual apps when they're no longer needed
To configure these options in a build job:
  1. In the left navigator, click Builds Builds.
  2. Depending on the option, decide if you want to configure an existing job or create a new one. For example, you might want to audit and test your visual app either as part of the package job, or more likely as a separate job that you'll run before the package job or as part of a merge request.
    • To add an option to an existing job, click Configure Job Configure icon for the job.
    • To add an option as part of a new job, click + Create Job. Give the job a new name and a description, select the build executor template, then click Create.

    See Create and Manage Jobs for details.

  3. On the Job Configuration page, click Steps.
  4. Click Add Step, select Visual Application, then choose the option you want to add.
    Build options available for a visual application when you click Add Step for a job

    While each option has its own set of parameters, they are all Grunt-based commands that automate the task of continuous integration and delivery for you. See the following for more information about each option:

  5. When you are done, click Save.