6 Use Workspaces and the Designer

Create or edit extensions and visual applications in a workspace. (The changes you make in the Designer are stored as source code in the Git repository associated with your workspace.)

What Is the Designer?

VB Studio includes the Designer, an editing and publishing environment that you use to create web or mobile applications (collectively known as visual applications), or to customize your Oracle Cloud Applications through extensions. For example, you may want to extend an Oracle Cloud Application so that certain fields are displayed only for managers, while the same fields are hidden from your users that aren't managers.

What Is a Workspace?

A workspace defines the resources that are available to you when you open the Designer. These resources include the Git repository—and the branch—containing the source files you want to use, the extension's or visual application's development environment, and, in certain cases for extensions, a sandbox. You can think of a workspace as your private editing environment while you're working with the Designer. If you’re not using VB Studio to create or update an extension or a visual application, you won't need a workspace.

There are three ways to access a workspace (and thus, the Designer):

  • From the Project Home page:

    Description of workspaces-list-project-home.png follows
    Description of the illustration workspaces-list-project-home.png

  • From the Workspaces option in the left navigator:

    Description of workspaces-list-designer.png follows
    Description of the illustration workspaces-list-designer.png

    In either case, click the workspace name to launch the Designer or right-click and select Open in New Tab to open the workspace in a new tab. (To see all the workspaces in the project while on the Workspaces page, click the Others toggle button.) Once you’re in the Designer, you can change the Git repository branch, if you wish, but you can’t change the Git repository where your work is stored—that’s set at the project level.

  • From an Oracle Cloud Application editing session:

    Description of fa-edit-page-link.png follows
    Description of the illustration fa-edit-page-link.png

    When you click Edit Pages in Visual Builder while in Oracle Cloud Applications, you are automatically sent over to Visual Builder Studio. If you have a workspace already set up for this app, that’s where you’ll land in the Designer. If you don’t, VB Studio will create a workspace for you.

In some cases, you may want to create a workspace explicitly, rather than allowing VB Studio to create one for you. Create a Workspace explains these options.

You're the only one on your team who can access your workspace. Changes to files you make in your workspace aren't visible to other team members until you save them to a branch (or unless you use the Share action). 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 while you’re in the Designer.

See What Is a Workspace? in Extending Oracle Cloud Applications with Oracle Visual Builder Studio for additional information about using workspaces with extensions. See Create Visual Applications in VB Studio for information about using workspaces with visual applications.

Create a Workspace

A workspace may have automatically been created for you when you opened VB Studio from a page. If not, or if you have other requirements, you can create a workspace explicitly.

You can create workspaces in projects where you've been added as a team member. A workspace requires an environment against which you develop your application and deploy it to. A project could have one or more environments available for different purposes, with workspaces mapped to each of these environments:

  • An app extension project will often have one development environment that one or more users will use to extend/configure the Oracle Cloud Application app. There will, however, be additional environments that users will publish/deploy their changes to and, of course, the production environment. Many projects with extensions have three environments - the first one is the development environment, the second is an intermediary one that's used for additional testing, and the third one is the production environment.

  • A visual app project will also often have one VB development environment in which visual apps are developed. However, there some cases that may have two development environments, for example one that is running a new VB release while the other is running a previous VB release. Both of these will be two separate environments in the visual app project.

The environment(s) must support the type of project you are working on. To create a workspace for a visual application, your project must be associated with a Visual Builder instance. To create a workspace for an extension, your project must be associated with an Oracle Cloud Application instance.

If the development environment isn't defined, you won't be able to create a workspace. You'll need to ask the project owner or an administrator to create one for you before you try to create a workspace.


Typically, the Visual Builder instance added to your visual application's environment uses the same identity domain as your Visual Builder Studio instance. If you choose a Visual Builder instance from a different identity domain as your deployment environment, you'll see a warning about setting up the Allowed Origins configuration. If you see this, you'll need to talk to your administrator to make sure your instance's domain is added to its list of allowed origins, as described in Allow Other Domains Access to Services.

Depending on what you need in your workspace, the type of template you select and the information you’re asked to supply during creation varies considerably. Here are the options for creating a workspace:

  • Clone an existing Git repository that contains an application extension or visual application

    Most people will create a workspace using the Clone from Git option, once a repository with the visual application or application extension that the team works on has been created. One team member will create the Git repository, so you and each member of your team will use the clone option to create at least one workspace so they can do their work. Or, perhaps you want to continue working on a branch that someone else has started. If you work on multiple branches and want to move freely from branch to branch without having to make sure that you added/committed changes you made in a branch, then you'd likely use the clone option to create a new workspace on the same repository.

    See Create a Workspace Using an Existing Repository if you're creating a visual application or Create a Workspace Using an Existing Repository if you're using this workspace for an extension.

  • Create a new visual application

    See Create Workspace for a New Visual Application for instructions on how to use this option.

  • Create a new extension

    See Create a Workspace for a New Application Extension for instructions on how to use this option.

  • Import an exported archive that contains an extension or a visual application

    You'd use this option when you want to base your new visual application on a valid existing artifact that you’ve already exported from Visual Builder or Visual Builder Studio to your local system. Or, if a team member gives you an archive of an extension, you can import it to create a workspace containing all the files in their branch of the extension's Git repository. When you create a workspace by importing an archive, you create a new Git repository and branch. By using the import and export functionality, you can share application sources and move applications between instances.

    When you select an archive to import, or drag it to the upload area in the dialog, VB Studio checks to see if the archive is valid for the operation (contains a visual application or an extension).

    See Import an App Extension Archive if you're creating an extension or Create a Workspace by Importing a Visual Application if you're using this workspace for a visual application.

