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 with application extensions.
Which Extension Guide Should I Use?
You may have noticed that the Visual Builder Studio library contains two extensions guides: the one you're currently viewing, as well as Extending Oracle Cloud Applications with Visual Builder Studio. Determining which book you need depends on if you are extending an older or newer version of your Oracle Cloud Application.
This guide is for you if you are still using an older version of an Oracle Cloud Application (22B and earlier), and still use "classic" application extensions to extend it. Classic application extensions are not supported on newer versions of Oracle Cloud Applications. To edit a classic application extension, you'll need to log into VB Studio and then open the workspace for the extension. For details on how to start editing a classic application extension, see Open Your Extension.
If you are using a newer version of an Oracle Cloud Application (22C and newer), you need to use the Extending Oracle Cloud Applications with Visual Builder Studio guide. A good place to start is The Basics chapter.
To determine if you are using a newer version, view your Oracle Cloud Applications page, click the Settings and Actions menu in the upper right corner, and then click Edit Page in Visual Builder Studio:
- If VB Studio opens in a new tab in your browser and your view of the Designer looks something like this, then you're using a newer version of a Cloud Application:
Description of the illustration brandnewworkspace.png - If a new tab opens and you see a message like this, you can no longer use the older version of your Cloud Application, and you'll need to open the newer version of your Cloud Application:
After opening the newer version in your browser, try clicking Edit Page in Visual Builder Studio again to open the extension in VB Studio.
Note:
If you don't see the Edit Page in Visual Builder Studio option in your Settings and Actions menu, that means your Oracle Cloud Application was not built using Visual Builder Studio and Oracle JET (JavaScript Extension Toolkit). In that case, you should use Configuring and Extending Applications to help you both add data to your data model, as well as to surface those changes in the user interface.Migrate Your Extension to the New Version for 22C
Oracle Cloud Applications that have been updated to 22C use a new structure for developing and registering extensions. App extensions built for version 22B and earlier won't work after your Oracle Cloud Application base app has been updated to 22C.
To use an extension after your Oracle Cloud Application has been updated 22C, you'll need to use Visual Builder's migration tool to convert your app extension to an extension that uses the new structure. After your extension is converted, you can re-deploy it to your 22C Oracle Cloud Application. For more on creating, developing and publishing extensions for 22C Oracle Cloud Applications, see The Basics chapter in Extending Oracle Cloud Applications with Visual Builder Studio .
Let's take a look at the basic workflow for migrating an extension. If you've created an extension for your 22B Digital Sales app, you most likely have published it to the TEST instance, and possibly the PROD instance, of your Oracle Cloud Application. When upgrading instances to 22C, Oracle will starting by updating your TEST instance. When your TEST instance is updated, Visual Builder will prompt you to migrate your extension to an App UI extension, and you'll have a few weeks to convert and test the migrated extension to make sure everything works on your TEST instance. This way, when you PROD instance is updated to 22C, you'll have an App UI version of your extension ready to publish to your PROD instance.
The Visual Builder migration tool will migrate your app extension to an App UI extension for you, but there are a few things you'll need to do to help make sure the process runs smoothly.
- Log into Visual Builder Studion and open your workspace.
If the workspace contains an extension, you'll know your Oracle Cloud Application base application has been updated to 22C if:
- You see a Migrate notification at the top of your workspace, and
- You can't see your extension in the Designer (because it cannot be rendered in the updated base app).
If your base application has been updated to 22C, step through the following steps to start the migration process for your extension.
- Create a new branch for your migrated extension.
- If there are active branches, you'll need to migrate them, although without publishing. You can also choose to create a new Git repository for the new extension.
- Select the Git repository that has your app extension. We'll assume you are using the main branch in your repository.
- Create a branch off main to create a v1 branch (you can use this for any hotfixes you might need to make to your classic extension in the production while testing the new extension).
- Create a new branch (for example, mymigration) off main for the migrated extension.
- Switch to your new mymigration branch in your workspace.
- Click Migrate in the Migrate notification.
- Open the Workspaces page, then click Clone from Git to create a new workspace.
In the Clone from Git dialog box, select the branch with your migrated extension.
Click Create.
- Open the new workspace.
You can now see the migrated extension in the Designer.
When you are ready, you can publish the extension. Publishing will merge your changes in the branch back to main.
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. It makes it easy for your entire team to develop the artifacts they need, including:
- Oracle Cloud Applications developers, who need to extend their applications with business-specific customizations;
- Low-code developers, who want to create applications using a visual designer;
- Experienced programmers, who want to modify the source code for applications created by others, or to develop bespoke apps using the web programming language of their choice.
With VB Studio you get:
- 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 JavaScript Extension Toolkit (Oracle JET)), also within a Git framework
- 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
- 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 (Redwood is Oracle’s next generation user experience design system) 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 Studio 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, by manipulating the dynamic forms and tables that appear on your Oracle Cloud Application’s pages.
The Designer's rule set editor lets you create and edit the rules that determine what is displayed in a dynamic form or table. 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 Extension?
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.
Here are the key components of the VB Studio ecosystem as it pertains to 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 extensions for an Oracle Cloud Application, like Digital Sales, and another project for building a bespoke application your own department will use. 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 to have a project dedicated to a single Oracle Cloud Application, so that all work for that App is stored in the same Git repository. When setting up a workspace, developers working on the extension should clone the project's Git repository and begin working from there.
- When you work on an 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 extension.
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 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 or test environment where you plan to publish your app, and, in certain cases, a sandbox, which contains data model changes made to the app which haven't been published yet. 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 can publish your app to an environment manually from your workspace, 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 main branch.
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 a) merge them to the project's Git repo, b) choose to Share them with others for testing, or c) deploy them. 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, for example, a sandbox defining an alternative data model that is being considered, 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 selecting a sandbox for a new workspace, or when switching the sandbox used with a workspace, VB Studio will indicate if any of the available sandboxes created in App Composer are "unpublishable". If a sandbox is unpublishable, you won't be able to publish it when you publish your app extension. Using an unpublishable sandbox in your workspace increases the risk that your app extension might not work correctly when you publish it because the sandbox might be out of sync with your Oracle Cloud Application's data model.
In your Workspaces page, you'll see a note in the Current Sandbox column if any of the sandboxes you're using with your workspaces are unpublishable.
If you open a workspace that uses an unpublishable sandbox, you'll see a lock icon in the header next to the sandbox's name. Also, in the dropdown list of your workspaces, if any of your workspaces use a sandbox that is unpublishable you'll see a lock next to the sandbox name.
VB Studio will display a notification if the sandbox you're using with your workspace has changed (for example, it was published or deleted). The notification will contain a description of the change, and suggest what you should do. In this image, the notification displays a message that the sandbox associated with the workspace should be refreshed because of changes in the application's environment.
In this case, the notification box contains a Refresh button you can click to refresh your sandbox. For more about working with sandboxes in Oracle Cloud Applications, see the Sandboxes section in Configuring and Extending Applications.
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 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.
Note:
You can't add new pages to your Oracle Cloud Application using classic application extensions. However, if your Oracle Cloud Applications instance is version 22B or newer, you can add pages by creating an App UI. To do this, follow the steps to Create an Extension and Create an App UI in Extending Oracle Cloud Applications with Visual Builder Studio.
After extending your application with the App UI, you can create links to the new pages from your classic application extension.
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, dynamic form |
Every dynamic table and form in your app extension is bound to a layout 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: Video: Work With Dynamic Components |
| 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:
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 customize 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 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 of commands for working with your repository. |
| 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: 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.
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. |
| F | Feedback | Submit your feedback about Visual Builder Studio to Oracle. |
| G | Go to File | Search the Git repository by file name. |
| H | Preview / Debug Preview | Open a new tab in your browser to preview the current page in the default preview mode. You select the default preview mode in the menu.
|
| 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. |
You use the Navigator on the left of the Designer to navigate the artifacts in your app extension.
The Application Extensions pane in the Navigator contains two types of artifacts:
- A layout represents a set of data fields that can appear in one or more related dynamic table or form components. 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 layouts for the application in the Navigator under "Layouts". Clicking a layout opens a new window containing tabs for editing its artifacts, such as its rule sets, fields and templates.
- Beneath the Layouts node, the extendable pages are grouped by their page flows under "Application". 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.
By default, the Application Extensions pane only displays artifacts that you can extend, but you can use the options menu next to the Filter field to select the filter: All Items, Extendable Items Only, or Extended Items Only.
The Page Designer, which appears to the right of the Navigator when you open a page, contains the canvas that displays your app extension pages and a Properties pane. In this image, you can see an app extension page with several dynamic components. Because none of the components are selected, the Components tab in the Properties pane on the right lists all the dynamic components in the page. The Properties pane also has a Constants tab listing editable constants used in the page.
When you hover your cursor over a dynamic component on the canvans or in the Properties pane, it is outlined in green on the canvas and a tab is displayed at the top identifying the type of component. Here the cursor is hovering over a dynamic container in the page.
You select a component by clicking it on the canvas or in the Components tab. In this example, a dynamic form has been selected in the page. The form's Properties pane shows that it uses the Account Hierarchy Card Layout rule set in the accounts Layout, and that the active layout is determined by the display logic. You can edit some component properties directly in the Properties pane, but for others, like dynamic forms and tables, you'll need to click the link in the Properties pane to open a dedicated editor.
The left edge of the Page Designer has three collapsible panes that you can use to navigate and modify editable components in the canvas. The Components palette lists components that you can drag into editable components, such as dynamic containers. Services that have been marked as extendable in the base app are listed in the Data palette. When a service is listed in the Data palette, you can access them in your page by binding the service to dynamic components in dynamic containers. The Structure view provides a structural view of the components in the canvas you can modify. This can help you locate and select specific components in the page.
The Designer also lets you work in source code, if you prefer. In the Page Designer toolbar, you can click Code to switch from the default Design view to the code editor and see the page's source. You can also click Source in the Navigator, which opens a tree list view of the files in your application extension:
To see a list of files you've changed, but haven't yet committed to your branch, click Git in the Navigator. If you have merge conflicts in your branch you'll see them listed here. In the Git pane you can click files with conflicts to open them in the conflict resolver tool and resolve the conflicts.
At the bottom of the Designer, 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. |
| Tests | View a list of all action chain tests. Action chain tests are not supported for app extensions, so this panel will not display any items. |
| 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. |
How Do I Customize and Publish an App Extension?
VB Studio provides all the tools you need for managing the development lifecycle of your app extension.
Here's the typical process for customizing and publishing an application extension:
- Log in to VB Studio.
- Open the Workspace for your application extension.
- In the Application Extensions pane, click the page you want to customize to open it in the Page Designer.
- 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 Components tab in the Properties pane on the right. The Constants tab in the Properties pane lists the extendable constants used in the page.
When you select a component (on the canvas, in the Properties pane or the Structure view), you'll see some of the component’s properties in the Properties pane. You use the Properties pane to view and edit properties, and to navigate to other editors. For example, if you look at the properties of a dynamic form in the Properties pane, 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.
- View your changes with the preview tools.
Use the Layout Preview in the Properties pane when editing a page to check your layouts in the Page Designer, and Preview in the Designer header to see your changes as they will appear in the page in a browser.
- 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.
- 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.
- 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.
- Merge your branch into the main repository.
When your changes have been reviewed and approved, you can merge your branch into the main repository. The administrator can configure the project so that merging changes to main 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.
Upgrade Runtime Dependencies
In VB Studio, runtime dependencies refer to a set of client-side libraries that, along with the accompanying version of Oracle JET, determine features and other improvements available to your application extension, like what JET components you can use. When your app extension was created, sets its runtime dependency version was automatically set to the Visual Builder runtime version of the base app. For more about runtime dependencies in Visual Builder, see Manage Runtime Dependencies in Building Responsive Applications with Visual Builder Studio.
In most cases, VB Studio will migrate the app extension's runtime dependency version in your workspace when the base app release is updated. To see the runtime dependency version of your base app, click Menu in the upper right corner, then select Settings:
A notification will appear in the Designer prompting you to migrate your app extension's dependencies if they need to be migrated to a newer version and VB Studio hasn't migrated it automatically. It's recommended that you migrate the runtime dependencies when prompted to take advantage of improvements provided by newer releases.
Note:
You can't migrate your app extension if you have any uncommited changes. You'll need to either commit or revert your changes before you can migrate your app extension to the newer version.When your app extension is migrated to a new release, VB Studio makes changes to your app extension to better align it with the upgraded release. We may, for example, address deprecated properties or move things from one file to another. You'll see details of all the changes made to your app extension during the migration, so you know exactly what happened behind the scenes. If your app has syntax errors, however, you'll need to fix those issues—conveniently flagged for action in the upgrade dialog—before you can upgrade. Here's an example of what you may see when a migration succeeds:
Immediately after migration, if you decide you don't want the upgrade, you can use the Undo icon in the header to roll back all the changes, though upgrading is the recommended course of action.