1 Get Started with Oracle Visual Builder Studio

Learn how you can use the tools in Oracle Visual Builder Studio to build web and mobile applications.

What Is Oracle Visual Builder Studio?

Oracle Visual Builder Studio (VB Studio) is a robust application development platform that helps your team effectively plan and manage your work throughout all stages of the app dev lifecycle: design, build, test, and deploy.

In addition, VB Studio makes it easy for your entire team to develop the artifacts they need, including:

  • Oracle Cloud Applications developers, who need to extend their Apps with business-specific customizations;
  • Low-code developers, who want to create web or mobile apps using a visual designer;
  • Experienced programmers, who want to modify the source code for web and mobile apps created by others, or to develop bespoke apps using the web programming language of their choice.

With VB Studio you get:

  • Built-in repositories for hosting code in Git and for hosting binaries, such as Maven dependencies
  • A continuous integration service so you can automate your build and test systems
  • A continuous delivery service that tightly integrates with Oracle Cloud Applications
  • A rich visual designer integrated with source control (Git) so that developers can manage changes, apply version control best practices, and collaborate with their teammates to develop applications
  • The ability to build and display different flavors of the UI to meet the needs of discrete users of certain Oracle Cloud Applications (those built with VB Studio and Oracle Java Extension Toolkit (Oracle JET)), also within a Git framework
  • Agile boards and an issue tracking system for tracking sprints, tasks, defects, and features

VB Studio enables developers to easily deploy their applications to their preferred target, whether it’s a staging or production instance of Oracle Cloud Applications or an Oracle Cloud Infrastructure (OCI) service instance.

Build Web and Mobile Applications with VB Studio

VB Studio provides a visual environment to develop, test, and deploy mobile and web applications.

It provides easy access to data from any REST-based service, and enables you to create custom reusable business objects for storing and managing data. Using the cloud-based visual development tools, you can create and test responsive web applications, progressive web apps, and native mobile applications without the need to install any additional software. The visual designer (Designer) enables you to lay out pages in your applications by dragging and dropping UI components, customizing their attributes and defining their behavior.

VB Studio uses Oracle JET to create web and mobile interfaces. Reusable Oracle JET Web Components, built using the Web Component standard, can be added to the application to further enhance the user experience.

VB Studio also provides the following tools for building and publishing applications:

  • Robust tools to describe requests and responses to Oracle Cloud Application services in the integrated catalog

  • Data management tools for managing business objects and importing and exporting data

  • Tools to configure role-based security and user access management

  • Tools to access Git repositories so you can share application resources with team members

If you previously developed visual applications in Visual Builder and now work with VB Studio, you’ll see that some things have changed. For details about tasks that you now do differently in VB Studio, see For Visual Builder Users.

This diagram shows the main artifacts in a visual application project.
Description of project-diagram-visualapp.png follows
Description of the illustration project-diagram-visualapp.png

Here are the key components of the VB Studio ecosystem as it pertains to visual applications (that is, web and mobile applications):

  • Within a single VB Studio instance, you and your team members who use that instance are considered an organization. Within your organization, you will likely belong to one or more projects, each of which is devoted to a discrete software effort. For example, you might have a project for building a new Financial mobile app, and a different project for creating an HR web application. A project brings together all the tools you need to create those artifacts, such as a Git repository for storing your source code, a pipeline to provide continuous integration and delivery, an issue tracking system, team wikis, and more.
  • If you used Visual Builder Cloud Service in the past, you're familiar with the Designer, which helps you build visual applications using a declarative graphical user interface. Specifically, you get a page editor, a Components Palette, and a Page Structure view, for designing the layout of a page. The Designer remains a key component in VB Studio as well.
  • All of your work in VB Studio is done in the context of a workspace, a completely private area where you can work on your visual application. Your work is stored in your own clone of the project's Git repository, and is not visible to others until you a) merge it to the project's Git repo, b) choose to Share it with other for testing, or c) deploy it. A workspace also includes a pointer to the development or test environment where you plan to deploy your app, which must be a separate Visual Builder instance (also known as an environment). You can deploy your app manually, or wire it up to a pipeline to do it automatically, such as when a developer on your project merges his or her branch to the master branch.
  • The data for your visual applications can come from a database (in the form of business objects), Oracle REST services, or external REST services, just as in Visual Builder Cloud Service.

Create Visual Applications in VB Studio

A visual application is a collection of resources that you use to develop web and mobile applications. It includes metadata in JSON files that describe data sources and business objects, and includes the HTML and JavaScript files of web and mobile applications (applications).

