How Do Sandboxes Relate to Git Branches?

There is no strict association between an Oracle Cloud Applications sandbox and a particular Git branch in your local repository. In fact, you can associate any sandbox to any Git branch in your repo while you're working on your extension in your private workspace.

As described in How Do I Use My Sandbox in Visual Builder Studio?, a sandbox hosts unpublished changes made to an Oracle Cloud Applications data model. Once you or another team member publish the sandbox, the changes are committed to the data model, so the sandbox is no longer needed and no longer available. If you want to refer to unpublished data in your extension, you simply associate your current Git branch with that sandbox. The typical workflow looks like this:

1. In your Oracle Cloud Application, you create a sandbox to make a change to the data model, like adding a new column to a dynamic table.
2. When you create a workspace in VB Studio, you specify the sandbox you want to access while making UI changes in your extension.

   If you jump over to VB Studio using the Edit Page in Visual Builder Studio option, we automatically add the sandbox association to your workspace for you. When accessing a workspace via this option for the first time (something that is typical when you create an Application Extension project and are yet to open the workspace), your workspace will be set to your Oracle Cloud Application's active sandbox if one isn't associated with your workspace.

3. Also while creating your workspace, you can create a new Git branch to house the UI changes you plan to make. Or, if you've previously made UI changes on a branch and want to continue with that branch, you can select it here.

Switch a Sandbox

You might need to switch sandboxes in your workspace if the one you're using was deleted or published. You can also switch when you want a sandbox that defines an alternative data model, or if yours is using the mainline data model (indicated by the None sandbox in the header).

Before you switch a sandbox, see How Do I Use My Sandbox in Visual Builder Studio? for best practices on working with sandboxes.

1. Click the Sandbox menu in the header:
   
   
   Description of the illustration sandbox.png
   
   
   You can also click the Git menu, next to the name of the current branch, in the header.
2. Select Switch Branch/Sandbox.

   The Switch Branch/Sandbox dialog displays the current branch in the Branch drop-down list and the number of uncommitted files, if any.
   
   Description of the illustration switchbranch.png
   

3. Choose the appropriate option:
   • To switch branches, select the branch that you want to switch to.
   • To create a new branch, select New branch from selected and enter the name for the new branch.
   • To associate this branch with a new sandbox, choose from the Sandbox drop-down. Some sandboxes might be marked "Unpublishable", which means they either have dependencies that haven't been resolved or were created without the ability to publish. Avoid choosing an unpublishable sandbox, as doing so is likely to break your extension.
     
     
     Description of the illustration switchsandbox.png
     
     
4. Click Commit and Switch (or Switch if you cleared the Commit changes before switching (recommended) check box).

Refresh a Sandbox

You might need to refresh a sandbox associated with your workspace to pick up the latest changes from other published sandboxes. VB Studio will notify you if this is required, for example, as shown here:

Description of the illustration refreshsandbox.png

Clicking Refresh in the message will refresh your sandbox. You can also do this using Refresh in the Sandbox menu:

1. Click the Sandbox menu in the header:
   
   
   Description of the illustration sandboxmenu.png
   
   
2. Select Refresh. This option is enabled only when your sandbox needs to be refreshed.

Disassociate a Sandbox

You can remove the sandbox currently associated with your workspace if you no longer need it. Removing a sandbox breaks the relationship between the Git branch and the sandbox and will likely impact your app's logic as well as the user interface. Proceed with caution.

1. Click the Sandbox menu in the header:
   
   
   Description of the illustration sandboxmenu.png
   
   
2. Select Disassociate.
3. In the Disassociate Sandbox dialog, click Disassociate to confirm your action.

Once the sandbox is disassociated, your workspace is set to the None sandbox (which uses the mainline data model). Make sure you resolve any issues reported in the Audits pane.

Publish a Sandbox

After you're done making changes to your extension, publish the sandbox to make your changes available to all users. Remember that you can't make changes to a sandbox once it's published, so make sure you adequately test and verify your extension's code before publishing your changes.

1. Click the Sandbox menu in the header:
   
   
   Description of the illustration sandboxmenu.png
   
   
2. Select Publish.
3. In the Publish sandbox dialog, click Publish to confirm your action.

Once the sandbox is published, your workspace is set to the None sandbox (which uses the mainline data model, now with your changes).

Any workspaces associated with the published sandbox must be switched to another sandbox.