Oracle® CloudExtending Oracle Cloud Applications withVisual Builder Studio

F20616-01May 2020

Oracle Cloud Extending Oracle Cloud Applications with Visual Builder Studio,

F20616-01

Copyright © 2020, Oracle and/or its affiliates.

Primary Author: Oracle Corporation

This software and related documentation are provided under a license agreement containing restrictions onuse and disclosure and are protected by intellectual property laws. Except as expressly permitted in yourlicense agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify,license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means.Reverse engineering, disassembly, or decompilation of this software, unless required by law forinteroperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. Ifyou find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it onbehalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software,any programs embedded, installed or activated on delivered hardware, and modifications of such programs)and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government endusers are "commercial computer software" or “commercial computer software documentation” pursuant to theapplicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use,reproduction, duplication, release, display, disclosure, modification, preparation of derivative works, and/oradaptation of i) Oracle programs (including any operating system, integrated software, any programsembedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oraclecomputer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in thelicense contained in the applicable contract. The terms governing the U.S. Government’s use of Oracle cloudservices are defined by the applicable contract for such services. No other rights are granted to the U.S.Government.

This software or hardware is developed for general use in a variety of information management applications.It is not developed or intended for use in any inherently dangerous applications, including applications thatmay create a risk of personal injury. If you use this software or hardware in dangerous applications, then youshall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure itssafe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of thissoftware or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks oftheir respective owners.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks areused under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc,and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registeredtrademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products,and services from third parties. Oracle Corporation and its affiliates are not responsible for and expresslydisclaim all warranties of any kind with respect to third-party content, products, and services unless otherwiseset forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not beresponsible for any loss, costs, or damages incurred due to your access to or use of third-party content,products, or services, except as set forth in an applicable agreement between you and Oracle.

Contents

Preface

Audience v

Related Resources v

Documentation Accessibility v

Conventions v

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

What Is Oracle Visual Builder Studio? 1-1

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

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

Extend Oracle Cloud Applications with VB Studio 1-3

What Is a Workspace and Why Do I Need One? 1-4

Use Your Oracle Cloud Application Sandbox 1-4

Use Branches to Isolate Changes 1-5

Share the Application Extension 1-5

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

2 Getting Started

Open an Application Extension from an Oracle Cloud Application 2-1

Create a Workspace Using an Existing Repository 2-2

Create a Workspace for a New Application Extension 2-3

What is a Scratch Repository? 2-5

Push a Scratch Repository to a Git Repository 2-5

Create Workspace by Importing an App Extension Archive 2-6

Open a Page in Your Application Extension 2-7

3 Create Your Application Extension

How Do I Create an Application Extension? 3-1

Understand the Designer 3-2

iii

Customize Dynamic Components 3-4

Determine What's Displayed at Runtime 3-4

Create a Dynamic Layout 3-6

Define Conditions in a Dynamic Layout 3-8

Add and Group Fields in Form Layouts 3-10

Design Your Pages 3-11

Preview Different Dynamic Layouts 3-11

Store Property Values with Variables and Constants 3-12

Change Constant Values in the Property Inspector 3-13

Edit Variables and Constants in the Variables Editor 3-15

Define the Behavior of Components with Action Chains 3-16

Use Events and Event Listeners to Start Action Chains 3-16

Event Behavior Types for Calling Event Listeners 3-18

Preview Your Application 3-22

Share Your Application Extension 3-22

Export Your Workspace as an Archive 3-23

4 Publish the Application Extension

Review the Process 4-1

Publish the Application Extension 4-2

Publish Changes Without Creating a Review 4-3

Publish Changes that Require Review 4-3

Save Changes to the Git Repository with Git Commands 4-5

How Do I Save My Changes? 4-6

Keep Your Local and Remote Branches in Sync to Avoid Conflicts 4-6

Commit and Push Your Changes 4-7

Create a Merge Request 4-10

Merge Changes From a Branch 4-11

View Your App Extension Deployments 4-12

iv

Preface

Extending Oracle Cloud Applications with Visual Builder Studio describes how to use aweb-based visual development tool to extend Oracle Cloud Applications.

AudienceExtending Oracle Cloud Applications with Visual Builder Studio is intended for OracleCloud Applications users who want to create, edit and publish their applicationextensions.

Related ResourcesFor more information, see these Oracle resources:

• Oracle Public Cloud

http://cloud.oracle.com

• What is Oracle Visual Builder Studio in Managing Your Development Process withVisual Builder Studio

• Set Up Oracle Visual Builder Studio for Extending Fusion Applications inAdministering Visual Builder Studio

Documentation AccessibilityFor information about Oracle's commitment to accessibility, visit the OracleAccessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic supportthrough My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

ConventionsThe following text conventions are used in this document:

Convention Meaning

boldface Boldface type indicates graphical user interface elements associatedwith an action, or terms defined in text or the glossary.

v

Convention Meaning

italic Italic type indicates book titles, emphasis, or placeholder variables forwhich you supply particular values.

monospace Monospace type indicates commands within a paragraph, URLs, codein examples, text that appears on the screen, or text that you enter.

Preface

vi

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

Application extensions in Oracle Cloud Applications are built with Oracle Visual BuilderStudio and Oracle JET. VB Studio has tools for creating, editing and publishing theseextension.

What Is Oracle Visual Builder Studio?Oracle Visual Builder Studio (VB Studio) is a robust application development platformthat helps your team effectively plan and manage your work throughout all stages ofthe app dev lifecycle: design, build, test, and deploy.

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

• Oracle Cloud Applications developers, who need to extend their Apps withbusiness-specific customizations;

• Low-code developers, who want to create web or mobile apps using a visualdesigner;

• Experienced programmers, who want to modify the source code for web andmobile apps created by others, or to develop bespoke apps using the webprogramming language of their choice.

With VB Studio you get:

• Built-in repositories for hosting code in Git and for hosting binaries, such as Mavendependencies

• 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 canmanage changes, apply version control best practices, and collaborate with theirteammates to develop applications

• The ability to build and display different flavors of the UI to meet the needs ofdiscrete users of certain Oracle Cloud Applications (those built with VB Studio andOracle Java Extension Toolkit (Oracle JET)), also within a Git framework

• Agile boards and an issue tracking system for tracking sprints, tasks, defects, andfeatures

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

1-1

How Can Visual Builder Studio Help Me Extend My OracleCloud Application?

VB Studio provides tools to help you work with your team members to develop anapplication extension and manage the entire development lifecycle, from creation topublication. 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 novicedevelopers 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 ApplicationsWork Together?

Configuring and Extending Applications describes how you can use Oracle CloudApplication tools to customize most Oracle Cloud Applications to meet your businessneeds. However, if you check the Settings and Actions menu while in an Oracle CloudApplication and see an option for “Edit Pages in Visual Builder”, that’s your signal thatyou 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 ApplicationComposer to make them first, then use the Edit Pages in Visual Builder option toexpose those changes in the UI with VB Studio. For example, you may want to add a

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

1-2

new field to a table, or rearrange the fields in a form so that those you care about themost are featured. You can use the Designer in VB Studio to manipulate the dynamicforms and tables that appear on your Oracle Cloud Application’s pages. When allowedby the application, you can also edit some of the constants and variables and even thebehavior of some components.

The Designer's dynamic layout editor lets you create and edit the rules that determinewhat is displayed in a component. For example, you may want to display one set ofoptions for a form when the user is based on the West Coast, but another set ofoptions when the user is based elsewhere. You can create a different layout for eachcase, then set a rule to apply the correct layout based on the user’s location.

Extend Oracle Cloud Applications with VB StudioThe changes you make to your Oracle Cloud Application in VB Studio are stored in anartifact called an application extension. Physically, the source code associated with theapp extension is stored in a Git repository off its master branch. When working on anapp extension, best practice is to have only one app extension for the base app in theproject, and to store all the sources for the app extension in the same Git repository inthe project. Multiple developers can work together to develop the app extension, butthey should all be working from the same repository. (Your individual work in VBStudio is also referred to as an application extension.)

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

• Within a single VB Studio instance, you and your team members who use thatinstance are considered an organization. Within your organization, you will likelybelong to one or more projects, each of which is devoted to a discrete softwareeffort. For example, you might have a project for building an application extensionfor an Oracle Cloud Application, and another project for building a bespoke web ormobile application for use by your own department. A project brings together allthe tools you need to create those artifacts, such as a Git repository for storing

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

1-3

your source code, a pipeline to provide continuous integration and delivery, anissue tracking system, team wikis, and more.

• Each base app should have only one app extension, and all work on the appextension is stored in the same Git repository. The workspaces of developersworking on the app extension should all use clones of the same Git repository.

• When you work on an application extension, you do so within the editors providedin the VB Studio Designer. Depending on which aspect of the page you'recustomizing, VB Studio invokes the proper editor to provide the experience youneed.

• All of your work in VB Studio is done in the context of a workspace, a completelyprivate area where you can work on your application extension. A workspaceprovides several important components:

– A reference to the base application, which is the Oracle Cloud Applicationyou're extending;

– A pointer to the Oracle Cloud Application sandbox, which contains any datamodel changes you may have made;

– A pointer to the Oracle Cloud Application development or test environmentwhere you plan to deploy your app. You can deploy your app manually, or wireit up to a pipeline to do it automatically, such as when a developer on yourproject merges his or her branch to the master branch.

– Your own clone of the app extension's Git repository, where the source codefor your application extension lives. Your work is not visible to others until youa) 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. Youcan think of a workspace as your editing context while you're working with theDesigner.

Before you can use the Designer to create or edit an application extension, you mustfirst select or create a workspace to identify the source files you'll be editing. Aworkspace defines the repository—and the branch—containing the source files youwant to use, the Application's development environment, and, in certain cases, asandbox. The Application repository and development environment must already beset up and defined in the application extension project in VB Studio before you cancreate a workspace. If the development environment isn't defined, you won't be able tocreate a workspace.

You're the only one who can access your workspace. Changes to files you make inyour 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 youcan use one workspace and switch to a different branch and sandbox when you are inthe Designer.

Use Your Oracle Cloud Application SandboxVB Studio can access the sandboxes in your Oracle Cloud Application that havechanges to the application's data model that haven't been published yet.

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

1-4

If the changes in a sandbox are relevant to your app extension, you can associate thesandbox you want to use with your workspace so you can access it when you arecreating the app extension. You'll want to save all your work in a branch that isassociated with the sandbox with those changes, and you'll want to continue to use thesame branch with that sandbox until you are finished. If you need to edit the appextension using a different sandbox as well, it's better to associate it with a new branchthan to use an existing branch. This will help isolate the changes you make for eachsandbox. If it helps, for each branch-sandbox pair you can create a separateworkspace instead of switching a workspace's branch and sandbox. VB Studio helpskeep your changes in sync by automatically recommending a sandbox for yourworkspace if you choose a branch that is already using it.

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

Use Branches to Isolate ChangesThe repository for your app extension was already created in your project by youradministrator. When you create a workspace, you use a branch of the repository forthe changes you will make. You can have separate branches for each new feature orchange to your app extension.

You can use separate branches for changes you want to make for two differentsandboxes, or for different versions of a feature that use the same sandbox. Forexample, when you are modifying a table component in your app extension, you mightwant to work on two different versions of the table. By creating a branch for eachversion, you can work on one version in one branch with a Workspace A mapped to it,and then switch to another branch by using Workspace B to work on the other version.This way you can use your workspaces to help you isolate the branches with yourchanges. After you decide which version you want to use you can share the branchwith others and delete branches you no longer need.

Share the Application ExtensionIt's good practice to ask your team members to review the changes you make to anapp extension before you publish it.

VB Studio has a share feature that allows you to share a preview of your changes withteam members. The preview version of your application runs on your Oracle CloudApplication development environment and includes the changes you made to the appextension. If you made changes based on a sandbox, the preview will use the samesandbox.

What is the Process for Creating and Publishing anApplication Extension?

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

Here's the typical process for editing and publishing an application extension.

1. In Oracle Cloud Applications, open the application you want to customize.

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

1-5

2. Open the Settings and Actions menu, then click Edit Pages in Visual Builder toopen the page in the Designer in VB Studio.You should take care to make any necessary data model changes before youlaunch VB Studio.

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

3. Using the Designer's dynamic layout editor, make the customizations you want tobe part of the application extension.When you click on a component, the editor will show you the component’sproperties, where you can select and change configuration details. At the top is theQuick Actions panel. This holds a selection of useful configuration options,dynamically chosen for each component, and most of the time, you'll want to makechanges to one of these. Sometimes you may need to change something that’snot in the Quick Actions. You can find other component properties below the QuickActions panel, such as the object properties and the applicable rule set.

When you start editing a component, each of its rule sets has a default base layoutthat's read-only. You’ll have to duplicate the rules set's default base layout orcreate a new one to make changes. In the layout you’ve made, you can move, editand delete the fields displayed in the component, or add any field that’s in yourapp’s data model.

You extend a component's rule set in the editor to add, duplicate, and update therules that govern which layout a dynamic component displays. The default baselayout is used when none of the rules apply.

4. View your changes with the preview tools.Use the Layout Preview when editing a page to check your layouts in theDesigner, and Preview to see your changes as they will appear in the page in abrowser.

5. Share your changes to get feedback.Use the Share tool to generate a URL for the app extension preview that you canshare. If you're working with a sandbox, you can send this URL and the sandbox

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

1-6

name to team members so they can see it and comment. If you're not working witha sandbox, simply share the URL.

6. Save your changes to a branch.You use the Git commands in the menu to commit and push the changes in yourworkspace to the remote branch.

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 andapprove the request if they look good.

8. Merge your branch into the main repository.When your changes have been reviewed and approved, you can merge yourbranch into the main repository (master). The administrator can configure theproject 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 CloudApplication test environment. After testing, a separate build job will publish thebuild artifacts to the live application.

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

1-7

2Getting Started

To start working on your application extension, the first thing you need to do is createa workspace for the Designer in Oracle Visual Builder Studio. A workspace is createdfor you when you come from your Oracle Cloud Application, but you can also createone in the Designer in VB Studio.

Open an Application Extension from an Oracle CloudApplication

When you're working in an Oracle Cloud Application, if a page has elements that canbe extended in VB Studio you can open VB Studio using the Edit Pages in VisualBuilder link in the user menu.

Clicking the link opens the app extension in a workspace in VB Studio, and opens theOracle Cloud Application page in the Designer. If your admin set up things properly, aworkspace was created for you if you needed one, and also a repository branch fromthe app extension's main repository that you can begin to fill in by creating newlayouts.

If your admin has set things up for you, you automatically land in the right project. VBStudio looks for the project and workspace associated with your base application andactive Oracle Cloud Application sandbox (if you have one). If you have an activesandbox, your app extension opens in a new workspace in VB Studio associated withit, or in an existing workspace if you've already created a workspace associated withyour active sandbox. In some cases you might need to select the project or workspaceyou want to open.

• If you have multiple workspaces associated with the same base application orsandbox, you will be prompted to choose one.

• If you don't have any workspaces, you will be prompted to select the repositorythat has the extension for the base application, and you might also need to selectthe base application's development environment.

If it's the first time you're editing the app extension, a new workspace and repositorybranch are created for you. If it's also the first time you're using the active sandbox, thesandbox is associated with the new workspace.

To access VB Studio you'll need to already be a team member of the VB Studioproject configured for your app extension and have the proper user role.

To open a page from your Oracle Cloud Application:

1. In your Oracle Cloud Application, navigate to the page that you want to edit in VBStudio.

2. Open the user menu and click Edit Pages in Visual Builder.

2-1

When you click the link, VB Studio checks for the correct project and workspace. Ifprompted, you might need to select the correct project or workspace before the appextension opens in the Designer.

Create a Workspace Using an Existing RepositoryTo make changes to an application extension that already exists, you want to create aworkspace that contains a clone of the application extension's Git repository.

Two workspaces shouldn't use the same branch. If you want to use a branch used inanother workspace, you can create a new workspace and clone the branch for yourchanges.

When creating a workspace you will create a new local repository by cloning anexisting repository or creating a branch. When cloning an existing repository, you willusually want to clone the master branch of your application's repository. This ensuresthat the new branch that you create contains the most up-to-date changes. If you aremaking changes that have not been merged to the master branch, you will want toselect the branch containing the sources that you want to edit. For example, if youneed 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 an app extension:

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 usingthe Create Workspace wizard. A workspace is created for you automatically whenyou open VB Studio from a page in your Oracle Cloud Application.

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 anyother branch.

Chapter 2Create a Workspace Using an Existing Repository

2-2

7. Select New branch from selected and type a name for the branch you want tocreate.

You can create additional branches and switch between branches in theworkspace.

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

Each of your workspaces will probably use the same development environmentbecause a project typically has only one. The environment must also support thetype of project you are working on, so to create a workspace for extending anOracle Cloud Application, your project must be associated with an Oracle CloudApplication environment. If an environment is not defined for your project youshould contact an administrator to add one.

9. Optional: Select the Sandbox you want to use with this workspace, if any.

Create a Workspace for a New Application ExtensionYou use the New Application Extension tab when you create a workspace to create anew Git repository that you'll use for a new application extension.

You might want to create a new app extension when no app extension for the baseapp exists. In some cases you might want to create a new app extension for a base

Chapter 2Create a Workspace for a New Application Extension

2-3

app, but best practice is that the base app should only have one app extension. Whenyou create the new app extension you'll have to specify the base app that it isextending, and the development environment used when developing the extension.

To create a workspace for a new application extension:

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 usingthe Create Workspace wizard. A workspace is created for you automatically whenyou open VB Studio from a page in your Oracle Cloud Application.

2. Click Create Workspace.

3. Type a name for your workspace.

4. Click New Application Extension.

The details you'll need to provide and the files in the Git repository in yourworkspace depend on the Initial Content option that you select.

5. Select the base Oracle Cloud Application that the app extension will extend.

The base app has already been configured for your project, so most likely there'llonly be one application in the dropdown list.

Chapter 2Create a Workspace for a New Application Extension

2-4

6. Type the name of the Git repository and branch that'll be created for storing yourfiles.

If you don't want to create a Git repository now, for example, you only want toexperiment with creating an app extension, you can select the Scratch repositoryoption. Selecting this will create a repository in your workspace that only you cansee.

7. Select the Development Environment for your app extension.

The Development Environment has already been configured for your project, somost likely there'll only be one environment in the dropdown list. You can't create aworkspace or develop an app extension if your project doesn't have adevelopment environment.

8. Select a sandbox if your new app extension will involve changes that have beenmade to the data model of the Oracle Cloud Application.

9. Click Create Workspace.

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 ascratch repository instead of a branch when you are experimenting and you're prettysure you'll never want to merge its contents into an existing repository. A scratchrepository is a private repository that only exists in your workspace. No one else cansee the repository's contents, and it's deleted when you delete the workspace. It'sbetter to create a branch rather than a scratch repository if you think you might want toeventually merge its contents into the main repository.

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

Push a Scratch Repository to a Git RepositoryIf you chose to use a scratch repository when creating your application extension,other team members in your project cannot work with your application extension.

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

1. Open your application extension.

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 theRepository to Create input field. You can provide an optional description for the Gitrepository that VB Studio will create for you.

4. Enter a commit message, and then click Create and Push.

Chapter 2Create a Workspace for a New Application Extension

2-5

Create Workspace by Importing an App Extension ArchiveIf a team member gives you an archive of an app extension, you can import it to createa workspace containing all the files in their branch of the app extension's Gitrepository. When you create a workspace by importing a file, you create a new Gitrepository and branch.

To create a workspace by importing an archive:

1. Open the Designer page in VB Studio.

2. Click Create Workspace.

3. Type a name for your new workspace.

4. In the Create Workspace wizard, click Import From File.

Chapter 2Create Workspace by Importing an App Extension Archive

2-6

5. Drag the archive into the Import File drop area, or click in the drop area to locatethe archive on your computer.

VB Studio automatically checks the content of your archive to verify that it is avalid app extension archive. If it's not, you will see a message that you can't createa workspace by importing it.

6. Provide a name for the new Git repository and branch that'll be created in theworkspace.

7. Select the development environment for the app extension, and a sandbox if youneed one. Click Create Workspace.

Open a Page in Your Application ExtensionIf you log in to VB Studio directly, you'll need to select or create a workspace if youwant to edit an application extension. When you open the Designer in VB Studio, you'llsee a list of your workspaces. You can select one of them, or create a new workspace.Once you are in the workspace you can select the page you want to edit.

To open a page in your application extension:

1. Log in to VB Studio, if you are not already logged in.

The Organization page opens when you log in and lists all the projects in yourinstance. You might only have a few projects.

2. Locate your project and click the project name to open its Project Home page.

The Project Home page displays details about your project, including the project'senvironment, repositories and recent activities.

3. Click Designer in the main menu to open a list of your workspaces.

4. Click the name of the workspace you want to open.

Chapter 2Open a Page in Your Application Extension

2-7

Each workspace is associated with a repository and a branch, and also sometimesa sandbox. If you are using a sandbox, you probably want to open the workspacealready associated with it. This helps ensure that your changes are made to thebranch using that sandbox.

If none of your workspaces are using the correct sandbox, you can create a newworkspace or open an existing one and switch to the correct sandbox and branch.

5. Click the page in the Navigator to open it.

The extendable pages are listed under the flow node in the Application Extensionspane.

Chapter 2Open a Page in Your Application Extension

2-8

3Create Your Application Extension

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

How Do I Create an Application Extension?There are two easy ways to create a new application extension, or to edit an existingone:

• Starting in Oracle Cloud Applications, click the Edit Pages in Visual Builder. VBStudio opens the workspace associated with the sandbox you’re using (if you areusing one), or creates a workspace for you if you don’t have one. Regardless, youshould see your page in the Designer, with the extensible areas outlined in blue,like this:

(If you’re new to application extensions, you may want to watch the video to helpyou get oriented.) When you select an extensible area—either by clicking a regionin the middle section, by selecting a component in the Property Inspector on theright, or by selecting a dynamic UI in the left Navigator area—you’ll be placed inthe dynamic layout editor, where the real work begins. If there are configurablevariables or events exposed in the base application, you'll also see the variablesand/or events tabs for viewing the configurable variables and events related to thepage.

• After logging in to Visual Builder Studio, you select the project you want to work in,then click Designer in the left navigator to either select your workspace or create anew one. You should then see something like this:

3-1

At this point you can select an app extension page or a dynamic UI in the leftnavigator, after which you’ll be placed in the dynamic layout editor. More on thatlater.

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

Element Description

Project The name of the current project.

Workspace The name of the current workspace. You can click the workspacename to switch to a different workpace in the project.

Git repository The name of the Git repository for the base app, and the name of therepository branch currently associated with your workspace.

Sandbox The name of the current sandbox used in the workspace, if any.

Undo Undo your most recent change.

Redo Redo a change after clicking Undo.

Preview Open a new tab in your browser to preview the current page.

Go to File Search the Git repository by file name.

Menu Open a menu containing the Share, Import and Export actions. Youcan also open the Settings editor from the menu.

You use the Navigator on the left of the Designer to navigate the artifacts in your appextension. The Application Extensions area in the Navigator contains two types ofartifacts:

• Under Dynamic UIs, the dynamic UI artifacts for each business object resource.Both Accounts and Contacts are examples of business objects used by theSubscription Accounts base Oracle Cloud Application, and their correspondingdynamic UI artifacts are listed in the navigator. When you select a dynamic UIartifact corresponding to a business object, it opens in the dynamic layout editorwhere you can edit the dynamic layouts that use that business object.

• Beneath the business objects, the extendable page artifacts are grouped intofolders under their flow names. When you select a page, like account-relationship-start, it opens in the Page Designer on the right, where you canclick the dynamic component you want to work on to open it in the dynamic layout

Chapter 3How Do I Create an Application Extension?

3-2

editor. When a page is open in the Page Designer, the extendable components inthe page and configurable variables and events related to the page are listed inthe Property Inspector on the right. You can open the editors for dynamic layouts,variables and events from the Property Inspector.

By default, the Application Extensions pane only displays artifacts that you can extend,but you can change that so that all the artifacts are shown, or to show only thosewhich have already been extended. You may see some artifacts that you cannot openor modify because you don’t have permission, or because it does not contain anythingthat can be extended.

The Designer also lets you work in source code if you prefer. Click the Source Viewicon to enter this mode:

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 theAudits 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 appextension.

Tests View a list of all action chain tests defined in the app extension, andthe status of each test.

Chapter 3How Do I Create an Application Extension?

3-3

Customize Dynamic ComponentsA dynamic component is a UI component, such as a form or a table, that does notrender a static set of fields. Instead, it determines at runtime what fields to render, andhow they are displayed, based upon the display logic specified in its rule set.

When you want to modify how a dynamic component looks and behaves, youconfigure its rule set. By default, a dynamic component in your cloud applicationrenders the fields defined out of the box in the rule set's built-in default layout. You canchange what's displayed in the component by configuring the rule set with your owncustom layouts and display logic.

You have two main objectives when customizing a dynamic component: one, toconfigure the fields the way you want them in a layout, and two, to define the displaylogic that determines which layout is applied to the component at runtime, based onthe viewer’s current circumstances. In most cases you define the logic first, thenconfigure the layouts that will be used in your logic. You can edit the layout to definethe fields that appear and how they are ordered and grouped.

Determine What's Displayed at RuntimeYou control what’s displayed at runtime on a page through the use of display logic,which you configure using the rule set editor. Suppose you want to configure adynamic table so that certain columns are hidden and others are added when the userviewing the page is in Canada. You’d then create a rule that checks for the user’slocation and, if the user is indeed in Canada, apply the layout you’ve created thatcontains the desired columns. All non-Canadians would see the page with the defaultlayout applied.

You can have more than one rule for a given component, and the order in which theyappear in the rule set editor is important. At runtime, Visual Builder Studio runsthrough the rules from top to bottom. When it finds a rule where the condition is met—in this case, the user is in California—the associated layout is applied to the page andno other rules are tested. Keep this in mind as you’re working with the rule set editor.

When you select a business object in the Application Extensions pane, you’ll see aseparate tab for each dynamic component that uses that business object. Forexample, suppose there’s both a dynamic table and a dynamic form bound to theContacts business object. When you open Contacts, for each component you’ll seeone tab containing the component's rule set, allowing you to control the data that’sdisplayed in each independently.

To set the display logic for a component:

1. After you have selected a dynamic component to extend, click Open Rule SetEditor in the Property Inspector.

The Property Inspector also tells you the REST endpoint of the business objectassociated with this component (contacts), as well as the name of the dynamiccomponent's rule set (ContactsListUsage).

Chapter 3Customize Dynamic Components

3-4

The rule set contains one or more built-in default rules governing the display forthe base app and it cannot be modified, but you can create new rules or makecopies of a built-in rule to use as the basis for your own rules.

2. In the rule set editor, click Duplicate Rule and give it a name, preferably somethingmeaningful. For example, to create a layout that displays only when the user is inCanada, you might call the rule inCanada.

If you want to also create a copy of the layout to use as a starting point, make surethat check box is selected in the Duplicate Rule dialog box.

3. Click Click to add condtion, select an Attribute and Operator from the dropdownlists, and enter a Value to create a condition. Click Done.

You can add more conditions and group conditions if you want to use moreattributes to make the rule more precise. For example, you may want to use alayout that displays an extra column if the user is in Canada AND has the managerrole. You would then create a rule with two conditions, and select Match All torequire that both conditions are true.

Chapter 3Customize Dynamic Components

3-5

If you select Match Any, then the rule would be true if any of the condtions in therule are true.

4. In the return field, select the layout you want to apply when the rule is true.

If you created a copy of a layout when you created the rule, it is selected bydefault in the return field. You can use the same layout with multiple rules.

5. Click Rule to add another rule.

6. Use the Move Up and Move Down buttons to make sure you have the rules in theorder you want them evaluated.

The order and precision of your rules is important. The rules are evaluated fromthe top down, so the first rule where all the conditions are met will determine thelayout that is used.

Create a Dynamic LayoutA layout defines the fields that are displayed in a dynamic component at runtime. Youcan create multiple layouts for a single component, and the layout that is used isdetermined by the rules in the rule set. For example, you might have one layout thatshows certain fields in a dynamic form when the user is a manager, and another layout

Chapter 3Customize Dynamic Components

3-6

for non-managers. At runtime, the rules associated with the component are evaluatedin the order they appear to see if the conditions set in that rule are met. If the conditionis true—say, the current user is a manager—then the layout you selected for that ruleis applied to the component and the user will see the fields he needs in the form. Non-managers will see a different layout.

To create a new layout:

1. Open the rule set you want to edit.

2. Click in the Layouts column of the rule set and type a name for the new layout,or click Duplicate in an existing layout to use it as a starting point.

Each rule set contains a default layout that is seeded for you. You can't edit thedefault layout, but you can duplicate it and use it as the basis for a new layout. Thedefault layout is always used in the last rule of the display logic tree.

3. Click the new layout to open the field selector.

4. In the Fields column, select the checkbox for the fields you want to add to thelayout, or drag fields from the Fields column directly onto the drop target in thecomponent column.

5. Edit a field's properties, for example, if it is read-only, by clicking the field in thecomponent column and editing the properties in the Property Inspector.

Chapter 3Customize Dynamic Components

3-7

6. Use the Property Inspector to set properties and create expressions that controlthe behavior of each field in the component, such as if it is a read-only field, aswell as some display properties. For example, the default value for the Show Fieldproperty is Always, but you can change that so a certain field is displayed onlywhen certain conditions are met.

7. Change the order that fields are displayed in the component by dragging fields intoa different position within the component column.

8. Click Done.

After a layout is created you can include it in a display logic rule, as described in Determine What's Displayed at Runtime. You can use the same layout in multiplerules.

Define Conditions in a Dynamic LayoutYou use expressions to define conditions for rule sets and the display properties forfields and components in dynamic layouts.

Visual Builder has a condition builder to help you create the conditions in your dynamiclayout by allowing you to quickly select the Attributes, Operators and Values in theexpression, and to easily create complex expressions. For example, you might createa rule in a rule set that looks like this:

Chapter 3Customize Dynamic Components

3-8

This rule has two conditions, and if both are met then the isEmailLayout layout is used.The conditions you see in the condition builder represent an expression in the dynamiccomponent's layout-x.json file. If you open the rule set in Code view you can see theexpression, which for this rule will look similar to this:

"isEmailRule": { "description": "My email rule", "type": "crmRestApiLatestAccountsDescribe", "expression": "{{ $context.record.NoteTxt.includes('available') && $context.user.email.includes('example.com') ? 'isEmailLayout' : null }}" }

When you create a conditon you select an Attribute in the condition builder's dropdownlist. You can select fields retrieved from the business object (for example,record.NoteTxt) or variables that are determined by the app extension's context (forexample, user.useremail). In addition to business object fields, two kinds of appextension context ($context) variables are available in Visual Builder: user andresponsive. Values for the user variables are determined by the current user, and theresponsive variables are determined by the current device used by the app extension.

The following user variables are added by Visual Builder to the $context available inlayout expressions:

• $context.user.userId

• $context.user.longId

• $context.user.fullName

• $context.user.email

• $context.user.isAdmin

• $context.user.isAuthenticated

The following responsive variables are added by Visual Builder to the $contextavailable in layout expressions:

• $context.responsive.smUp

• $context.responsive.mdUp

• $context.responsive.lgUp

• $context.responsive.xlUp

• $context.responsive.smOnly

Chapter 3Customize Dynamic Components

3-9

• $context.responsive.mdOnly

• $context.responsive.lgOnly

The responsive variables are wrapped with an accessor, so parentheses are not usedin expressions (for example, $context.responsive.mdUp === true ?).

Add and Group Fields in Form Layouts

When creating a form layout in the dynamic layout editor, you can create groups offields so that the fields are displayed together in a layout, and so you can treat them asa single entity. For example, you can create an address group that contains the fields(for example, name, address, city, state, country and post code) that you want to bedisplayed as a group in your layout. You can then apply conditions to the group thatcontrol when the group is displayed. A group also makes it easy to add several fieldsto a different layout in one step, rather than adding them individually.

You can define properties for a group (for example, to add a group label) and toindividual fields in a group (for example, to specify column spans for fields to createcomplex form layouts.)

To create a group of fields in a form layout:

1. Open a form layout containing fields you want to group together, or create a newform layout and add the fields you want the group to contain.

You can use buttons in the toolbar to duplicate the current layout ( ), to copy

selected fields in your current layout to another layout ( ), and to copy fields fromanother layout into the current one ( ).

2. In the layout diagram, select the fields that you want to group together.

To select multiple fields, hold the CMD key (on macOS) or Ctrl key (on Windows)when you click a field.

3. Click Group Fields in the Property Inspector, or Group selected fields ( ) in thetoolbar.

The selected fields are grouped under a new folder in the layout diagram.

Chapter 3Customize Dynamic Components

3-10

4. Type a name for the new group by naming the folder in the layout diagram. Click

to save the group name.

5. In the Property Inspector, set the properties for the group and fields in the group,for example, conditions that determine when the group is displayed in a layout.The default setting is to always display the group.

After a group is created, you can still use the handles for fields to drag them into andout of a group.

Design Your PagesWhen you select a page artifact in the Navigator it opens in the Page Designer, whereyou can see how the page looks when different layouts are used, and edit theproperties of page components. When nothing is selected on the page, the PropertyInspector on the right lists the page's dynamic components, as well as other editableitems such as constants and variables used in the page. Editable components areoutlined on the page, and when you select a component on the page or in the PropertyInspector its properties are listed in the Property Inspector. You can edit somecomponent properties directly in the Property Inspector, but for others like dynamiccomponents you'll need to click the link in the Property Inspector to open a dedicatededitor.

In this example where the Leads Table component is selected in the page, theProperty Inspector shows that the component uses the simpleTable rule set and thatthe active layout is determined by the display logic.

Preview Different Dynamic LayoutsWhen you want to see how different dynamic layouts look in your page, the LayoutPreview in the Property Inspector lets you switch between the different componentlayouts in your rule set. The display logic rules in a component's rule set apply whenyou are looking at a page in the Page Designer. For example, if you created a layoutthat only managers can see, you won't see it in the Page Designer because you don'tmeet the conditions in the rule. You use the Layout Preview dropdown list in theProperty Inspector to override the display logic and select one of the component'slayouts.

Chapter 3Design Your Pages

3-11

To preview a dynamic component layout:

1. When the page is open in the Page Designer, select the dynamic component youwant to check on the page.

When a dynamic component is selected, the Layout Preview dropdown listcontains the layouts defined in the component's rule set.

2. Select a layout in the Layout Preview dropdown list.

The Layout Preview displays the name of the active layout.

In this image, the Property Inspector shows that the Page Designer shows thecomponent's CommercialOrgTableLayout. Some display conditions that you haveadded to fields might be ignored, however. You can click Configure Layout to openthe layout in the dynamic layout editor.

3. Click Reset to return to the default "Resolved by display logic" option.

Store Property Values with Variables and ConstantsVariables and constants store values that are used to define how pages are displayed,and may also be used for page actions. For example, the color of a page heading canbe stored in a variable, so when creating your app extension you can edit the variableto set the color. The base application developer or a team member might have already

Chapter 3Design Your Pages

3-12

specified some variables and constants that you can extend, but you might also wantto add others.

Variables and constants are both used to store values and might be read-only orwriteable by the app extension, but there are some differences.

• Variables are typically used to store values used within a page's UI or an actionchain, for example, an input text or a total. Variables are commonly used to storevalues when performing an action in the page like adding items to an order, butthey can also be used to store property values like a text color or font size.

• Constants are typically defined in the base app, and their values don't changeafter they are set by the app extension. For example, the base app might define aheading that uses the constant itemDetailHeading for setting the heading text.Your app extension can write a value to the constant, and that value will be usedto set the heading text every time itemDetailHeading is used in the appextension.Constants that can be extended by your app extension are listed in the PropertyInspector. Extensions that supply the same value for a constant will overrideprevious extensions that are lower down in the dependency chain.

The Page Designer has a Variables editor where you can view, create and editvariables and constants. Special characters (period, colon, dash and space) can beused in the field names for variables by enclosing it in bracket notation. For example,an object variable that contains a field called 'child.field' will need to be referencedas $variables.objVar['child.field'].

Change Constant Values in the Property InspectorIf the base app or your app extension use constants that can be extended by your appextension, you can see and modify the values stored in them in the Property Inspector.

For example, the base app might use a constant to store a font size or text for aheading in your app extension. The base app will specify a default value, but it mightallow your app extension to overwrite the default value used for the heading and setyour own font size or text. Your value will be used instead of the default when your appextension is published.

If you open the Variables editor in the Page Designer you can see a list of all theconstants used in your app extension, and if your app extension is allowed to overwritethe constant's default value. Constants are badged when they are defined in the baseapplication.

To overwrite the default value of a constant:

1. Open your extension page in the Page Designer.

2. In the page's Property Inspector, locate the constants used in the page in theConstants section and click the component's name.

Chapter 3Design Your Pages

3-13

The Constants section displays the name of each constant and the component it'sused for. For each constant, you can click the component name to open itsproperties in the Property Inspector. In this image of the Property Inspector youcan see that two constants (detailHeading and headerFontSize) are used in thepage. The constant detailHeading is used to store a property of the Headingcomponent.

Alternatively, if you know a component uses an editable constant you can click thecomponent on the page to open its properties in the Property Inspector.

3. In the Property Inspector, type the value in the text field.

Chapter 3Design Your Pages

3-14

The text field contains the constant's default value. A component might use morethan one constant to define its properties.

Edit Variables and Constants in the Variables Editor

To edit a variable or constant in the editor:

1. Select the component in the Page Designer.

The Property Inspector lists the attributes of the selected component that can becustomized using variables or constants.

2. Select the attribute defined by a variable or constant.

3. Click Show in Variables to open the Variables editor.

Chapter 3Design Your Pages

3-15

In the Variables editor, you can edit the properties of variables that are defined in theapp extension. You can also right-click a variable in the list and choose Go to Code inthe menu to open the JSON file where the variable is defined.

Define the Behavior of Components with Action ChainsThe behavior of the components in your app extension are determined by actionchains, a sequence of actions triggered directly by another action chain or by an eventlistener. An action chain might be a short sequence of a few actions, but it couldcontain many actions as well as logic for determining what happens in the sequence.For example, when you click a button on a page, what happens next is determined byan action chain that might contain actions such as assigning data to a variable,sending data to a database and navigating to another page.

Action chains can be defined in your app extension and in the base app. You can't editaction chains defined in the base app, but you can create and edit action chains inyour app extension in the Action Chain editor. For details on how to create and useaction chains, see Work with Actions and Action Chains in Building Web and MobileApplications with Visual Builder Studio.

Though you can't edit the action chains defined in the base app, the base app mightdefine custom events and event listeners that you can use to trigger them from actionchains in your app extension. The base app might also define events that you can useto start action chains in your app extension.

Use Events and Event Listeners to Start Action ChainsWhen an event occurs in a page, if an event listener is "listening" for the event it canstart one or more action chains when the event occurs.

There are various types of pre-defined events that you can apply to a component, andthe type of event is usually determined by the type of component. For example,ojAction is a type of component event triggered when a button is clicked, so youwould typically apply it to a button component. An event listener listens to that buttonfor the ojAction event, and starts an action chain (or multiple action chains) when the

Chapter 3Design Your Pages

3-16

event occurs. Each component event will usually have a corresponding componentevent listener. You can add an action chain to more than one event listener, so youmight have a SaveData action chain that can be started by two different event listenerslistening for two different events. For more, see Start an Action Chain with an Event inBuilding Web and Mobile Applications with Visual Builder Studio.

In addition to using the pre-defined component events, you can define your owncustom events. Unlike component events, custom events are not applied to acomponent but are triggered by the Fire Custom Event action in an action chain. Thereare a few types of custom events, and typically you would use one when you want totrigger some notification, for example, to display a popup window with a message, orwhen you want to transform some data. Like component events, you use custom eventlisteners to listen for custom events.

The base app might define some custom events that are designated as Triggerableand/or Listenable, indicating that you can use them to start action chains. In theEvents editor you can see which custom events are defined in the base app, and ifthey are listenable or triggerable. You can also see the event's behavior type thatdefines how the event listeners will be called.

You can't change the designation of custom events defined in the base app, but youcan use them to start action chains defined in the base app or in your app extension.

Chapter 3Design Your Pages

3-17

Event Designation Description

Triggerable Triggerable events are used to start action chains defined in the baseapp. If an event is designated as Triggerable, you can call the eventfrom an action chain in your app extension using the Fire CustomEvent action.

For example, the base app might define an action chain that opens apopup window, and define a custom event (for example, openPopup)and event listener to trigger the action chain. If the custom event isTriggerable, you can call the event from your app extension. So if youwant to use that action chain when a user selects a specific option, youcan add the Fire Custom Event action to the action chain in your appextension that is triggered when the option is selected. In the Actionseditor, you would choose the openPopup event when you configurethe Fire Custom Event action.

Listenable Listenable events are used to start action chains defined in your appextension. If an event in the base app is designated as Listenable, youcan add an event listener to your app extension and configure it totrigger your action chain when the listenable event occurs.

For example, you can use listenable events to:

• execute an app extension action chain asynchronously orsynchronously

• cancel an event in the app extension action chain• transform a return value that is passed between the layers of

event listeners

Event Behavior Types for Calling Event ListenersEach event has a Behavior type that defines how the event listeners will be called inrelation to each other, whether the result for the listener is available, and what form theresult would take. This is used for listeners defined in base apps as well as extensions,and is not specific to events defined in the "interface". The behavior does not definethe order in which the listeners are called.

The behavior determines whether the listener is called serially or in parallel, that is,whether the Action that raised the event waits for a listener resolution, and what the"result" of the listener invocation looks like. So in this case, "serially" means:

• all event listener chains for a single event listener (in a container) are calledsequentially, in a declared order. This means that a listener action chain is notcalled until any previous actions chain has finished (and resolved, it returns aPromise)

• the event listeners for the next container's listeners are not called until the listeneraction chains for any previous container's event listeners have finished (andresolved, it returns a Promise)

An event will have one of the following behavior types.

Type Description

Notify Parallel - The event is triggered but the application does not wait for theextension to process it.

Chain results are not available to the Action (or helper) that fired the event(because the listeners are called without waiting). This is the defaultbehavior.

Chapter 3Design Your Pages

3-18

Type Description

NotifyAndWait Serial - Each action chain listener must complete (and resolve any returnedPromise, if any), before another event listener action chain is called.

Chain results are not available to the Action (or helper) that fired the event.

CheckForCancel Serial - Each action chain listener must complete (and resolve any returnedPromise, if any), before another event listener action chain is called.

If any of the listeners Chains returns a "success" (*?!? or new result type?)with a payload of { "stopPropagation": true }, the application will stop callingevent listeners. When calling listeners defined in both extensions and thebase application, the listeners in the "closest" extension are called first. Inother words, extensions of extensions are called before extensions of thebase. This allows higher-precedent extensions to cancel listening, beforethe lower-precedent extensions (or base) receive the event.

Chain results are not available to the Action (or helper) that fired the event.

Chapter 3Design Your Pages

3-19

Type Description

Transform Serial - Each action chain listener must complete (and resolve any returnedPromise, if any), before another event listener action chain is called.

The "eventListener" will have access to a new context variable, $previous,which is a peer of "$event". This will be the result of the previous listenerinvocation's chain result, or undefined for the first invocation. The"eventListener" for a "transform" event can also have a "returnType"declaration, analogous to the "payloadType", but corresponding tothe $previous value. If the event declaration has a"returnType", $previous should match the type, otherwise, it will becoerced to the type.

When calling listeners defined in both extensions and the base app, thelisteners in the "closest" extension are called first. In other words,extensions of extensions are called before extensions of the base app.(This convention matches the order of the "cancel" behavior). The finalresult, "returnType", when all the listeners have been called, will bereturned as the result of the fireCustomEventAction that initially raisedthe event.

If the application wishes to use the "transform" mode, the convention itshould follow is:

• For any listeners for an event with a "transform" behavior thatreference more than one Chain, the Chains are called in array order.

• All listeners for an event with a "transform" behavior should passthe $previous as an argument to their Chain (and this will typically bewired by the design-time).

• All listeners for an event with a "transform" behavior should define a"returnType", which matches the "returnType" for the event declaration.

• The Chain variable argument that corresponds to $previous shouldhave an argument that matches the "returnType" of the event, and theChain should also have a "returnType" that matches the listeners"returnType" (note that "payloadType" and "returnType" cannotcurrently reference defined Types, because of restrictions on typesused in the "interface" section).

• The Chain should have a "returnType" defined, that matches the"returnType" of the event (this is currently not used by runtime.).

The parameters for the listener, and the inputs for the Chain, toprovide $previous can be added by the design-time, just as it providesthe $event.

Here is an example:

"events": { "myTransformEvent": { "payloadType": { "foo": "string" }, "returnType": { "bar": "number", }, "behavior": "transform" }}"eventListeners": { "myTransformEvent": { "chains": [{

Chapter 3Design Your Pages

3-20

Type Description

"chainId": "myTransformChain", "parameters": { "myPrevious": "{{ $previous }}", "myEvent": "{{ $event }} } }]},"chains": { "myTransformChain" : { "variables": { "myEvent": { "type": { "foo": "string" } }, "myPrevious": { "type": " { "bar": "string" } } }, "actions": { ... }, "returnType": { "bar": "string" } }, "fireIt": { "root": "fire", "actions": { "fire": { "module": "vb/action/builtin/fireCustomEventAction", "parameters": { "name": "{{ $chain.variables.name }}", "payload": "who cares?" }, "outcomes": { "success": "getResult", } }, "getResult": { "module": "....", "parameters": { "name": "{{ $chain.results.fire.result }}", } } } }}

Chapter 3Design Your Pages

3-21

Preview Your ApplicationBefore committing your changes to the branch, you can use the application preview tosee how your pages look and behave in a browser.

The application preview shows you how the pages are displayed based on thechanges you've made to the app extension in your workspace. It is a working versionof your application that you can use to test the behavior of your app extension. In thepreview you can check the rule sets, layouts, the navigation between pages, and whathappens when you add and edit data. While the data in the preview comes from yourCloud Application, you can freely make changes in the preview because the data isonly stored in the test environment used for the preview and is not saved to the CloudApplication's data storage.

When you use Preview to view your application, you'll see the pages as they lookbased on your user role. This means that if the application has any rule sets thatevaluate the user's role, this will affect what data you see in the pages, and you can'tswitch between layouts determined by rule sets.

To preview your application:

1. Open a page in your application.

2. Click Preview in the toolbar to open the application preview in your browser.

You can't share an application preview URL with your team members. If you wantteam members to see your changes, you'll need to commit the changes to a branchand then use the Share action to get a URL you can share.

Share Your Application ExtensionApplication previews can only be seen by you in your workspace, but by using theShare action you can allow team members to also see your changes to the applicationextension. The Share action generates a URL for the application extension that youcan share with your team members.

If you made changes to the app extension that involved changes to the data model,when you share the URL you might need to also share the name of the sandbox soyour team members can check the changes in the app extension using the correctdata model. The URL of the application extension you are sharing might not be thesame as the URL you see when you are previewing the application extension in theDesigner.

To share your edited application extension:

1. Open your workspace in the Designer.

2. If you are using a sandbox, confirm that your current sandbox is the one you wantto share.

3. Open the User Menu and click Share.

Chapter 3Share Your Application Extension

3-22

4. Click Copy to copy the generated URL for the application extension.

If you are using a sandbox, you will need to share the URL and the name of thesandbox with your team members.

5. Click Share.

6. Send an email with the generated URL, and include the name of the sandbox ifone was used.

Export Your Workspace as an ArchiveWhen you want to share the files in your app extension, for example, with a teammember, you can export your workspace as an archive. Importing the archive in theCreate Workspace wizard creates a new workspace with a Git repository containingthe files in the archive.

When you export an app extension, the exported archive contains the files in yourworkspace's branch of the app extension's Git repository.

To export an app extension as an archive:

1. Open the Designer page in VB Studio.

2. Locate the workspace that you want to export and select Export ApplicationExtension in the workspace's options menu.

Chapter 3Share Your Application Extension

3-23

4Publish the Application Extension

To publish your app extension you need to save your changes to a remote branch andthen to the master branch. You can do all these steps at one time using the Publishaction, or you can use Git commands in your workspace to do them individually.

Review the ProcessIf you’re unfamiliar with Git commands, it may be helpful to review the relationshipbetween your workspace, your project, and the Oracle Cloud Applicationsdevelopment environment.

• When you create a workspace (or one is created for you), you get a clone of theproject’s Git repository and all its branches. Your workspace will contain a branch(which might be new or might already exist), but no one else can see the changesyou make to the branch in your workspace until you choose to make them visible.This branch is where you work on your application extension.

• As you make your changes, you frequently use the Commit action from theDesigner’s drop-down menu to save your changes to your local copy of the repo:

• You can also add a commit message describing the reason you updated thosefiles (for example, "Added new layout X for field Y"). These commit messages canhelp you later to identify which files were changed and why.

• In most cases, the top of your project’s Git repository is called the master, and isthe source from which your artifacts (like an app extension) are built. Yourproject’s Git repository is also called the remote repository, while the clone in yourworkspace is called the local repository.

• When you’re ready to publish the work you’ve done in your private branch, youfirst Push your changes into the remote repository, thereby exposing your changesas a branch to everyone else in your project. (In Git terms, you do a Git Push

4-1

operation to add it to the project’s Git repo; if a team member does a Git Pulloperation at this point, they will get a copy of your branch as well.)

• Once your changes are part of the project’s Git repo, your team members canclone the branch in their workspace and view the changes. They can also view thesource code in the repository, including all branches, by opening Git in VB Studio.

• If other team members are working on the application extension, you might all beworking off the same branch. For this reason, you should update the branch withyour changes frequently using the Push command. Frequently pulling changesthat other members make into your branch is also advised to ensure that thebranch in your workspace has the most recent changes. This can help you toavoid accidentally making changes to files that someone else is editing or hasedited, which can result in a code conflict that you would then need to resolve.

• When you’re completely done with your work, the next step is to merge yourchanges to the source of truth, the master branch. You might be required to submita merge request before the merge is permitted. A merge request describes thereason and scope of the changes to be merged, and often requires some teammembers to explicitly approve the request after they have reviewed the changes.

Publish the Application ExtensionDepending on how your project is configured, you might be able to publish yourchanges without creating a merge review request, but it's good practice to ask yourteam members to review the changes you made before you publish it. A code reviewis usually required before changes are added from a branch to the main branch (oftenthe master branch).

The easiest way to publish your changes is by opening the Publish Changes dialogbox from the header in the Designer. In the dialog box you simply enter a commitmessage describing the changes (and add reviewers and issue if you're also creatinga merge review request) and click Publish Changes. If you don't create a merge reviewrequest, the changes are merged immediately. If you create a merge review request,the changes can be merged after they've been reviewed and approved. Once therequest is approved, you use the Merge action on the Merge Requests page to mergethe changes.

Once you publish your changes, you can no longer use the Git branch that containedyour changes, so you'll need to use a different branch if you want to make additionalchanges. A new branch is created automatically for you when you publish yourchanges, and you can use it to make additional changes or you can create your ownbranch.

When you're ready to merge your changes, you should publish the sandbox you usedin your Oracle Cloud Application. Publishing the sandbox before merging yourapplication extension changes to the main repository can help avoid potentialproblems resulting from using two different data models. See Publishing Sandboxes:Procedure in Configuring and Extending Applications.

Chapter 4Publish the Application Extension

4-2

Your project is probably set up so that each time changes are merged into the masterbranch, the application extension artifacts are built from the repository andautomatically deployed to the Oracle Cloud Application's test environment for furthertests.

Publish Changes Without Creating a ReviewIf your project is configured to allow you to merge changes from your branch withoutcreating a merge review request, you can use the Merge Now tab when you use thePublish Changes action.

To publish your application extension without creating a merge review request:

1. Click Publish Changes in the Designer toolbar.

2. Select the Merge Now tab and type a Commit Message.

3. Click Publish Changes.

4. Click Close.

Publish Changes that Require ReviewIf you are publishing changes and want to create a merge review request, you use theMerge After Review tab in the Publish Changes dialog box to enter the commitmessage and review details. If your project requires a review before changes can bemerged, the Publish Changes will not have the Merge Now tab.

To create a merge request in the Publish Changes dialog box:

1. Click Publish Changes in the Designer toolbar.

2. Select the Merge After Review tab and type a Commit Message.

Chapter 4Publish the Application Extension

4-3

3. Select the team members you want to review your changes.

The members you select will be listed in the the Merge Review page as reviewerswho can should review and can approve the merge request.

4. Select the issues that you want to link to the merge review request.

The issues you choose will be linked from the Merge Review page.

5. Click Publish Changes.

When you click Publish Changes, the dialog box displays the Git commands thatare automatically performed for you.

Chapter 4Publish the Application Extension

4-4

6. Click Close.

The changes can be merged after they have been approved on the Merge Requestspage. You need to use the Merge action on the Merge Requests page to merge theapproved changes.

Save Changes to the Git Repository with Git CommandsThe most current version of an application extension's files are stored in a remoterepository branch usually named "master". This branch is used to build the applicationextension. To get your changes into master, you first save the changes in the localbranch in your workspace to a remote repository branch, and then merge that remotebranch into the "master" branch.

When editing an application extension, you'll save all your changes to a localrepository branch in your workspace first. Branches are usually created from theremote repository "master" branch, but might also be created from a different remoterepository branch. Your workspace contains a local branch which is a copy (clone) ofthe remote branch. When editing your app extension, your changes are automaticallysaved in the local branch in your workspace and are not visible to others. To allowyour team members to see your changes, you need to update the remote branch withthe changes from your local branch.

After the remote branch is updated with your changes, a team member can view thechanges by creating a clone of the remote branch in their workspace. They can alsoview the source code in the repository, including all branches, by opening Git in VBStudio.

If other team members are also working on the application extension, your localbranch and the local branches in each of their workspaces might all be clones of thesame remote branch. You should update the remote branch with your local changesfrequently. This can help you to avoid accidentally making changes to files that

Chapter 4Save Changes to the Git Repository with Git Commands

4-5

someone else is also editing, which might result in a code conflict when adding yourchanges to the remote branch.

How Do I Save My Changes?After you edit files in your workspace you need to save them to a remote branch inorder to share the changes in your app extension with your team members. Until yousave those changes to a remote branch, they only exist in the local branch in yourworkspace.

When you make changes in your workspace, a badge is applied to the branch name inthe header to let you know that the changes in your local branch haven't been saved tothe remote branch.

Saving your changes to a remote branch is a two-step process: commit and push.The first step you must perform is a commit. When you make a commit you arebasically grouping the files in your local branch that you want to save to the remotebranch, and providing a description of the group. This may seem redundant, but ithelps document the process of saving files to the repository, which can be very helpfullater if you need to track down which files were changed.

For example, if you make some changes to add a new layout to include a field, whenyou "commit" the changes you can add a commit message describing the reason youupdated those files ("Added new layout X for field Y"). You then might change someother files to add a rule for the new layout, and add a commit message describingthose changes ("Added rule Z for layout X"). When you eventually save these files tothe repository, those commit messages can help you identify which files were changedand why. When you look at the list of changes made to the repository, you can easilysee what files were changed and the reasons for changing them.

The second step is push, which saves all the files in the groups that you've"committed" to the remote branch, so a single "push" might save several groups offiles. If you have edited some files but haven't committed them, they are not includedwhen you "push" your changes to the repository.

Files and artifacts can have the status Edited, Committed, or Pushed (the defaultstatus). The name of each file in the Navigator is color-coded to indicate its status.

Keep Your Local and Remote Branches in Sync to AvoidConflicts

If you and another team member are working together on an app extension, you willbe using the same Git repository and might be working off the same branch andediting the same files. This can result in a code confict, where you and a team membermake changes to the same line of code in a file.

To help minimize the number of conflicts, the best practice is to make sure your localbranch and the remote branch are in sync and up to date. You do this by committingand pushing often. Each time you commit or push changes to the branch, Git will

Chapter 4How Do I Save My Changes?

4-6

check the remote branch to see if there were any updates since the last time youchecked, and update your local branch with the changes.

If a code conflict occurs, you'll have to resolve it before you can update the branch withyour changes. VB Studio will let you know if there is a conflict when you try to commitor merge your changes, and you can use the conflict resolution editor to fix theproblems in each file by selecting whose changes you want to keep. You can continuewhen all the conflicts are resolved.

You can use the Audits pane in the Designer to scan and locate places in your codethat are flagged as errors because a conflict has not been resolved.

For details on resolving merge conflicts when merging a review branch, see Resolovea Merge Conflict in Managing Your Development Process with Visual Builder Studio.

Commit and Push Your ChangesAll the changes you make in the Designer are stored in the local branch in yourworkspace and are invisible to your team members until you commit and push them toa remote branch.

Your must explicitly commit your changes before you can push them to the remotebranch. You are prompted to commit and push the changes in your local branch if youtry to switch to a new branch in your workspace or choose to Share your changes.

To commit changes in your local branch:

1. Click the branch name in the toolbar and select Commit in the menu.

2. Enter a commit message to describe the changes you are committing. ClickCreate Commit.

Chapter 4Commit and Push Your Changes

4-7

3. Click the branch name in the toolbar and select Push in the menu.

4. Enter a commit message to describe the changes you are pushing to the remotebranch. Click Push to Git.

Chapter 4Commit and Push Your Changes

4-8

When your changes are pushed to the remote branch, the Push Content to GitRepository displays a message that says your files were successfully added.

You can see the changes that were added to the remote branch in the RecentActivities panel on the Project Home page. Pushing your changes adds all the filesthat you've committed since your previous push to the remote branch. The commitmessage for each commit included in the push is listed in the Recent Activities panel.

Chapter 4Commit and Push Your Changes

4-9

Create a Merge RequestAfter your changes have been pushed to the remote branch, you can create a mergerequest asking project members to review the changes before they are merged toanother branch or the master repository branch.

A merge request might be required to merge changes from a branch to the masterbranch in your project. In the merge request you can specify which team members youwant to review the changes. The requirements of the merge request will depend onhow your project is set up, for example, a certain member might be required toapprove the request before the changes can be merged. For details on how to createand work with merge requests, see Review Source Code with Merge Requests inManaging Your Development Process with Visual Builder Studio.

To create a merge request:

1. Click Merge Requests in the main menu to open the Merge Request page.

2. Click Create Merge Request.

3. In the New Merge Request dialog box, select the Git repository for the applicationextension, the target branch and the review branch. Click Next.

For the target branch, you should select the master repository branch for theproject if you are doing the final merge to the repository. For the review branch youshould select the branch containing the changes you want reviewed.

Chapter 4Create a Merge Request

4-10

You can merge a review branch into a branch that isn't master, but you should becareful when doing this, and its best to do this only when the review branch is abranch of the target branch.

4. In the Details set of the wizard, select the project members that you want to reviewthe changes. Click Next.

It is good practice to also provide as many additional details as you can about yourrequest, such as if the changes resolve an issue, and provide a summary of thechanges.

5. In the Description step of the wizard, add any additional details in the EditDescription field. Click Create.

Merge Changes From a BranchWhen you've finished making changes on your branch and your changes have beenapproved, you use the Merge Request tool to merge your changes to the target branchyou chose in your merge request, which can be another branch or master.

To merge a branch, you use the Merge command in a merge request that you createdor one where you were assigned as a reviewer. The target branch and the branch thatwill be merged are already defined in the merge request.

It's good practice to ask some project members to review the changes, but it isn’tmandatory to get approval from all reviewers before you merge the review branch.

Chapter 4Merge Changes From a Branch

4-11

Note that you can’t merge the review branch if the target branch is locked. If it's lockedyou need to contact the project owner to unlock the target branch. For details on howto merge branches, see Merge Branches and Close the Merge Request in ManagingYour Development Process with Visual Builder Studio.

To merge a branch:

1. Click Merge Requests in the main menu and open your merge request.

2. On the right side of the page, click Merge.

3. In the Merge dialog box, type a description of the merge and click Create a MergeCommit.

To delete the review branch after the commits are merged with the target branch,you can select Delete Branch in the dialog box.

When your merge is complete you'll see a summary of the merge request in theConversation tab. If you didn't select Delete Branch in the Merge dialog box, you candelete it now by clicking Delete Branch.

In the main Merge Requests window, you can open the table's Merged tab to confirmthat your review branch was merged to the target branch.

After merging a branch to master, the branch is automatically closed and you can nolonger use it. To make additional changes you'll need to create a new branch in yourworkspace or open an existing branch.

View Your App Extension DeploymentsAfter you've published your app extension, you can check your project's Environmentstab to see if it's been deployed to your development environment.

To view the deployed app extensions for your base application:

1. Click Enviroments in the main menu to open your project's Environments page.

Chapter 4View Your App Extension Deployments

4-12

2. Select the development environment for your app extension.

App extension projects usually only have one development environment that theextensions are deployed to.

3. Open the Deployments tab of your environment and click ApplicationExtensions.

4. Expand the node for your base application to see a list of deployed appextensions.

There might be several app extensions deployed to your base application, so you'llneed to look for the extension id and name in the list of deployed extensions toconfirm that yours has been deployed.

If you think your app extension should have been deployed but you can't find it in thelist, you should check the build jobs for your project to check if the job has finished, orcontact your project administrator if you think there might be a problem with deployingthe app extension.

Chapter 4View Your App Extension Deployments

4-13