1 How Do I Use Visual Builder Studio to Extend Oracle Cloud Applications?

Your Oracle Cloud Applications are built using Oracle Visual Builder Studio and Oracle JET components. You can use these same tools to customize Oracle Cloud Applications by creating an application extension.

What's 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.

How Can Visual Builder Studio Help Me Extend My Oracle Cloud Application?

VB Studio provides tools to help you work with your team members to develop an application extension and manage the entire development lifecycle, from creation to publication. VB Studio can help you and your team members:

  • Create new application extensions and edit existing ones.
  • Edit page layouts and display logic using a visual editor.
  • Version the changes made to an extension so you can revert to previous versions, if needed.
  • Collaborate on an application extension, so that both experienced and novice developers can contribute.
  • Participate in the code review process.
  • Test the changes on your Oracle Cloud Application development environment.
  • Share your changes during development and provide feedback.
  • Publish the changes to the application’s production instance.

How Do Visual Builder Studio and Oracle Cloud Applications Work Together?

Configuring and Extending Applications describes how you can use Oracle Cloud Application tools to customize most Oracle Cloud Applications to meet your business needs. However, if you check the Settings and Actions menu while in a "Redwood"-style Oracle Cloud Application and see an option for “Edit Pages in Visual Builder”, that’s your signal that you need to use VB Studio to make your changes to the app’s user interface:

If you require any underlying data model changes, you should use Application Composer to make them first, then use the Edit Pages in Visual Builder option to expose those changes in the UI with VB Studio. For example, you may want to add a new field to a table, or rearrange the fields in a form so that those you care about the most are featured. You can do this using the Designer in VB Studio to manipulate the dynamic forms and tables that appear on your Oracle Cloud Application’s pages.

The Designer's dynamic UI rule set editor lets you create and edit the rules that determine what is displayed in a dynamic component. For example, you may want to display one set of options for a form when the end user has the "manager" user role, but another set of options when the user has a different role. You can create a different layout for each case, then set a rule to apply the correct layout based on the end user’s role.

You can even include other components in your page, for example, images or links, and then define their behavior by creating action chains.

What's an Application Extension?

