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.
- 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 - 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.pngRemember 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.
- On the Workspaces tab, select New, then New Application Extension:
Description of the illustration newappext.pngThe New Application Extension dialog is displayed:
Description of the illustration newappextensionnotexpanded.png - 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. - 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.
- The extension ID (used internally by Oracle) by default adds the extension name to the prefix
- 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.)
- 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.
- 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.)
- 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.
- 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.
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:
- Select the project you want to work on from the Organization tab.
- Click Workspaces in the left navigator (or select Manage Workspaces on the Project Home page), then click Clone from Git:
Tip:
You can also create a workspace from the Git repositories page: Click Git, then Create Workspace.
- Enter a name for your workspace.
- Select the Git repository to clone. If you're cloning from the Project Home page, the repo is already selected for you.
- 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. - (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.
- 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.)
- (Optional) Select the sandbox you want to use with this workspace, if any.
- 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:
- Select the project you want to work on from the Organizations tab.
- Click Manage Workspaces:
Description of the illustration manageworkspaces.png - Click Import to open the Import from file dialog:
Description of the illustration importfromfile.png - 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 - Enter a name for the new workspace.
- 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.)
- Choose a sandbox if you need one.
- 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.
- 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 so your team members can clone it.
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 initially set up for you, unless you decide you want to publish the changes in your scratch repo after all. To do this, you'll need to first push your changes to a remote repository, at which time VB Studio asks you to identify the target repository, then creates the required build and package jobs for you.
See Push a Scratch Repository to a Remote Repository for more information about using scratch repositories.