Oracle Fusion Technical

Visual Builder Studio

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
• Deploy

How Can Visual Builder Studio Help Me Extend My Oracle Cloud

Application?
• 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.

What Are the VB Studio Building Blocks?

To access VB Studio, you must have one of two roles:
• DEVELOPER_ADMINISTRATOR - Also known as an organization administrator, users
with this role can create and set up an instance of VB Studio, manage all projects, manage VM
executors and executor templates, and update the organization's details. Because this role is so
powerful, it should be granted sparingly.
• DEVELOPER_USER - Users with this role can create and access VB Studio projects, and
create things like wikis, tracking issues, and much more.

How to Verify Whether a Page Can Be Extended Using Visual Builder Studio
If you see the Edit Page in Visual Builder Studio option in Settings and Actions menu of a page, that
means you must use Visual Builder Studio to make changes to that page. If you don't see the option,
that means the page can't be modified using Visual Builder Studio.

All you have to do is click the link to jump over to the Designer in VB Studio, where you can start
customizing your App.
You can create a project, open a shared project, or open a project you're a
member of.
Create Project
What Is a Project?
A project collects all the people, tools, and processes you need to complete a unit of work in VB
Studio.
▪ On the Organization page, click + Create.

▪ On the Project Details page of the New Project wizard, in Name and Description, enter a
unique project name and a project description.
▪ In Security, select the project's privacy:
• Select Private to restrict access to project members only.
Select the Discoverable checkbox to allow organization members that aren't org admins or project
members to see basic information, such as name and owner contact information, about your private
project. Private projects that aren't discoverable won't be exposed to non-members.
• Select Shared to make the project code, wiki docs, tasks, and builds available to anyone
inside your organization.
▪ Click Next.
 ▪ On the Template page, select Empty Project, and click Next.

▪ On the Project Properties page, from Wiki Markup, select the project’s wiki markup
language.
Project team members use the markup language to format wiki pages and comments.
▪ Click Next.
 ▪ On the Team page:

a. Click Add Members and select users or groups to add to the project, from the list displayed, if
you know they may work in this project.
b. Select the membership (Project Owner, Developer Full Access, Developer Limited Access, or
Contributor) that the members you're adding will have in the project:
c. Click Add.
d. Repeat substeps a, b, and c for different users and groups with various membership types, if
needed.
▪ Click Finish.
 What Are Project Memberships?
Here's what you can do in VB Studio pages, depending on your project membership status:

This project
membership... Enables a user to:

Organization Access and manage all projects of the organization, and set connections to OCI and OCI
Administrator Classic.
Note:In any project, an organization administrator can assign himself or herself the Project
Owner role. This will grant them the same project permissions as any other project owner.
An organization administrator can't even open a project unless they are a member and, even
then, it is the project membership type that determines their project permissions.
Individuals that head up organizations and members of the IT department are assigned this
membership. The individual that creates the service instance is automatically assigned this
membership.

Project Owner Access all components of the project and perform project management and administrative
tasks, such as adding or removing Git repositories, managing project users, assigning default
reviewers, and configuring Webhooks.
Project managers and team leaders are assigned this membership. The individual that creates
the project is automatically assigned this membership.

Developer Access most components of the project, but has restricted project management or
administrative actions.
Senior developers are assigned this membership.

Developer Limited Access some components of the project, but has restricted job configuration, environment
management, board management, project management, and administrative actions.
Junior developers and members of the QA team are assigned this membership.

Contributor Access the project's components in read-only mode but can enter comments, update issues,
view wikis, and download build artifacts.
Usually, new developers, technical writers, and other members are assigned this
membership.

Non-member Access the same things as the Contributor membership, but for shared projects only.
 Check Your Project Membership
To see what membership you have for a project, sign in to VB Studio and click the project’s name:

To discover Do this:

If you’re the In the branding bar, click the user avatar, then click Contacts. If you see your name listed
organization under Organization Admins, you’re assigned the Organization Administrator role.
administrator You could also check by selecting Organization in the navigation menu and
displaying the Organization page. If you see a series of tabs (Projects, OCI Account, Build
Executor Templates, Build Executors, Component Exchange, Groups, Properties,
Activities), you're an organization administrator. If you only see a list of projects, you've
been assigned some other role.

Projects you own On the Organization or Project Home page, click the Owner toggle button.