It also includes service connections to REST services that the applications connect to in order to consume and edit data exposed by the REST service. For mobile applications, a visual application also stores configuration information necessary to build the Android and iOS mobile applications, or progressive web applications (PWA), that you can generate from the project source of a mobile application in your visual application.

Before you can create visual applications in VB Studio, a project must be set up where you and other project members collaborate to develop web and mobile apps. Usually, projects are set up for you by a project owner using the Visual Application template. For an overview of the steps to set up a project for visual applications, See Setting Up for Visual Applications in Administering Visual Builder Studio.

Once a project owner has set up a project and added you to it, the steps that you'll follow to develop a web or mobile app in VB Studio will be broadly the same:

  1. You'll access the project that your project owner created for you.

    By default, a project created using the Visual Application template includes artifacts such as a Git repository, a build pipeline, and a Development environment where you can view the status of the Development VB Instance (Visual Builder) and the apps deployed to it.

  2. Once you enter the project, you’ll create a workspace in the Designer. A workspace is where you create a new visual application or clone the Git repository of an existing visual application.
  3. After VB Studio sets up your workspace, you’ll work within the Designer to develop your application. You can preview your application in a separate browser tab as you develop, and you can share it with others to test, without having to commit changes to the Git repository branch, or run the build pipeline.
  4. When you are ready to deploy your application, you click the Publish Changes icon in the Designer. If your workspace does not contain changes that conflict with other changes in the branch, and if your project owner permits you to commit changes without a merge review, then you can publish your changes by entering a commit message and clicking Publish Changes. This triggers a build pipeline that includes a packaging and deployment job that your project owner should have configured with the credentials required to deploy your application to the Visual Builder instance. On successful completion of this build pipeline, your application should be deployed to the Visual Builder instance. You can view the progress of the build pipeline from the Builds page and the status of your application in the Visual Applications tab of the Development environment in the Environments page.
  5. For a mobile application that you deliver as a progressive web app (PWA), the steps to deploy are the same as those for web applications, assuming you have configured the PWA option in the mobile app’s Settings page. For a mobile app that you deliver as an Android or iOS app, you must first create a build configuration where you upload the certificates that you need to provide before you can build and publish these types of mobile application.

This series of steps describe how you create a web or mobile app that you deploy to the Development environment of your project. Once you progress to the testing and delivery stages of app development, your project owner should have set up test and production instances in the project’s Environment where you can deploy test and production versions of your web and mobile apps. See Set Up VB Studio for Developing Visual Applications in Administering Visual Builder Studio.

Create a Workspace for a New Visual Application

To create a new visual application in VB Studio, you create a workspace in the project where your project owner added you as a team member. A workspace contains all the artifacts that you need to develop visual applications and contribute to your team’s project(s).

  1. Sign in to VB Studio.
  2. On the Organization page, select your assigned project where you want to create a visual application.
  3. On the Designer page, click + Create Workspace.
  4. In the Create Workspace dialog, enter a name for the workspace, and click New Visual Application in the Initial Content tab.
    The name you enter for the workspace will also be the name that VB Studio uses for the visual application it creates.
  5. In Visual Application Template, click Change Template if you want to use a different template to the Default VBCS Application template that is automatically selected. The default template does not create any artifacts, apps or other resources. Other templates might create resources or apps that already include artifacts.
  6. In Git Repository, enter a repository name and working branch name for the Git repository that VB Studio will create when it creates the workspace. Alternatively, select the Scratch repository checkbox if you do not want to create a Git repository and working branch when you create the workspace.
  7. Select the Development Environment. You might have only one option.
  8. Click Create Workspace.

VB Studio creates a workspace with the name and the repository option you specified. Once VB Studio completes set up of the workspace, it opens the workspace where you can start to create web apps, mobile apps, business objects, and connections to REST services.

What is a Scratch Repository?

When you create a workspace, you have the option to create a scratch repository, rather than using a copy of the project's Git repository. You may want to create a scratch repository instead of a branch when you are experimenting and you're pretty sure you'll never want to merge its contents into an existing repository. A scratch repository is a private repository that only exists in your workspace. No one else can see the repository's contents, and it's deleted when you delete the workspace. It's better to create a branch rather than a scratch repository if you think you might want to eventually merge its contents into the main repository.

If you're using a scratch repository in your workspace and you decide you want to let your team members use it, you can push your scratch repository to a new Git repository.

Create a Workspace Using an Existing Repository

To make changes to a visual application that already exists, you want to create a workspace that contains a clone of the visual application's Git repository.

If you want to use a branch used in another workspace, you can create a new workspace and clone the branch for your changes.

