Create an Extension

If you accessed VB Studio by clicking a link in Oracle Cloud Applications, your extension (also considered your workspace) is usually created along the way. However, if you're starting from VB Studio, you'll need to explicitly create an extension.

Note:

Before you create a new extension, make sure a Development environment is defined in your project and that it points to an active Oracle Cloud Application instance. Your Project Home page lists your project's environments:

Description of the illustration projhomeenv.png

If an environment is not defined for your project, contact an administrator or project owner to add one. You can find the project owner in the Team panel on the Project Home page.

To create a new extension:

1. If you haven't already, log into VB Studio and select the project you want to work in from the Organizations tab:
   Description of the illustration orgpage.png
2. On the Project Home page, select the workspace you want to work in, or click Manage Workspaces to create a new workspace:
   
   Description of the illustration manageworkspaces.png
   

   Remember that a workspace is tied to a Git repository, and that it's considered best practice to use a single Git repo for all changes made to a single App UI. So, if you know that someone else has already made changes to an App UI you're planning to work on, it's best to either clone or import the existing repository at this point, rather than create a new one. See Collaborate on an Extension.

3. On the Workspaces tab, select New, then New Application Extension:
   
   Description of the illustration newappext.png
   

   The New Application Extension dialog is displayed:
   
   Description of the illustration newappextensionnotexpanded.png
   

4. Enter a name for the extension. Because your extension may become available to others, keep these naming standards in mind:
   • Keep names meaningful and brief.
   • Do not use "Extension".
   • Do not use (or combine) generic phrases like "UI", "app", or "application".

   Tip:

   If you need to rename the extension later for some reason, you can do so on the Settings panel.
5. If you want, change the extension ID and workspace name. Both fields are automatically filled in based on the extension name, but you can change it if you like.
   • The extension ID (used internally by Oracle) by default adds the extension name to the prefix site_.
   • The workspace takes the extension name by default.
6. If multiple environments are available, select the Development Environment for your extension. 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 the Base Oracle Cloud Application field, select None to create an empty extension, or select an App UI if you know which one you want to configure.
8. Select a sandbox if your new extension will involve changes that have been made to the base app's data model in an unpublished Application Composer sandbox. (If a change is published, it's already part of the data model and therefore a sandbox isn't needed. But if the change is still in a sandbox, you need to make it accessible to your extension by naming the sandbox explicitly. You may also need to re-authenticate to the Oracle Cloud Application periodically to make sure you have access to the absolute latest data model.)
9. Click Create new repository, then enter the name of the Git repository and branch that will be created for storing your files.

   If you don't want to create a Git repository now—for example, you only want to experiment with creating an app extension—keep the Use Scratch repository option. Selecting this will create a repository in your workspace that only you can see. Build jobs won't be created for your app extension if you create a scratch repository instead of a remote Git repository. For more details, see Use a Scratch Repository.

10. Click Create.

    Note:

    After you create your extension, it's a good idea to go into Settings and provide a description for your extension right away. This will help people who are trying to add your extension as a dependency later understand what's in it.

From here you can create a new App UI, or configure an existing App UI.

Collaborate on an Extension

To work on an App UI, you must have a workspace; it's your ticket into the Designer. When you create a workspace, you must associate it with a Git repo—either one you create from scratch or, if you want to collaborate with someone who has already started configuring this particular App UI, a copy of the Git repo they've been working in.

In fact, if you know that someone else has already made changes to an App UI you're planning to configure, it's considered best practice to use the same Git repository in your workspace, rather than creating a new one.

If you need to work on an App UI that's already been worked on, you have two choices:

• Clone the repository in your own workspace
• Import a repo that has been exported as an archive into your own workspace

Clone an Existing Repository

When cloning an existing repository, you clone the branch containing the 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 use a branch used in another workspace, the owner of the Git repo will first need to push that branch. It will then be available for you to check out when creating a workspace that clones that repository.

To create an extension by cloning someone else's repository:

1. Select the project you want to work on from the Organization tab.
2. Click Workspaces in the left navigator (or select Manage Workspaces on the Project Home page), then click Clone from Git:
   
   
   Description of the illustration clonefromgit.png
   
   

   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 for the latest changes, but it 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. If multiple environments are available, select the Development Environment for your extension. 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.)
8. (Optional) Select the sandbox you want to use with this workspace, if any.
   
   
   Description of the illustration clonefromgitdialog.png
   
   
9. Click Create.

Import an Extension Archive

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 a file, you create a new Git repository and branch.

To create a workspace by importing an archive:

1. Select the project you want to work on from the Organizations tab.
2. Click Manage Workspaces:
   Description of the illustration manageworkspaces.png
3. Click Import to open the Import from file dialog:
   Description of the illustration importfromfile.png
4. 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 extension archive. If it's not, you'll see a message that you can't create a workspace by importing it.

   The Import from file screen looks like this:
   
   Description of the illustration importarchive.png
   

5. Enter a name for the new workspace.
6. If multiple environments are available, select the Development Environment for your extension. 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. Choose a sandbox if you need one.
8. Choose the Git repository you want to use with the workspace:
   • Choose Use a scratch repository if you're just experimenting;
   • Choose Create a new repository (based on the one you're importing) and provide a name for both it and the branch you want to use.
9. Click Import.

When your new workspace opens, you'll see the contents of the archive you just imported in the Designer, and you can start working from there.

Related information: Export Your Workspace as an Archive

Use a Scratch Repository

When you create a workspace, you have the option to create a scratch repository, rather than creating a new repository (which is based on the master branch of the project's 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.

When you create a Git repository for your workspace, VB Studio automatically sets up packaging and build jobs (also known as a build pipeline) so that you can build and publish your artifacts simply by clicking Publish. If you opt for a scratch repository, however, these jobs are not set up for you.

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. See Push a Scratch Repository to a Remote Repository for more information about using scratch repositories.