Projects in which On the Organization or Project Home page, click the Member toggle button.
you’re a member

Your project 1. In the left navigator, click Project Home .

membership status 2. On the right side of the page, click the Team tab.
If you see the Owner tag next to your name, you’re a project owner. If you don’t see
the Owner tag next to your name, you’re a project member. The Developer, Developer
Limited, or Contributor tag next to your name indicates your project membership. If you
can’t find your name, you’re a non-member.
For example, in this graphic, Alex Admin is a project owner, Clara Coder is a Developer
Limited, and Don Developer is a Developer:
What Can I Do at the Project Level?
The actions you can perform in VB Studio depend on your project membership status.
Note:
In any project, an organization administrator can assign himself or herself the Project Owner role.
This will grant them the same project permissions as any other project owner. An organization
administrator can't even open a project unless they are a member and, even then, it is the project
membership type that determines their project permissions.
Here's what you can do in VB Studio pages, depending on your project membership status:

Project Developer
Action Owner Developer Limited Contributor Non-member

Git Repository

Create, edit, or delete a

Git repository

Push commits to a Git

repository

Clone and read files from

a Git repository

Maven Repository

Write or upload files to

the Maven repository

Read files from the

Maven repository

NPM Registry

Read packages from the

project's NPM registry
 Project Developer
Action Owner Developer Limited Contributor Non-member

Publish packages to the

project's NPM registry

Snippets

View snippets

Create, edit, and delete

snippets

Merge Requests

Search and view merge

requests

Add comments to merge

requests

Create, merge, and close

merge requests

Add and remove

reviewers

Add and remove linked

issues

Add and remove linked

builds

Start linked builds

Issues
 Project Developer
Action Owner Developer Limited Contributor Non-member

Search and view issues

Create and edit issues

Agile

View boards (backlog,

active sprints and issues,
but not reports)

Create, copy, and edit

one's own boards

Copy and edit boards

owned by others

Delete one's own boards

Delete boards owned by

others

View sprint reports

Wikis

View wiki pages

Add comments to wiki

pages but cannot change
page content

Create, edit, and delete

wiki pages
 Project Developer
Action Owner Developer Limited Contributor Non-member

Builds

View builds

Run builds and receive

build notifications

Create, configure, and

delete jobs

Create, configure, and

delete pipelines

Environments

View environments

Create, configure, and

delete environments

Add and remove instances

Workspaces

View workspaces

Add and manage

workspaces

Releases

View releases
 Project Developer
Action Owner Developer Limited Contributor Non-member

Create, edit, and delete

releases

Docker

View a Docker registry

Write to a Docker registry

Projects

Access to project
administration pages for
all features, team
administration

After creating a project, you can add users

Request Membership in a Project You Can't Access

https://docs.oracle.com/en/cloud/paas/visual-builder/visualbuilder-manage-
development-process/request-membership-project-you-cant-access.html
Set up environments and manage the projects.
Crate Environments
▪ In the left navigator, click Environments

▪ Click Create (or + Create Environment if the page is empty).

▪ In Environment Name, enter a unique name and, in Description, enter a description.

▪ Click Create.
▪ In the Service Instances tab, click + Add Instance.

▪ In the Add Service Instance dialog, select the type of service instance: Visual Builder and
Oracle Integration, Oracle Cloud Applications, or Infrastructure Services.
From the Environments page, you can:
• Create and delete environments
• Add or remove service instances from existing environments
• Update the details of the environment
The Details tab displays details, such as name and description, for the selected environment. You
can also instantly see the health of all service instances comprising each environment right on the
Project Home page or on the Environments page.
• View the details of an environment's service instances
The Service Instance tab captures information, such as the health of and response times for service
instances and their URLs, for each environment in a single place, so you won’t have to hunt for it
later.
• Upload and remove an environment's trust certificates
The Certificates tab shows trust certificates that you upload to connect with external services in an
environment, allowing all applications that use that environment to communicate with those
services.
• View deployments
The Deployments tab shows deployments for extensions and visual apps. Use the Application
Extensions toggle to show deployments for all projects associated with this environment or use
the Visual Applications toggle to show deployments for the current project only.
• Manage the lifecycle of deployed extensions
Click the Extension Lifecycle button to centrally manage extensions deployed across
environments (and across projects). On the Manage Extension Lifecycle page, you can deploy an
already published extension to a new instance, and delete extensions when no longer needed. You
won't see the Extension Lifecycle button if you haven't yet added an Oracle Cloud Applications
instance to your environment
What Is a Workspace?
▪ 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.
▪ 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 extension. Before you can use the Designer to create an App UI
or configure an Oracle Cloud Application, you must first select or create a workspace, which
defines:

• The Git repository where your files will be stored. Physically,

you work within a copy of the Git repository, called the local
repo, and push your changes periodically to the remote repo,
which belongs to the project you’re working within.
• The branch containing the source files you want to use.
• The Oracle Cloud Applications environment where you plan
to publish your extension.
• A sandbox, if you’re using one, which contains data model
changes that haven't been published yet. (The data model
changes that have been published are already available to your extension.)

▪ On the Organization page, select the project where you want to create aApplication
Extension.
▪ In the VB Studio left navigator, click Workspaces .
▪ On the Workspaces page, click New, then select New Application Extension.
What is an Extension?
▪ Extensions are what you use to deliver new capabilities into Oracle Cloud Applications.
▪ The changes you make to your Oracle Cloud Application in VB Studio are stored in an artifact
called an extension. Physically, the source files associated with the extension are stored in a Git
repository. When working on an extension, the best practice is to have only one extension for
the base app ( the Oracle Cloud Application you're extending) in the project, and to store the
source files for the extension in the same Git repository in the project. Multiple developers can
work together to develop the extension, but they should all be working from the same
repository.
▪ 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.

▪ In Git Repository, choose between creating a new repository where you and others can
work on the visual application and using a private scratch repository that is visible only to
you.
o To create a new repository for your visual application, click Create new repository,
then enter a repository name and working branch name.
o

o To use a scratch repository for your visual application, click Use scratch
repository (selected by default).
▪ Click Create.
 What is App UI?
simply an application that includes a user interface component in the form of Visual Builder pages
and flows.

A single extension can contain:

• Configurations you make to one or more Oracle Cloud Applications, and/or;
• One or more App UIs that you create, and/or;
• One or more resources that you want to contribute to the Oracle Cloud Application
ecosystem, like a service connection, image, CSS (Cascading Style Sheets), or JavaScript
function.
What Parts of the UI Can I Modify?
The base application developer (at Oracle) who created your Oracle Cloud Application made certain
elements of the app's UI eligible for customization. You customize these elements in your app
extension by modifying the dynamic components and the UI components and elements the dynamic
components contain. Dynamic components are clearly indicated in the VB Studio UI, so you know
what you can extend and what you can’t.
There are other elements used in dynamic components you might also need to modify when
extending them. For example, adding a button to a dynamic component might involve:
• Modifying a rule set to control when the button is displayed;
• Modifying a template to control how the button is rendered;
• Creating an action chain to define what the button does;
• Creating variables used in the action chain.
What are Dynamic Components?
▪ 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 can't add
them yourself.
▪ 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, Every dynamic table and form in your app extension is bound to a layout
dynamic form 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.

Watch this video to see how dynamic components work:

https://www.youtube.com/watch?v=A_7rKAKR2jw&t=47s

Dynamic Dynamic containers are pre-defined areas in a page that can be used to display
container 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.
 What Is the Designer?
▪ VB Studio includes the Designer, a declarative development environment that you use to
create visual applications or to customize your Oracle Cloud Applications through extensions.
▪ For example, you may want to extend an Oracle Cloud Application so that certain fields are
displayed only for managers, while the same fields are hidden from your users that aren't
managers.
▪ Much of what you do in VB Studio is within the context of an extension, and almost everything
you do within an extension takes place within the Designer. The Designer is divided into five main
areas:

1. Header
2. Navigator
3. Canvas/Editors
4. Properties pane
5. Footer
 The Header
The header contains information about your current VB Studio session, as well as access to the tools
you need to move your extension through the development process.

Here's what each element does:

Label Element Description

A Workspace The name of your current workspace, which defines all the resources you
need to create an extension.
You may have several active workspaces at any one time, one for each
discrete body of work you’re responsible for. To switch to a new
workspace, just click the workspace name and pick a new one.

B Git VB Studio stores all the files for your extension in a Git repository. If you’re
repository/branch working with multiple people on the same extension, you’ll all work within
the same repository, possibly—but not necessarily—in separate branches. If
you see a yellow dot in the header next to the repository name, that means
there are uncommitted changes in your workspace.
Click the repo name to see a list of commands you can use while working
with your repository.
If you don’t know much about Git repositories, this video can help you
learn the basics, or read through Manage Your Extension with Git.

C Undo Undo one or more of your changes. To undo your most recent change,
click the Undo icon (hover your cursor over the icon to view the action
that will be undone). To undo multiple changes, click the Undo drop-
down list and select the actions you want to undo. For example, selecting
the Insert Heading action in this image will remove the heading and undo
other changes you made after adding the heading:
Label Element Description

Tip:You can undo up to 10 of your changes at a time (your last 500 actions
are stored in the browser and will be lost if you clear the browsing cache).
To undo more than 10 actions, simply undo a few items, then open the
drop-down list again.

D Redo Redo one or more changes after undoing them. To redo your most recent
change, click the Redo icon (hover your cursor over the icon to view the
action that will redone). To redo multiple changes, click the Redo drop-
down list and select the actions you want to redo. For example, selecting the
Set text of Heading action in this image will revert two of the previously
undone actions:

E Sandbox If you require any underlying data model changes, you should use
Application Composer to make them first in a sandbox, then use the Edit
Page in Visual Builder Studio option to expose those changes in the UI
with VB Studio.
Label Element Description

Click the sandbox name to associate a new sandbox with your workspace.
You might want to do this if another sandbox contains the data you need for
the extension you’re working on. See Switch a Sandbox.

F Feedback Submit your feedback about VB Studio to Oracle.

G Go to File Search your project's sources by file name. When you first click Go to File,
your most recently used files show. If the file you're looking for isn't listed,
start typing the name of the name in the search box, then select the file you
want in the suggestions.

H Preview Before committing your changes to the branch, you can use the Preview
action to see how your pages look and behave in a browser.

I Publish Commit changes in the current branch to your local repo, push them to the
project's Git repo, and kick off package and deploy jobs to publish your
branch to your development environment. (If you want to publish the
entire extension, make sure you commit and push changes in all other
branches before clicking Publish.)

J Menu Open a menu containing the Share, Import, and Export actions, as well as
commands for opening the Settings editor and navigating to the Visual
Builder Studio Help Center.
 The Navigator
The Navigator helps you move between the artifacts in your extension, and provides access to the
VB Studio editors:

Icon Element Description

App UIs There's a lot going on in this section of the Navigator. You can:
• Create an App UI, if you want to add new pages to your extension;
• Create a fragment, if you need a reusable piece of UI you can use in App
UIs or configurations of App UIs (or within a layout template);
• Create a root page to brand the pages in your App UI with a common
header, footer, background, or other elements, to provide a consistent
look and feel.
• Import resources into the Global Resource folders to use across your
extension, or;
• Add another extension as a dependency, so you can refer to its App UI's
service connections, Layouts, global resources, and so on from your own
App UI, or so that you configure an App UI to meet your own business
needs.

Layouts A Layout represents a set of data fields that can appear in one or more related
dynamic components, like a table or form. Create a new Layout here by
choosing a data source, then defining the rule set that governs how that data
looks and behaves. You can also view the Layouts provided by any App UI you
may have as a dependency.

Services To access external REST APIs in your extension, you can create connections to
the services that provide access to these API endpoints.
VB Studio also includes a catalog of predefined services in the form of an Oracle
Cloud Applications backend. This backend exposes REST APIs—from Human
Capital Management, Sales, and more—that your App UIs can consume right
out of the box. You can also create custom service connections to access services
Icon Element Description

that aren't listed in this catalog. See Add Service Connections to Your
Extension for details.

Dependencies When you add an extension as a dependency, you gain access to the resources
that comes with the extension, like its service connections, Layouts, and more.
Add a dependency when you want to configure one of the App UIs contained
within the extension, or when you want to use the extension’s resources to
build your own App UI.
The Dependencies panel shows you all the extensions containing an App UI
that has at least one artifact flagged as extendable—a dynamic component, a
variable, and so on. If an extension doesn’t have an extendable App UI, it won’t
appear in this list.

Components The Components tab helps you to install and manage the components that you
download from the Component Exchange, a repository of components that can
be installed in your VB Studio instance.

Translations To ease with translation, all text strings in an App UI—such as headings, labels,
and messages—can be stored in a separate external file, rather than hard-coded
in the App UI. This means that you can translate the App UI by simply
downloading this file, translating it, and uploading a newly translated file.

Source Although the Designer is primarily a visual editor, you can always work in
source code if you prefer.

Git Shows you the list of files you've changed, but haven't yet committed to your
branch. If you have merge conflicts in your branch, you'll see them listed here.
Click a conflicted file to open it in the conflict resolver tool so you can resolve
any issues.
By default, the App UI section displays only artifacts that you can extend, but you can use the options
menu next to the Filter field to select items that have already been extended, or items available for
extension:

The Canvas/Editors
The canvas, which appears to the right of the Navigator when you open a page, is where you do the
bulk of your work in VB Studio. When you open a page, you'll see different editors along the top to
help you modify and create artifacts used in the page, like Page Designer, Actions, Event Listeners,
and so on:
Depending on which aspect of the page you're customizing or building, VB Studio invokes the
proper editor to provide the experience you need, and displays that editor in the canvas. Perhaps the
most important editor is the Page Designer, described in detail in Use the Page Designer.
All of the changes you enter through the editors—the Page Designer, Actions, Event Listeners,
etc.—are saved as JSON, which you can access through the JSON pane, next to Settings. In
addition, you can use the JavaScript pane to enter any custom functions you may need for your App
UI.
Note:
The JSON and JavaScript panes represent what will ultimately be checked into Git when you publish
your extension. Therefore, if you look at these panes for an App UI you have added as a
dependency, you won't see anything there—unless you have customized that App UI in some way.
Tip:When working with multiple artifacts (pages, flows, layouts, and so on), each artifact opens as a
separate tab on the tab bar. Here's how you can better manage these in your work area:
• Right-click a tab to see options to close the particular tab, close other tabs, close tabs to the
right, or close all tabs. You can also use this menu to select a particular tab in the Navigator:

If the tabs overflow available space on the tab bar, click at the edge of the tab bar and select the tab
you want to open. Note that the active tab always stays in focus.
• Right-click the empty space on the tab bar and select the option to reopen closed tabs.
Recently closed tabs are saved in session history, so you can keep reopening tabs until you get
to the one you want.
The Properties Pane
As the name suggests, the Properties pane lets you specify the properties that control the appearance
and behavior of whatever is currently selected in the canvas. While you're in the Variables editor, for
example, you use the Properties pane to set the variable's default value, type, and other attributes.
When you click a component on a page in the Page Designer, the Properties pane is immediately
updated to reflect the component's properties. Depending on the component, the Properties pane
might display additional tabs for modifying the component’s attributes or its behavior.
When you add a collection component to the canvas, like a table or list, you'll see a Quick Start tab
added to the Properties pane:

Quick Start wizards help you add some actions and components that are typically associated with the
component, such as mapping the collection to data and adding Create and Detail pages.
To hide or show the Properties pane, just click the tab itself.
The Footer
At the bottom of the Designer, you have several tools that can help you debug and streamline your
extension:

Element Description

Audits Scan the code in your extension for places containing errors, warnings,
info and to-dos. Your code is scanned when you open the Audits pane.

Find in Files Search your extension for a text string.

Git History View a list of Git actions you have performed in your workspace. The
window displays details about each action, including the type, date and
files involved.

Logs View build logs when your extension is shared or deployed.

Tests View a list of all action chain tests.

Color Theme
The Designer, by default, uses a light theme based on Redwood to set the color palette for your
work environment. To personalize your environment to use a dark theme or sync with your OS
settings:
1. Click Menu in the upper right corner.
2. Select Theme, then choose an option:
 • Select Dark to use a dark color display, more suited for low-light conditions. This
option switches the background and text used in all the editors, except the Page
Designer canvas, where application pages continue to display against a lighter
background with dark text.
• Select OS Default to inherit the theme used in your operating system's settings. If your
system settings are configured to use dark mode, the Designer will also use those
settings.
• If you changed the default, select Light to switch back to a lighter background with
dark text display.
Tip:
You can also control this setting from your preferences. Click Go to project page, click your
avatar, select Preferences and General, then look for the Preferred color theme setting. See Set
Your Preferred Color Theme.
No matter where you configure this setting, your preferred color theme takes effect for all pages in
the user interface, including the Designer.
Create Service Connection