When creating a workspace you will create a new local repository by cloning an existing repository or creating a branch. When cloning an existing repository, you will usually want to clone the master branch of your application's repository. This ensures that the new branch that you create contains the most up-to-date changes. If you are making changes that have not been merged to the master branch, you will want to select the branch containing the sources that you want to edit. For example, if you need to make changes to MyFeature, and MyFeature has not been merged to master, you'll want to clone the branch that contains the MyFeature changes (e.g. MyFeature-branch.git). You will make the changes to the MyFeature branch in your workspace.

To create a workspace by cloning a repository containing a visual application:

  1. Click Designer in the main menu to view the list of your workspaces in the project.
    The list might already contain workspaces even if you have not created one using the Create Workspace wizard.
  2. Click Create Workspace.
  3. Type a name for your workspace.
  4. Click Clone from Git.
  5. Select the Git repository.
  6. Select the branch of the repository you want to clone. This can be master, or any other branch.
  7. Select New branch from selected and type a name for the branch you want to create.

    You can create additional branches and switch between branches in the workspace.

  8. Select the Development Environment. You might have only one option.

    Each of your workspaces will probably use the same development environment because a project typically has only one. The environment must also support the type of project you are working on, so to create a workspace for a visual application, your project must be associated with a Visual Builder instance. If an environment is not defined for your project you should contact an administrator to add one.

    Description of vbs-cloneworkspace.png follows
    Description of the illustration vbs-cloneworkspace.png

Import and Export Visual Applications

You can export a visual application as an archive to your local system that you can then import to create a new visual application. You can use the import and export mechanism to share application sources and to move applications between instances.

Export a Visual Application

You can use the Export Visual Application action to download an archive of a visual application and its resources to your local system. After exporting the archive, you can import it to create a copy of the application and share the archive with team members.

When you export the application you can choose if you want the archive to include the data contained in the application’s custom business objects. Some information, such as credentials for external REST end points, is removed when you export an application. This information needs to be provided after the archive is imported.

To export a visual application:

  1. On the Designer home page that displays the list of workspaces in your project, select Export from the dropdown menu beside the workspace that contains the visual application you want to export.
  2. In the Export Visual Application dialog, clear the Include business objects data checkbox if you do not want to export custom business object data in the archive that VB Studio creates.
  3. Click Export.

    When you choose to export the visual application with business object data, the archive will include a json file (entity.json) and spreadsheet (entity-data.csv) for each custom business object. The json file describe the business object and the spreadsheet contains the business object data. If you choose to export the application without data, the archive will only contain the json file describing the business objects.

    The archive will always include the data for any business objects that are identified as containing Application Setup Data.

The visual application and its resources are exported as an archive file. The archive is saved to your local system in the location specified for your browser’s downloads.

Create a Workspace by Importing a Visual Application

To import your visual applications into VB Studio, you create a workspace in the project where your project owner added you as a team member. You import an archive file of a visual application that was previously exported into this workspace.

You can also replace all the source files of an existing visual application with the contents of a visual application archive using the Import command in the Options menu in the toolbar of the existing application. When you click Import, the Import Resources dialog box will open where you can import a ZIP archive. If you select Delete existing files and resources in the dialog box all the files and resources in the existing visual application will be deleted. The resources are imported into the root directory of your visual application. You might want to select this option when you want to replace all the existing files with new files to prevent duplicating files.

To import a visual application:

  1. On the Organization page, select your assigned project where you want to import the visual application.
  2. On the Designer page, click + Create Workspace.
  3. In the Create Workspace dialog, click Import from File and drag your visual application archive file from your local system into the upload area. Alternatively, click the upload area in the dialog box and use the file browser to locate the archive on your local system.
  4. In Git Repository, enter a repository name and working branch name for the Git repository that VB Studio will create when it creates the workspace. Alternatively, select the Scratch repository checkbox if you do not want to create a Git repository and working branch when you create the workspace.
  5. In the Development Environment dropdown list, select the environment to use.
  6. Click Create Workspace.

VB Studio creates a workspace with the name and the repository option you specified. Once VB Studio completes set up of the workspace, it opens the workspace where you can work with the visual application that you imported. After you import a visual application, you might need to provide additional details such as service credentials in the new application.

Manage Your Visual Applications With Git

VB Studio creates a Git repository for you when it creates your visual application. You can choose between a Scratch repository, which is private to your workspace, or a Git repository, and an associated working branch, which you can share with other team members in your project.

