2 Get Started

To work on your application extension, you need to have a workspace. There should already be a workspace for the extension, but if you need another workspace for some reason, you'll need to create the workspace manually.

If you're not sure why you need a workspace, see What Is a Workspace and Why Do I Need One?

Open Your Extension

If you're used to clicking Edit Page in Visual Builder Studio in your Oracle Cloud Application to open an extension, that option is no longer supported for classic application extensions. Instead, to work on an extension you must first open the workspace for the extension directly in VB Studio:

1. Log into VB Studio.
2. Select your project on the Organization page.
3. In the Workspaces pane, click the workspace you've been using for your app extension.

   If you want to create a workspace for an existing app extension, you can create one in the Workspaces page:

   
   
   
   Description of the illustration project-home-workspaces.png
   
   

   After opening your workspace, you should then see something like this:

   
   
   
   Description of the illustration designer-welcome-page.png
   
   

   At this point you can select an app extension page or a layout in the left navigator, after which you’ll be placed in that artifact's editor. More on that later.

Create a Workspace

A workspace defines the resources available to you when you open the Designer. You can think of a workspace as your editing context while you're working with the Designer.

Before you create a new workspace, make sure a Development environment is defined in your project and it points to an active Oracle Cloud Application instance. Your Project Home page lists your project's environments. Each of your workspaces will probably use the same development environment, because a project typically has only one. If an environment is not defined for your project you should contact an administrator or project owner to add one.

There are two ways to create a workspace.

Create a Workspace Using an Existing Repository

If you need to work on an app extension that's already been started, even by another developer, you can clone the original Git repository when creating a new workspace.

When cloning an existing repository, you clone the branch whose changes you want in your workspace. Usually, you'll want to clone the main branch to ensure that your new branch contains the most up-to-date changes.

Two workspaces shouldn't use the same branch. If you want to create a workspace that uses a branch that's also used in another workspace, you'll need to make sure the branch has been pushed to the repository. You'll then be able to clone the branch when creating your new workspace.

To create a workspace by cloning a repository:

1. Click Workspaces in the VB Studio left navigator to view your workspaces in the project.

   Even if you've never explicitly created a workspace before, you may see workspaces in this list. That's because a workspace is created for you automatically when you open VB Studio from a page in your Oracle Cloud Application.

2. Click Clone from Git.
3. In the Clone from Git dialog, enter a name for your workspace.
4. Select the Git repository to clone.
5. Select the repository branch you want to check out. This is typically main for the latest changes, but can be any branch.
6. (Optional) 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. Select the Development Environment. You might have only one option.

   Each of your workspaces will probably use the same development environment because a project typically has only one. The environment must also support the type of project you are working on, so to create a workspace for extending an Oracle Cloud Application, your project must be associated with an Oracle Cloud Application environment. If you don't have an environment, ask the project owner or an administrator to create one for you.

8. Optional: Select the sandbox you want to use with this workspace, if any.
   
   

   
   Description of the illustration workspace-create-clone.png

   
   
9. Click Create.

VB Studio creates a workspace and opens it up in the Designer, so you can edit the extension.

Create a Workspace by Importing an App Extension Archive

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

To create a workspace by importing an archive:

1. Click Workspaces in the VB Studio left navigator to open the Workspaces page.
2. Click Import to open the Import from file dialog box.
   
   

   
   Description of the illustration workspace-create-fromfile.png

   
   
3. Drag the archive into the Drag and Drop area, or click in the drop area to locate the archive on your computer.

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

4. Type a name for the new workspace.
5. Select the development environment for the app extension, and a sandbox if you need one. Click Create Workspace.
6. Choose the Git repository you want to use with the workspace:
   • Use scratch repository to create a new scratch repository;
   • Create new repository and provide a name for the new Git repository and branch that'll be created in the workspace.

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.
   
   

   
   Description of the illustration push-scratch-repo.png

   
   

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.

Set Up a Build Pipeline for a Scratch Repository

When you create a scratch repo, Visual Builder Studio doesn't automatically create package and deploy jobs for your app extension or visual app as it would otherwise. If you decide you want to publish what's in your scratch repo, you'll need to create these jobs manually. After setting up the jobs, you can create pipelines to run the package jobs and deployment jobs in sequence. Usually you'll want to set up one pipeline for deploying your app extension to your development instance, and a second one to deploy to the production environment. The steps for setting up the jobs in the two pipelines are basically the same, but some of the configuration options might differ, for example, the security options and credentials for deploying to a production environment might be different from those for the development environment.

If you've already created a workspace with a remote repository, your project should already contain packaging and deployment jobs that were automatically set up for the remote repository. While these jobs were configured for a different repository, you can copy them when creating a build job, and then reconfigure the details in your copy as needed. If your project doesn't contain any jobs, you'll need to complete all the steps for configuring the new jobs.

For more detailed steps on how to configure packaging and deployment jobs, see Create and Configure Production Build Jobs in Administering Visual Builder Studio.

To set up a development pipeline for a scratch repository:

1. Push your scratch repository to create a new remote repository.
2. Click Builds in the VB Studio left navigator.
3. Create a build job to package your artifact:
   1. In the Builds page, click Create Job in the Jobs tab to create a build job to package your artifact.
   2. Type a name for the package job and select the System Default OL7 for Visual Builder template. Click Create.

      If your project already contains a similar packaging job, you can select Copy from Existing to use it as the basis of your new job. You'll need to set the job's Git repository to your new remote repository.

   3. Set the job's details in the Job Configuration page. Click Save.

      When configuring the packaging job, you select your new remote repository in the Git tab. If you want the packaging job to start each time changes are added to the remote repository, select Automatically perform build on SCM commit.

      
      

      
      Description of the illustration build-job-configuregit.png

      
      
4. Create a job to deploy your build artifact to your development instance.
   1. Return to the Builds page, then click Create Job to create a new job to deploy your build artifact to your development instance.
   2. Type a name for the deploy job and select the System Default OL7 for Visual Builder template. Click Create.

      If your project already contains a similar deployment job, you can select Copy from Existing to use it as the basis of your new job. If you're not deploying to the same instance, you'll need to set the target instance and credentials in the Steps tab.

   3. Set the job's details in the Job Configuration page. Click Save.

      When setting the target instance, select your development environment.

5. In the Builds page, open the Pipelines tab, then click Create Pipeline and type a name for your new development pipeline. Click Create.
6. Design your pipeline by adding the packaging and deployment jobs you created. Click Save.

   For the steps for designing the pipeline, see Set Up Production Build Pipelines.

If you set the packaging job to run each time a change is committed to the remote repository, you can use Publish in the header to commit your changes to the repository and start the pipeline. You can also start jobs and pipelines manually in the Builds page.

For details and more configuration options for builds and pipelines, see Set Up the Project to Deploy to Production in Administering Visual Builder Studio.

Use Branches to Isolate Changes

The repository for your app extension was automatically created when your project was created. When you create a workspace, you name the branch in the repository where your changes will be stored. You can have separate branches for each new feature or change to your app extension.

You can use separate branches for changes you want to make for two different sandboxes, or for different versions of a feature that use the same sandbox. For example, when you are modifying a table component in your app extension, you might want to work on two different versions of the table. By creating a branch for each version, 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 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.

If you want to rename or delete a branch, you can click the branch name in the header to open the Git menu containing the Rename Branch and Delete Local Branch commands.