The changes you make to your Oracle Cloud Application in VB Studio are stored in an artifact called an application extension. Physically, the source files associated with the app extension are stored in a Git repository. When working on an app extension, the best practice is to have only one app extension for the base app ( the Oracle Cloud Application you're extending) in the project, and to store the source files for the app extension in the same Git repository in the project. Multiple developers can work together to develop the app extension, but they should all be working from the same repository. (Your individual work in VB Studio is also referred to as an application extension.)

Here are the key components of the VB Studio ecosystem as it pertains to application extensions:

  • 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 an application extension for an Oracle Cloud Application, and another project for building a bespoke web or mobile application for use by your own department. 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. For details on how to create projects in VB Studio, see Set Up Oracle Visual Builder Studio for Extending Oracle Cloud Applications in Administering Visual Builder Studio.
  • The best practice is for each base app to have only one app extension, and all work on the app extension is stored in the same Git repository. When setting up a workspace, developers working on the app extension should clone the project's Git repository and begin working from there.
  • When you work on an application extension, you do so within the editors provided in the VB Studio Designer. Depending on which aspect of the page you're customizing, VB Studio invokes the proper editor to provide the experience you need.
  • 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 application extension. A workspace provides several important components:
    • Various artifacts, for example, an application extension;
    • A pointer to the Oracle Cloud Application sandbox, which contains any data model changes you may have made;
    • A pointer to the Oracle Cloud Application development or test environment where you plan to deploy your app. 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.
    • Your own clone of the app extension's Git repository, where the source code for your application extension lives. Your work 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.

What Is a Workspace and Why Do I Need One?

A workspace defines the resources available to you when you open the Designer. You can think of a workspace as your editing context while you're working with the Designer.

Before you can use the Designer to create or edit an application extension, you must first select or create a workspace to identify the source files you'll be editing. A workspace defines the repository—and the branch—containing the source files you want to use, the application's development environment, and, in certain cases, a sandbox. The Git repository and development environment must already be set up and defined in the application extension project in VB Studio before you can create a workspace. If the development environment isn't defined, you won't be able to create a workspace.

You're the only one who can access your workspace. Changes to files you make in your workspace aren't visible to other team members until you save them to a branch. You can have multiple workspaces, each with a different branch and sandbox, or you can use one workspace and switch to a different branch and sandbox when you are in the Designer.

Use Your Oracle Cloud Application Sandbox

VB Studio can access the sandboxes in your Oracle Cloud Application that have changes to the application's data model that haven't been published yet.

If the changes in a sandbox are relevant to your app extension, you can associate the sandbox with your workspace so you can access it while you're working on the app extension. You'll want to do all your work in a branch that is associated with the sandbox with those changes, and you'll want to continue to use the same branch with that sandbox until you are finished. If you need to edit the app extension using a different sandbox as well, it's better to associate it with a new branch than to use an existing branch. This will help isolate the changes you make for each sandbox. If it helps, for each branch-sandbox pair you can create a separate workspace instead of switching a workspace's branch and sandbox. VB Studio helps keep your changes in sync by automatically recommending a sandbox for your workspace if you choose a branch that is already using it.

When you are ready to publish your app extension to your Oracle Cloud Application environment, you should publish the associated sandbox at the same time or shortly before to minimize the risk that the data model and app extension will be out of sync.

What are Dynamic Components?

The base application developer (at Oracle) who created your Oracle Cloud Application made certain elements of the app eligible for customization. Those elements can include dynamic components (tables, forms, containers), as well as certain variables, constants, and events. Those items are clearly indicated in the VB Studio UI, so you know what you can extend and what you can’t.

A dynamic component is an extendable UI component, such as a form, table or container, that does not render a static set of fields or content. Instead, a dynamic component uses display logic to determine what the component displays, for example, what fields are displayed in a table and how they are rendered. Display logic is simply a set of conditions that you define. At runtime the conditions are evaluated based on the viewer’s current circumstances (for example, the user's role) to determine what is displayed in the component. The dynamic components that appear in your app are determined by the base app developer at Oracle.

You have two main objectives when customizing a dynamic component: one, to configure the component's content the way you want it using layouts and templates, and two, to define the display logic that determines the layout and templates displayed in the component. In most cases you define the logic first, then configure the content that will be used in your logic.

There are three types of dynamic components that can be used in app extensions: tables, forms and containers. What is displayed in a component and how you customize it depends on what type of component it is:

Dynamic Component Description
Dynamic table, dynamic form

Every dynamic table and form in your app extension is bound to a dynamic UI artifact that represents a data resource. In dynamic tables and forms, you customize which fields are displayed and how they are rendered. In most cases, you can hide, show, or re-order these fields, and can even create new fields based on existing ones. You can also apply field templates to control how certain fields are rendered at runtime.

Dynamic container

Dynamic containers are pre-defined areas in a page that can be used to display various types of content. Unlike a dynamic table or form, which can appear on multiple pages, a dynamic container is scoped to the page and can only ever appear on that page.

Understand the Designer

Let’s take a look at the Designer so you can understand what it offers. In the header, you have:

The following table describes what these header elements are:

Label Element Description
A Workspace The name of your current workspace. Click the workspace name to switch to a different workpace in the project.
B Git repository / branch The name of the Git repository for the base app, and the name of the repository branch currently associated with your workspace. Click to open a menu with a command to switch to a different branch or sandbox, and Git commands for working with your repository.
C Sandbox The name of the current sandbox used in the workspace, if any. Click to open a menu with a command to switch to a different branch or sandbox, and Git commands for working with your repository.
D Undo Undo your most recent change.
E Redo Redo a change after clicking Undo.
F Preview Open a new tab in your browser to preview the current page.
G Publish Publish your app extension.
H Feedback Submit your feedback about Visual Builder Studio.
I Go to File Search the Git repository by file name.
J Menu Open a menu containing the Share, Import and Export actions. The menu also contains commands for opening the Settings editor and navigating to the Visual Builder Studio Help Center.

You use the Navigator on the left of the Designer to navigate the artifacts in your app extension.

The Application Extensions panel in the Navigator contains two types of artifacts:

  • A dynamic UI represents a set of data fields that can appear in one or more related dynamic components, like a table or form. Which of these fields actually appear in a given component is determined at runtime by the layouts defined in a rule set. You can see all the dynamic UIs for the application in the Navigator under "Dynamic UIs". Clicking a dynamic UI opens a new window containing tabs for editing its artifacts, such as its rule sets, fields and templates.
  • Beneath the Dynamic UIs, the extendable page artifacts are grouped under their page flow. When you select a page, a new window for the page opens on the right containing tabs for editing the page's artifacts, including the Page Designer where you can see how the page looks and select and edit page components.

When no component is selected in the Page Designer, the Property Inspector on the right lists the page's dynamic components, as well as other editable items such as constants used in the page. Editable components are outlined on the page in green, and when you select a component on the page or in the Property Inspector its properties are listed in the Property Inspector. You can edit some component properties directly in the Property Inspector, but for others, like dynamic forms and tables, you'll need to click the link in the Property Inspector to open a dedicated editor.

In this example, a dynamic form is selected in the page. The Property Inspector shows that the form uses the Experience Card rule set and that the active layout is determined by the display logic.

By default, the Application Extensions pane only displays artifacts that you can extend, but you can use the Filter options to show All Items, Extendable Items Only or Extended Items Only.

The Designer also lets you work in source code if you prefer. Open the Source View panel in the Navigator to enter this mode and open a tree list view of files in your application extension:

Open the Git Panel in the Navigator to open a tree list view of files you've changed but you haven't committed to the your branch. If you have any merge conflicts in your branch, you'll see them listed here, and you can open the conflict resolver from this panel.

In the footer you have:

Element Description
Audits Scan the code in your app extension for places containing errors, warnings, info and to-dos. Your code is scanned when you open the Audits pane.
Find in Files Search the code in your app extension for a text string.
Logs View the log of messages written by custom code in your app extension.
Tests View a list of all action chain tests defined in the app extension, and the status of each test.

What is the Process for Creating and Publishing an Application Extension?

VB Studio provides all the tools you need for managing the development lifecycle of your app extension.

Here's the typical process for creating and publishing an application extension:

  1. In Oracle Cloud Applications, open the application you want to customize.
  2. Open the Settings and Actions menu, then click Edit Pages in Visual Builder to open the page in the Designer in VB Studio.

    You should take care to make any necessary data model changes before you launch VB Studio.

    If your admin has set things up for you, you automatically land in the correct app extension project for the Oracle Cloud Application. (If you belong to more than one project, you might have to choose.) If this is your first time to VB Studio, we’ll create a workspace for you (assuming your admin has properly set up the app extension project.)

  3. Using the Designer's editors, make the customizations you want to be part of the application extension.

    When you open a page in the Designer, it opens in a new window with several editor tabs. In the Page Designer tab you'll see the page you were just viewing, and you can select dynamic components on the canvas or from the list in the Property Inspector on the right. The Property Inspector also lists constants used in the page.

    When you click a component on the canvas, you'll see some of the component’s properties in the Property Inspector:

    You use the Property Inspector to view and edit properties, and to navigate to other editors. For example, if you look at the properties of a rule set in the Property Inspector, you can see some of its properties and suggestions on what to do next:

    At the top is the Quick Actions panel, which holds a selection of suggested actions, dynamically chosen for each component. Most of the time, you'll want to do one of these. Sometimes you may need to change something that’s not in the Quick Actions. You can find other component properties below the Quick Actions panel.

    When you start editing a dynamic table or form, you'll configure the component's rule set to determine the conditions under which each layout is applied to the page. If none of the conditions apply, the base layout is used.

    You'll see that each rule set has a default base layout that's read-only. You’ll have to duplicate the rule set's default base layout or create a new one to make changes. In the layout you’ve made, you can move, edit and delete the fields displayed in the component, and add any field that’s in your app’s data model. You can also create custom fields that you can use in your layouts.

    When editing dynamic containers, you'll use display logic to determine the sets of components that are displayed in the container.

  4. View your changes with the preview tools.

    Use Layout Preview when editing a page to check your layouts in the Page Designer, and Preview to see your changes as they will appear in the page in a browser.

  5. Share your changes to get feedback.

    It's good practice to ask your team members to review the changes you make to an app extension before you publish it. You can use the Share tool to generate a URL for the app extension preview that you can share with team members so they can test it. If you're working with a sandbox, be sure to give the testers the name of the sandbox along with this URL. If you're not working with a sandbox, simply share the URL.

  6. Commit your changes to a branch.

    You use the Git commands in the menu to commit and push the changes in your workspace to the remote branch. The Publish action can automatically perform this step and the next two steps (create a merge request and merge the branch) for you.

  7. Create a merge request asking team members to review your changes.

    Your team members can review the changes to the source files in the branch and approve the request if they look good. For some projects the merge requests might be optional, but a project owner can make merge requests and reviews mandatory.

  8. Merge your branch into the main repository.

    When your changes have been reviewed and approved, you can merge your branch into the main repository (master). The administrator can configure the project so that merging changes to master will automatically trigger a build job. The build job will create the build artifact that is deployed to the Oracle Cloud Application test environment. After testing, a separate build job will publish the build artifacts to the live application.