After VB Studio opens your workspace in the Designer, you’ll see a dropdown menu in the upper-right of the Designer that provides access to Git commands that you’ll use frequently. You’ll also see a tab in the Application Navigator that opens the Git Panel, where you can view changes in your workspace that you have yet to commit to your Git repository branch. The Git Panel also provides access to tools that assist you as you review and resolve conflicts that occur when your changes conflict with those of other project team members. The Git features in the Designer complement VB Studio’s support for source code management using Git, described in Manage Source Code Files Using Git Repositories.

Git Menu in Workspace Designer

Pull Files From Your Git Repository

You use the Pull option in the Git menu to update your visual application with the source files from the linked Git repository.

To pull source files from a repository:
  1. Open your visual application.
  2. Click the Git icon in the toolbar and select Pull in the menu.

    The Update Application from Git dialog box displays the details of the branch containing the source files.


    Description of git-update-application.png follows
    Description of the illustration git-update-application.png
  3. Click Update From Git.

    The dialog box displays a progress bar while pulling the source files from the branch. You

  4. Click Close when the update is finished.

    The dialog box displays a status message when the update is complete.


    Description of git-update-application-complete.png follows
    Description of the illustration git-update-application-complete.png

Push Your Changes to Your Git Repository

You use the Push to Git command in the Git menu to upload the source files in your visual application to the linked Git repository.

To help avoid merge conflicts, you should update the source files in your visual application by pulling the most recent versions from the repository before you push any changes. If the file versions in the repository are newer than the versions in your visual application, you’ll see a status message when attempting to push your changes that the push was rejected and you should pull the most recent versions from the repository before pushing.

To push the visual application source files to the repository:

  1. Open your visual application.
  2. Click the Git icon in the toolbar and select Push to Git in the menu.

    The Push Content to Git Repo dialog box displays the details of the target branch.


    Description of git-push-content.png follows
    Description of the illustration git-push-content.png
  3. Type a comment that describes the content you are pushing to the repository. Click Push to Git.

    The comment message that you provide in the dialog box is displayed when you examine the Git activity log for the branch.

  4. Click Close when the push is finished.

    The dialog box displays a status message when the push is complete.


    Description of git-push-content-complete.png follows
    Description of the illustration git-push-content-complete.png

Push a Scratch Repository to a Git Repository

If you chose to use a scratch repository when creating your visual application, other team members in your project cannot work with your visual application.

You can share the content of your scratch repository with your team members by pushing its content to a Git repository that VB Studio will create for you.

  1. Open your visual application.
  2. Click the Git icon in the toolbar and select Push in the menu.
  3. In the Push Content to Git Repository dialog that appears, enter a value in the Repository to Create input field. You can provide an optional description for the Git repository that VB Studio will create for you.
  4. Enter a commit message, and then click Create and Push.

Create or Switch a Branch

When you create a visual application with a Git repository, VB Studio creates two branches in the Git repository (master and working branch).

The master branch contains the initial set of source files for the visual application. The working branch contains the same set of source files initially, but as you work with your visual application, this branch will contain the changes that you make. Using the Switch Branch option in the Git menu, you can switch branches and commit your changes to the branch you switch to, or create a new branch from the branch you are currently working in.

You use the Switch Branch dialog to switch branches or create a new branch from the existing branch that you are working on.

  1. Open your visual application.
  2. Click the Git icon in the toolbar and select Switch Branch in the menu.

    The Switch Branch dialog displays the current branch in the Branch dropdown menu and the number of uncommitted files, if any, in the current branch.

  3. Choose the appropriate option:
    • To switch branches, select the branch that you you want to switch to and click Commit and Switch or Switch. The button’s label depend on whether you selected the Commit changes before switching (recommended) checkbox.
    • To create a new branch, select the New branch from selected checkbox, enter the name for the new branch in the New branch name input field and click Switch.

Resolve Code Conflicts Using the Git Panel

Use the Git Panel to review and resolve code conflicts that occur when your changes conflict with the changes made by other project team members in the working branch where you all commit code changes.

Typically, you’ll be informed of these conflicts when you attempt to push your changes to the working branch, or when you pull the latest changes from the working branch to your workspace. You’ll have to resolve the conflicts before you can commit and push the changes in your workspace to the working branch. When this happens, open the Git Panel and open the file(s) that the Git Panel identifies as containing code conflicts. The editor where you open the file(s) with code conflicts contains controls to navigate you through each code conflict, and provides options to resolve the conflict. In the following image, the Git Panel highlights a conflict between the workspace copy of the main-start-page.html file and the copy of the file in the working branch. The user must make a choice to resolve the conflict. Apart from the code conflict in the main-start-page.html file of the web app, the Git Panel identifies other changes in the user’s workspace that have yet to be committed to the working branch, such as a new mobile application (app2). Once the code conflict is resolved, all changes can be committed and pushed to the working branch.

