Create a Workspace

To work on a visual application, you must have a workspace; it's your ticket into the Designer.

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 to. All your workspaces will probably use the same development environment because a project typically has only one. This environment must support the type of project you are working on, so to create a workspace for a visual application, your project must be associated with a Visual Builder instance. If the development environment isn't defined, you won't be able to create a workspace; ask the project owner or an administrator to create one for you before you try to create a workspace.

Note:

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

A workspace is typically associated with a Git repository—either one you create from scratch or, if you plan to collaborate with someone who has already started developing an application, a copy of the Git repo they've been working in. Because Git repos store your source files, it's helpful to familiarize yourself with some concepts underlying Git.

How to Use Git Branches to Isolate Changes

Your visual application's Git repository is automatically created when your project is first set up. In most cases, this project repository includes the default branch (usually, main) and an associated branch where your changes are stored. The default branch is typically the source from which your visual application is built.

Because the default branch represents the source of truth—code that is tested and ready to be pushed to production—it is usually protected and any changes to this branch will require approval. If you want to make changes to the default branch (main, for example) but don't have permission to push to it, you'll make your changes in a separate branch based on main, then create a merge request to get your changes reviewed. After your changes are approved, you'll merge the changes in your branch to the main branch and make your updates public. Even if a public branch isn't protected, it's good practice to always work on a private branch and merge your changes to a public branch only after review.

You create a separate branch based on the main branch when you create a workspace. You can have separate branches for each new feature or change to your visual application. You can even use separate branches to create two different versions of one feature. For example, you might want to work on two different versions of a table. By creating a branch for each version, you can work on one version in one branch with (say) Workspace A mapped to it, then switch to another branch using Workspace B to work on the other version. This way, you can use workspaces to isolate the branches with your changes. After you decide which version you want to use, you can share the branch with others and delete the branches you no longer need.

Watch this video to learn the basics, like remote and local repositories, as well as how they tie in to workspaces:

What's a Scratch Repository

When you create a workspace, you have the option to create a scratch repository, instead of a new repository or 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 deploy your visual app, you might want to create a new repository and branch, instead of a scratch repository. When you create a workspace with a new repository, a build pipeline is automatically generated for you.

To deploy changes 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.

Create a Workspace for a New Visual Application

Create a visual application when you want to start developing a new visual application with a new Git repository.

1. If needed, select the project where you want to create a visual application on the Organization page.
2. In the left navigator, click Workspaces .
3. On the Workspaces page, click New, then select New Visual Application.
4. In the New Visual Application dialog, enter a name for the workspace. Because a workspace is synonymous with a visual application, this name will also be used for the visual application that VB Studio creates.
5. If multiple environments are available, select the Development Environment. Only environments that are in the same identity stripe as the logged-in user are listed. (If only one environment is available, it is automatically selected for you.)
6. If you want to use a template other than the default VB application template, click Change Template in Visual Application Template. The default application template does not create any artifacts, apps, or other resources. Other templates might create resources or apps that already include artifacts.

   Tip:

   Create a workspace using the Oracle Visual Builder Cookbook template to browse through samples of common coding patterns and learn by example. See Work With Code Samples.
7. In Git Repository, choose between creating a new repository where you and others can work on the visual application and using a private scratch repository that is visible only to you.
   • To create a new repository for your visual application, click Create new repository, then enter a repository name and working branch name.
   • To use a scratch repository for your visual application, click Use scratch repository (selected by default).
8. Click Create.

VB Studio creates a visual application workspace and opens it up in the Designer, so you can start to create your web apps and define their data sources. A new visual application does not contain any artifacts, but the application's file structure and some resources are created for you by default. You can use the Welcome screen to help you decide which artifacts you want to create first:

Description of the illustration welcome.png

Create a Workspace by Cloning an Existing Repository

If you want to work on a visual application that's already been started, even by another developer, you can clone the original Git repository and use it as a starting point for a new workspace.

1. On the Organization page, select the project where you want to create a visual application.
2. In the left navigator, click Workspaces , then Clone from Git.

   Tip:

   You can also create a workspace from the Git repositories page: Click Git , then Create Workspace.
3. Enter a name for your workspace.
4. Select the Git repository to clone. If you're cloning from the Project Home page, the repo is already selected for you.
5. Select the repository branch that has the changes you want in your workspace. This is typically main, the default branch that contains the most up-to-date changes, but can be any branch.
6. Select New branch from selected and enter a name for the branch you want to create. You can create additional branches and switch between branches in the workspace.
7. If multiple environments are available, select the Development Environment. Only environments that are in the same identity stripe as the logged-in user are listed. (If only one environment is available, it is automatically selected for you.)
   
   

   
   Description of the illustration vbs-cloneworkspace.png

   
   
8. Click Create.

VB Studio creates a workspace and opens it up in the Designer, so you can start to create your web apps and define their data sources.

Create a Workspace by Importing an Application Archive

If a team member gives you an archive of a visual application, you can import it to create a workspace containing all the files in their branch of the application's Git repository. When you create a workspace by importing a file, you create a new Git repository and branch.

1. On the Organization page, select the project where you want to import the visual application.
2. In the left navigator, click Workspaces .
3. Click Import.
4. In the Import from file dialog, drag your visual application archive file from your local system to the drag-and-drop area. Or, click the drag-and-drop area and use the file browser to locate the archive on your local system.
5. In the Workspace name, enter a name for your workspace.
6. If multiple environments are available, select the Development Environment. Only environments that are in the same identity stripe as the logged-in user are listed. (If only one environment is available, it is automatically selected for you.)
7. In Git Repository, choose between creating a new repository where you and others can work on the imported visual application and using a private scratch repository that is visible only to you.
   • To create a new repository for your imported visual application, click Create new repository (based on the one you're importing), then enter a name for the new repository and the branch you want to use.
   • To use a scratch repository for your imported visual application, click Use scratch repository (selected by default).
8. Click Import.

When VB Studio creates a workspace and opens it up, you'll see the contents of the archive you just imported in the Designer, and you can start working from there.

Create a Workspace Without an Environment

Workspaces almost always require an environment against which you develop and deploy your application—but you can create a workspace without an environment simply to explore VB Studio's visual development capabilities within the Designer.

Note:

When your workspace doesn't have an environment, you won't be able to create business objects or deploy (share and publish) your app—though you can click Publish in the header to merge your changes to the default branch (main) in the project's Git repository. To explore VB Studio without any restrictions, you need to add a Visual Builder instance to your VB Studio instance's environment.

To create a workspace without an environment:

1. On the Organization page, select the project where you want to create a visual application.
2. In the left navigator, click Workspaces .
3. On the Workspaces page, click New, then select New Visual Application.
4. In the New Visual Application dialog, enter a name for the workspace.
5. Leave the Development Environment set to No environments.

   Note:

   If this option isn't available to you, it means that this functionality has not been enabled in your environment. File a service request with Oracle Cloud Support.
6. If you want to use a template other than the default VB application template, click Change Template in Visual Application Template. The default application template does not create any artifacts, apps, or other resources. Other templates might create resources or apps that already include artifacts.
7. In Git Repository, choose between creating a new repository where you and others can work on the visual application, and using a private scratch repository that is visible only to you.
   • To create a new repository for your visual application, click Create new repository, then enter a repository name and working branch name.
   • To use a scratch repository for your visual application, click Use scratch repository (selected by default).
8. Click Create.

When your visual application workspace opens in the Designer, you can start to create your web app, define a service connection to access data, design your app's pages, and preview the app as it would appear to users.