What is a Scratch Repository?

When you create a workspace, you have the option to create a scratch repository, rather than creating a new repository or using a clone of the project's Git repository. You may want to create a scratch repository when you are experimenting and you're pretty sure you'll never want to merge your changes into an existing repository. A scratch repository is a private repository that only exists in your workspace. Only you can use the scratch repository, and it's deleted when you delete the workspace. If you want to let your team members use your scratch repository, you'll need to push the scratch repository to a new remote repository.

No build pipeline is set up for you if you create a scratch repository when creating your workspace. If you want to build and publish artifacts, you might want to create a new repository and branch instead of a scratch repository. When you create a new repository while creating a workspace, a build pipeline is automatically set up for you when the workspace is created.

If you want to build and publish artifacts from a scratch repository, you'll need to first push the scratch repository to a new remote repository. After the new repository is created, you or your project administrator will need to set up build jobs for the repository.

Push Your Scratch Repository to the Remote Repository

If you chose to use a scratch repository when creating your workspace, you'll need to push the scratch repository to the remote repository if you want other team members to see its contents. Pushing your scratch repository creates a new remote Git repository in the project.

  1. Open your workspace.
  2. In the header, click the arrow next to your Git repo and select Push in the menu.
  3. In the Push Scratch Repository to Remote dialog, type a repository name. This name cannot be the same as an existing project repository.
  4. Enter a commit message, and click Push Repository.

After you push your scratch repository to the new remote repository, you can create a pipeline with jobs for packaging the build artifacts from the repository and deploying the artifacts to your environment.

Understanding Default Branch Names

When a new repository, both scratch or non-scratch, is created for a workspace, main is now used as the default branch.

When a repository is cloned, the default branch, which could be master, main, or anything that has been set manually, is used to determine whether it contains an application and can be cloned.

Publish actions always use the current default branch as the target branch. Existing workspaces behave as they always have — VB Studio won't try to automatically update the default branch to main. So, a scratch workspace that was created prior to this release will continue to use master as the repository default when it is pushed, whereas a newly created one will use main.

If you change the repository's default branch after the workspace's build jobs have been created, you'll need to manually update those jobs to use the new default branch name.

Manage Workspaces

Some workspace management tasks can be done by an individual, while others must be performed by the project owners.

The Project Home page displays your personal workspaces associated with the selected project:

Description of workspaces-list-project-home.png follows
Description of the illustration workspaces-list-project-home.png

The Workspaces tile on that page has Refresh Refresh icon buttons for its environments, so you can reload them independently from each other. Click a workspace name in the tile to open the Designer in the context of that workspace (that is, with the correct Git branch and sandbox, if used).

Depending on your permissions, you can use the action menu on the Workspaces page to perform various workspace management tasks:

Description of workspaces-list-designer-action-menu.png follows
Description of the illustration workspaces-list-designer-action-menu.png

The activities stream on the Project Home page will display notifications about most, but not all, of these tasks. Notifications for opening workspaces, opening a workspace in new tab, and exporting workspaces won't be shown, but notifications for creating, deleting, importing, changing ownership, and renaming workspaces will be displayed.

Here’s what you can do from the Workspaces page:

  • Use Mine to view your personal workspaces only, or use Others to view all the workspaces associated with this project. If the list is long, you can use the search field to find specific user or workspace names.
  • Open the workspace in a new tab. This is convenient when you want to work in another project area, such as Issues, without closing and leaving the page where you opened the workspace. Both pages can be open simultaneously.
  • Delete a workspace.

    As an individual working on extensions or visual applications, it’s a good idea to delete a workspace once you’ve finished with it (that is, once you’ve used the Publish action to push your changes into the main Git branch).


    If there are uncommitted changes to the workspace being deleted, the Confirm Delete dialog will indicate this. The dialog will also indicate if the workspace contains changes that were committed but not pushed.

    If you’re a project owner, you can delete workspaces that are or were associated with projects that you own, even workspaces that you don't own or didn't create. Try not to let inactive workspaces accrue in your project, as they still count against your total resource allocation and thus have a (hidden) cost.

  • Both the project owner and the workspace owner can rename a workspace, or export it to an archive that can later be imported to another project. See Export a Visual Application for more information.
  • Both the project owner and the workspace owner can assign a new owner for a workspace by selecting Change Ownership in the action menu. This may be necessary for making changes, like resolving conflicts, pushing changes, or managing workspaces when the workspace owner has left the company or organization.

    Once a workspace has a new owner, it behaves as if the new owner created the workspace. Only the new owner (and the project owner) can work on that workspace going forward. The original owner could still see the workspace by setting Others, if he or she is a project owner, but would lose all access to the workspace.