Git Panel in the Designer with Code Conflicts

As with other Git features in the Designer, the Git Panel code conflict resolution features complement VB Studio’s support for source code management using Git. You can also review and resolve conflicts from VB Studio’s Git page. See Resolve a Merge Conflict.

Manage Visual Application Settings

A visual application is a container that includes one or more artifacts, such as a web or a mobile app. You can configure settings for a visual application that affect the artifacts within it, while other settings are application-specific, such as the version number for a mobile app.

You configure settings for a visual application in the Settings editor. To access the Settings editor, click the Options menu in the visual application workspace toolbar and select Settings.


Description of vbs-visual-app-ws-settings.png follows
Description of the illustration vbs-visual-app-ws-settings.png

The settings for a visual application are grouped into tabs in the Settings editor:

  • Application: Read-only values appear for settings such as your workspace name, but you can configure the values for the Root URL and Vanity URL properties. VB Studio uses the values for these latter properties when you share your visual application or use a custom app URL (also known as a Vanity URL). For these tasks, see Share a Visual Application and Specify a Custom App URL.
  • Translations: You can download the strings that appear in the user interface of your visual application's web and mobile apps to import into a third-party translation tool for translation. You then upload the translated strings from the translation tool to use for those apps that support different languages. See Work with Translations.
  • Application Profiles: An application profile allows you to deploy your app with different settings depending on the environment. If, for example, you are developing a web or mobile app, you won’t want to use a production REST service with access to live customer data. Instead, you’ll use a development or test instance of the service. Once you complete development and your app is deployed to production, you’ll want it to connect to the production REST service. Application profiles help manage the switch between the instances of the REST service. Similarly, you use application profiles to simplify the management of mobile build configuration depending on whether your app is in development, test, or production. See About Application Profiles.
  • User Roles: Controls access to business objects and data in your apps based on a person’s user role. See About Authentication Roles and User Roles.
  • Business Objects: Retrieve the API for the catalog of endpoints exposed by business objects in your visual application. Other settings in this tab configure client’s access to this API. You can configure anonymous access, basic authentication, or get an access token that a client can use. See About Allowing Access to the Catalog API and Get an Access Token for Authentication.
  • Services: Add or configure connections to a catalog of backend services provided by Oracle, such as Oracle Cloud Applications. See Manage Backend Services in Your Visual Application.

Information About Cookies

When a user visits a published web application, a combination of cookies are used for storing authentication and session information.

The following cookies are used to store information about sessions, visits and authentication. The information we observe about visitor behavior is stored on our servers, not in the cookie placed on the browser. The cookies we use are usually an anonymous unique identifier, which provides a means of determining whether a visitor has visited the application before but does not provide any means of identifying the visitor. None of the cookies contain personally identifiable information, although, in accordance with standard HTTP protocol, the visitor’s IP address is passed to our servers as part of the HTTP request. All cookies are secured with encryption and sent over HTTPS. The following table describes the cookies that are saved to the browser of visitors visiting a published application.

Name Description
JSESSIONID

The JSESSIONID cookie is a transient cookie used for session management. This cookie only contains a session identifier. The cookie does not contain any personal details.

OAMAuthnCookie

The OAMAuthnCookie cookie is generated by Oracle Access Manager for all clients using an Oracle Cloud service. A valid OAMAuthnCookie is required for a session.

  • Authenticated User Identity (User DN)

  • Authentication Level

  • IP Address

  • SessionID

  • Session Validity (Start Time, Refresh Time)

  • Session InActivity Timeouts (Global Inactivity, Max Inactivity)

  • Validation Hash

Removing the cookie will cause the user to be logged out. The user will need to re-authenticate the next time the user requests a protected resource.

X-AppBuilder-SessionId

The X-AppBuilder-SessionId cookie is a persistent cookie that expires 24 hours after it is created and contains a unique user ID (UUID) and time stamp. This cookie is only used to store visitor behavior information across sessions for billing purposes. This cookie is used for published classic applications.

Removing the cookie might result in each new session being recorded as a new visit.

VBCS_METRICS_<app name>_<app version>

This cookie is a persistent cookie that expires at midnight on the day it is created and contains a time stamp. The purpose is help count unique visits, and to ensure that multiple visits by the same user between when the cookie is created and when it expires are counted as one unique visit. If the cookie is removed before it expires, a new cookie is created on the next visit and the visit will be counted as a new unique visit. This cookie is only used for internal metrics and is not used for billing purposes.

This cookie is used for staged and published visual applications.