5 Set Up VB Studio for Developing Visual Applications

This chapter tells you how to set up Oracle Visual Builder Studio (VB Studio) so that your users can create visual applications.

A visual application is a responsive web or native mobile application developed using VB Studio's browser-based development environment. You deploy a visual application to a Visual Builder instance or to a Visual Builder instance available in Oracle Integration. The Visual Builder instance must be version 19.4.3.1, or later.

Set up Visual Builder Studio

The following table has a summary of how to set up VB Studio for developing visual applications.

To perform this action:	See this:	Why do I need to perform this action?
1. Get access to Visual Builder instances.	Get Access to Visual Builder Instances	To deploy an app, you need a user's credentials who can deploy apps to the Visual Builder instance. If an instance isn't available, you must create it.
2. Get the required IDCS roles assigned to you.	Get the Required IDCS Roles	To create and set up the VB Studio instance, you must be assigned some specific IDCS roles.
3. Access your VB Studio instance or create an instance, if necessary.	Access Your VB Studio Instance	To use any Oracle Cloud service, you must have access to an instance of the service. Oracle Cloud Application customers will already have a VB Studio instance as part of their account. OCI customers might need to create an instance.
4 (Optional) Configure VB Studio to run build jobs and pipelines.	Configure VB Studio to Run Build Jobs and Pipelines	To run build jobs and pipelines, you must configure VB Studio to connect to an OCI account or the built-in free account.

Note:

If you're developing a visual application using an instance of VB Studio that was provisioned in your Oracle Cloud Applications account, follow the procedures in Create and Set Up a Project for Development (Different Identity Domain).

Set Up the VB Studio Project

After setting up VB Studio, follow these steps to create and set up a project for developing your visual applications.

To perform this action:	See this:	Why do I need to perform this action?
1. Create a project for visual applications and set up the project for development.	Create and Set up a Project	To develop a visual application, you must create a VB Studio project and set up the project for your developers.
2. Add users to the project.	Add Users to the Project	To allow your team members to access the visual application project, invite them to join the project.
3. (Optional) Configure advanced settings.	Optional Configuration	These settings are optional, depending on your configuration.
4. Developers can now create visual applications.	What Next?	This is the main development stage for your visual app.

Set Up the Project to Deploy to Production

After setting up the project, follow these steps to set up the project for deploying your visual application to the production instance.

To perform this action:	See this:	Why do I need to perform this action?
1. Add the Visual Builder production instance to an environment.	Add the Visual Builder Production Instance to an Environment	First, create an environment and add the Visual Builder production instance to it.
2. Create the packaging and deployment build jobs, and set up a build pipeline.	Create a Production Packaging Build Job, Create a Production Deployment Build Job, and Create and Configure a Pipeline	Next, create and configure the packaging and deployment jobs so that your visual applications will be promoted to your Visual Builder production instance.
3. (Optional) Restrict access to the build jobs.	Configure a Job's Privacy Setting	To restrict who can view the job's configuration, edit it, or run its build, you should mark both packaging and deployment jobs as private.

Before You Begin

Before you set up VB Studio, you may want to review VB Studio key concepts in Key Concepts, Components, and Terms. You should also learn about the built-in free account, its free VM build executor, and best practices, as described in this section.

Get Access to Visual Builder Instances

You can deploy a visual application to a standalone Visual Builder instance or to a Visual Builder instance that's part of Oracle Integration.

It’s important to keep these things in mind before you deploy a visual application to a Visual Builder instance:

• The Visual Builder instance must be version 19.4.3.1, or later.
• To ensure that business objects work properly, your Visual Builder administrator must manually add the VB Studio hostname to the allow list for each Visual Builder instance. For more information, see Add an Allowed Origins Domain.
• If you need to create a VB Studio instance, create it in the same Oracle Cloud account and identity domain as the Visual Builder development instance. See Create the VB Studio Instance.
• Follow your organization's guidelines to create and set up Visual Builder instances. Your guideline may suggest to create instances for different software development environments, such as development, integration, test, pre-stage, stage, pre-production, and production. You can create these instances in different identity domains or in a common identity domain.

  This documentation assumes that you have created and set up Visual Builder instances for development and production environments, where each instance is in a different identity domain.

To deploy your visual application to Visual Builder development and production instances, you'll need credentials of users who can access them.

If an instance isn't available to develop your visual application, then do this:

1. Create a Visual Builder Service Instance.

   To create an instance, you'll need the IDCS VISUALBUILDER_ENTITLEMENT_ADMINISTRATOR service role.

2. Add an IDCS User to Your Cloud Account and assign the user a Visual Builder role to connect and deploy applications.

You should also make sure that administration settings in each Visual Builder instance is configured. If you’re a Visual Builder runtime administrator, sign in to the Visual Builder runtime to complete these tasks that are described in Administering Oracle Visual Builder.

• Access Instance Settings
• Configure Security Options for Applications
• Set Page Messages for Access Denied Errors
• Allow Other Domains Access to Services
• Switch to Your Own Oracle DB Instance
• Reset an Expired Password or ATP Wallet for Your Oracle DB Instance
• Manage Self-signed Certificates
• Configure Support for a Custom Domain

Best Practices

Here are some best practices to follow while setting up VB Studio to develop visual applications.

• Ensure that you and your organization's users are assigned the correct VB Studio identity domain roles. See Get the Required IDCS Roles.
• Before you create a VB Studio project, make sure that your Visual Builder development and production instances are up and running.
• After creating the project, add VB Studio users to the project and assign them proper project roles.

  For example:

  • Assign the Developer role to trusted users who can access code files, build, and deploy the application.
  • Assign the Developer Limited role to users who can access the code files, can run build jobs (but can't create, configure, or delete them), and deploy applications.

    If you want to assign the Developer limited role but restrict access to specific build jobs, you should look into using protected jobs, which is explained in Configure a Job's Privacy Setting.

  • Assign the Contributor role to users who can access the project, but not update the code files.
• If you use the Visual Application template to create your project, VB Studio automatically creates a Development environment that points to the Visual Builder instance you specify. The build jobs, created by default, package the application's artifacts and deploy them to the Visual Builder development instance.

  If you want to use VB Studio to also deploy to your Visual Builder production instance, you'll need to manually create a VB Studio environment for the instance.

• To add a Visual Builder production instance from another identity domain, you'll need to get either the identity domain's details or a user's credentials who can connect to the instance.
• Follow your organization's guidelines to create and manage Git repository's branches. By default, the project uses the main branch for development. This documentation assumes that you'll continue to use main as the development branch and create a separate branch for production.
• You should set restrictions on the production branch to control who can merge to it. You should also set restrictions on who can edit or run the production jobs.
• To deploy to your Visual Builder production instance, create separate jobs to package the artifact and to deploy the artifact to the Visual Builder instance. Then, create a pipeline to run the packaging and deployment jobs in sequence.
• When you configure a deployment job, you'll specify the application's version and whether you want to include the version in the deployed application's URL. It's considered best practice to include the version number in jobs that deploy to development and other non-production instances, but not for jobs that deploy to the production instance.
• Set restrictions on who can edit or run production jobs.
• Before you run production build jobs or pipeline, make sure that all code changes have been pushed to the production branch and there are no open merge requests.

Get the Required IDCS Roles

Make sure that your users have the correct roles to access VB Studio, depending on whether your VB Studio instance is in Oracle Cloud Applications or on an OCI tenancy.

Oracle Cloud Applications

To set up VB Studio and your Oracle Cloud Applications instances, make sure you're assigned the FND_ADMINISTER_SANDBOX_PRIV privilege or any of these roles in your development and production instances:

• APPLICATION ADMINISTRATOR
• APPLICATION DEVELOPER
• SALES_ADMINISTRATOR
• CUSTOMER RELATIONSHIP MANAGEMENT APPLICATION ADMINISTRATOR

OCI

This table lists the identity domain roles you'll need to set up VB Studio on an OCI tenancy:

You must be assigned this role:	To ...
Identity Domain Administrator or User Administrator	Add users and assign IDCS roles.
DCS_INSTANCE_ENTITLEMENT_ADMINISTRATOR	Create the VB Studio instance.
DEVELOPER_ADMINISTRATOR	Set up VB Studio. After you're assigned the role, you're considered VB Studio's Organization Administrator.
OCI_Administrator (OCI Administrator)	Set up OCI compartments and buckets, which are required to set up the VB Studio build system.

Access Your VB Studio Instance

Get access to the VB Studio instance where you will create the project for your visual application.

Note:

If you are an OCI customer and you don't already have a VB Studio instance, you'll need to create an instance in the same Oracle Cloud account and identity domain as the Visual Builder development instance. See Create the VB Studio Instance.

Follow the instructions in the row that corresponds to the type of VB Studio instance that you have.

Type of VB Studio Instance	How to
Oracle Cloud Infrastructure (OCI)	In a web browser, go to https://cloud.oracle.com. On the Sign-In page, in Cloud Account Name, enter your Oracle Cloud account or tenancy name and click Next. On the Single Sign-On (SSO) panel, click Continue. Enter your Oracle Cloud account credentials and click Sign In. The Oracle Cloud Console, also called the OCI console, opens. In the upper-left corner, click Navigation Menu . Select OCI Classic Services and then select Developer. If you don't see the Developer option, make sure you're assigned the required IDCS roles. In the Instances tab, click Manage this instance and select Access service instance. Add users to IDCS. See Add Users to IDCS. The VB Studio Organization page opens, which displays all the projects you're a member of, as well as your favorite projects, the projects you own, and all the shared projects in your organization. You can also set up OCI connections, virtual machines, and the properties of the organization.
Oracle Cloud Application	In your Oracle Cloud Applications TEST instance, click Navigator . In the navigation menu, under Configuration, select Visual Builder. Description of the illustration oracle_apps_navigator_vbstudio.png The VB Studio Organization page opens, which displays all the projects you're a member of, as well as your favorite projects, the projects you own, and all the shared projects in your organization.

Configure VB Studio to Run Build Jobs and Pipelines

In a VB Studio visual application project, you use build jobs to compile the source code, package the visual application, and deploy it to a Visual Builder instance. The builds and pipelines run on build executors, also called VM build executors. These VM executors are Oracle Cloud Infrastructure (OCI) VM compute instances dedicated to run VB Studio builds.

In some Oracle Cloud regions and data centers, VB Studio is available pre-configured with a built-in free account, which provides one free VM executor that you can use to run build jobs that package and deploy your extensions. However, there some limitations (see VB Studio's Free VM Build Executor) associated with the free VM build executor, so you may want to connect to your own OCI account instead, if you have one. See OCI Resources in VB Studio for more a more comprehensive comparison between the built-in free account, free tier account, and your OCI account.

To find out whether your VB Studio instance is connected to the built-in free account, follow these steps:

1. In the navigation menu, click Organization .
2. Click the OCI Account tab.

   You should see a similar page:

   
   Description of the illustration vbs_built-in_free_account.png

Depending on your VB Studio's data center, you may or may not see the Built-in (Free) option.

What do you see?	What you need to do:
I see the Built-in (Free) option	If you're trying out extensions, no additional configuration is required. Go ahead and create your extension project. VB Studio creates the free VM build executor when you create your first project.
I see the Built-in (Free) option, but want to run builds without any limitations	Configure VB Studio to connect to your OCI account and add VM executors. If you're new to OCI, see Welcome to Oracle Cloud Infrastructure.
I don't see the Built-in (Free) option, but have access to an OCI account	The built-in free account isn't available in your data center. You should configure VB Studio to connect to your OCI account and add VM executors.
I don't see the Built-in (Free) option and don't have access to an OCI account either	You can still use VB Studio to create the extension project. To run builds, create an OCI account or the Oracle Cloud Free Tier account. The free tier account offers free micro Compute VMs that your organization's members can use to run builds. After creating the free tier account, create OCI resources as described in Set Up the OCI Account and get their details as described in Get the Required OCI Input Values. Then, set up the OCI connection in VB Studio. If you can't create an OCI account or the free tier account, wait for the built-in free account to be available in your data center.

Before you create a project, note that in a VB Studio instance that has no projects and no VM executors, the firstVM executor is created for you when you create the first project. If the project isn’t the initial one, the VM executor must be created manually.

Add the Free VM Build Executor Manually

If you're using VB Studio's built-in free account, the free VM build executor is added when you create your first project. Add the VM executor manually if you've deleted it or it wasn't added when you created the project.

1. In the navigation menu, click Organization .
2. Click the VM Build Executors tab.
   If you see a VM executor of the System Default OL7 for Visual Builder template, the free VM build executor is available in your VB Studio instance. Ignore the remaining steps.

   
   Description of the illustration vbs-builtin-freevm.png

   If you don't see the VM executor, jump to the next step.

3. Click Create Free VM Build Executor.
   
   Description of the illustration vbs_freevm.png

Create and Set up a Project

A project gathers all the resources you need for developing software. After a project is created, it needs to be set up to enable your developers to create the visual application.

The procedures that you use to create and set up the project depend on whether your Visual Builder instance is in the same identity domain as your VB Studio instance or in a different domain.

Type of VB Studio Instance	Links to Procedures
Visual Builder instance is in a different identity domain than the VB Studio instance.	Create and Set Up a Project for Development (Different Identity Domain)
Visual Builder instance is in the same identity domain as the VB Studio instance.	Create and Set Up the Project for Development (Same Identity Domain)

Create and Set Up a Project for Development (Different Identity Domain)

If want to develop visual application using VB Studio instance that's in a different identity domain than your Visual Builder instance (for example, VB Studio instance provisioned in your Oracle Cloud Application account), you'll need to add a Visual Builder instance to your VB Studio project. You first need to create an empty project, and then manually create a new environment with the Visual Builder instance where you plan to deploy the visual applications.

Note:

To create a project using a VB Studio instance created in the same identity domain as your VB Studio instance, follow the instructions in Create and Set Up the Project for Development (Same Identity Domain).

1. After you've set up VB Studio to develop visual applications, follow the steps in the this table to set up the project, configure the deployment job, and add users to the project:

   Action	How to
   1. Create an empty VB Studio project.	Sign in to VB Studio. See Access VB Studio from the Oracle Cloud Home Page. On the Organization page, click + Create. On the Project Details page, enter a unique name and description for the project. In Security, select the project's privacy setting. A private project is accessible to invited users only. Users who aren't invited can't access it or make changes to it. You can invite users after creating the project. A shared project is accessible to all users of the organization. Any user can view the source code, create or update issues, edit wiki pages, and interact with project builds. However, only invited users can make updates to the source code in Git repositories, create and run build jobs, and perform deployment operations. In Preferred Language, specify the language for the email notifications your project users will receive. You can change the language in which the user interface appears in your user preferences. Click Next. On the Template page, select the Empty Project template, then click Next. On the Properties page, select the wiki markup type, then click Finish. After the project is provisioned, the Project Home page opens where you can see a summary of the project's provisioning activities; default environment; default workspace; and Git, Maven, and NPM repositories. Review the activities feed and the Environments box for any errors.
   2. In the project, create an environment with your Visual Builder instance.	In the navigation menu, click Environments , and then click + Create Environment. In Environment Name and Description, enter a unique name and description, and click Create. In the Service Instances tab, click Add Instance. For Instance Type, select the Visual Builder, and for Authentication Method, select Visual Builder Credentials. In Base URL, enter the Visual Builder instance's URL. The Instance Name is automatically filled, but you can update that if you with. The Instance Name will be displayed in the Service Instances tab. In Username and Password, enter the credentials of a user who can access the Visual Builder instance. Click Add.
   3. When users are ready, they can create this workspace in the project.	In the navigation menu, click Workspaces . Click New and select New Visual Application. In Workspace Name, add a name for your workspace. In Development Environment, select the environment you created in the previous step. In Visual Application Template, don't change the default (Default VBCS Application). In Git Repository, select Create new repository, and enter a repository name and working branch name.
   4. The user that created the visual application will need to configure their deployment job.	In your Visual Builder Studio navigation menu, click Builds . Click Configure, then click Configure. Click the Steps tab. In Target Instance, make sure that the environment you created in Step 2 is selected. In Username and Password, enter yours or a user's credentials who can connect and deploy to the Visual Builder development instance. The credentials will be used when the package and deploy build pipeline runs. (Optional) Choose Use custom file names and add custom file name details. (Optional) To overwrite the application's default version, specify the new version in Application Version. Leave it empty to use the version defined in the application's visual-application.json file. Don't deselect the Include the application version in the URL check box. (Optional) In Application Profile, specify the development application profile. Leave it empty to use the application's default profile. Using application profiles, you can define different combinations of servers and security settings for each of your environments, and use them when deploying the application to an environment. To learn more, see What Are Application Profiles? (Optional) To use the existing application's database, in Data Management, select Keep existing environment data. To use a clean database for the application, in Data Management, select Use clean database. Click Save.
   5. Add users to the project.	To allow your team members to access the visual application project, invite them to join the project. See Add Users to the Project.

Create and Set Up the Project for Development (Same Identity Domain)

If want to develop visual application using VB Studio instance that's in the same identity domain than your Visual Builder instance, you'll first need to first create a project based on the Visual Application template, and then make a few configuration settings in the project so that it's ready for developing visual applications.

Note:

To create a project using a Visual Builder instance that was provisioned in a different identity domain than your VB Studio instance, follow the instructions in Create and Set Up a Project for Development (Different Identity Domain).

Here's a summary of how to create and set up a VB Studio project for development.

To perform this action:	See this:
1. Create a project.	Create a Project
2. Configure the deployment job. By default, the deployment job doesn't have credentials to connect to the target development instance, so you must specify them manually.	Configure the Deployment Job
3. To verify your credentials, run the development pipeline	Run the Pipeline Manually
4. View the deployed visual applications	View the Deployed Visual Application
5. Add other members of your team to the project	Add Users to the Project

Create a Project

If are developing visual application using VB Studio instance that's in the same identity domain than your Visual Builder instance, you'll need to base your project on the Visual Application project template.

Note:

To create a project using a Visual Builder instance that was provisioned in a different identity domain than your VB Studio instance, follow the instructions in Create and Set Up a Project for Development (Different Identity Domain).

1. Sign in to VB Studio. See Access VB Studio from the Oracle Cloud Home Page.
2. On the Organization page, click + Create.
3. On the Project Details page of the New Project wizard, enter a unique name and description for the project.
4. In Security, select the project's privacy setting.
   A private project is accessible to invited users only. Users who aren't invited can't access it or make changes to it. You can invite users after creating the project.

   A shared project is accessible to all users of the organization. Any user can view the source code, create or update issues, edit wiki pages, and interact with project builds. However, only invited users can make updates to the source code in Git repositories, create and run build jobs, and perform deployment operations.

5. In Preferred Language, specify the language for the email notifications your project users will receive.
   You can change the language in which the user interface appears in your user preferences.
6. Click Next.
7. On the Template page, select the Visual Application project template, and then click Next.
   If you don’t see the Visual Application template, that means you’re in an OCI region that doesn’t yet support it. Use the steps in this workaround to create your project instead of the steps shown here.
8. On the Project Properties page:
   1. In Git Repository Name, change the Git repository's default name, if required.
   2. In Development VB Instance, if not already selected, select the Visual Builder development instance.
      If there is only one Visual Builder instance in your VB Studio's identity domain, VB Studio selects it as the development instance. If there are more than one Visual Builder instances in your identity domain, the drop-down lists all the Visual Builder instances.

      If you're assigned the PaaSAdministrator IDCS role, you'll see both current identity domain's service instances and PSM Visual Builder instances in this list. If you see both, select a PSM Visual Builder instance as it provides options to control the instance.

   3. In Visual Application Template, select a visual application template available on the selected development instance.
      By default, VB Studio uses the Default VBCS Application template. To select another template, click Change Template, select the template and click Use Selected.
   4. (Optional) In Workspace Name, if required, change your private workspace's name. By default, it is Workspace1.

      A workspace contains all the artifacts that you need to develop visual applications, including a clone of this project's Git repository–and the branch–containing the source files. To learn more about workspaces, see What Is a Workspace and Why Do I Need One?

   5. (Optional) In Working Branch Name, if required, change the workspace's working branch name. By default, it is branch1.
      When the project is provisioned, the Git repository's main branch contains your application's files. While creating the workspace, VB Studio creates a copy of the main branch, renames it with your specified name and uses it as the workspace's working branch.
9. Click Finish.

After the project is provisioned, the Project Home page opens where you can see a summary of the project's provisioning activities; default environment; default workspace; and Git, Maven, and NPM repositories. Review the activities feed and the Environments box for any errors.

When you create a project using the Visual Application template, these artifacts are created for you:

• A Git repository, which contains the visual application's source code.

  To see the Git repository's files, go to the Project Home page, click the Repositories tab, then click the Git repository name:

  
  Description of the illustration default_visualapp_repository.png
• A Development environment pointing to the Visual Builder development instance.

  In the navigation menu, click Environments to see the Development environment:

  
  Description of the illustration default_visualapp_environment.png
• Build jobs that package and deploy the visual application's artifact to the Visual Builder development instance.

  By default, Visual-Application-Package and Visual-Application-Deploy jobs are created for you. The Visual-Application-Package job generates the visual application's artifact file. The Visual-Application-Deploy job deploys the visual application's artifact file to the Visual Builder development instance.

  In the navigation menu, click Builds and then click the Jobs tab to see the build jobs:

  
  Description of the illustration default_visualapp_buildjobs.png

  To run builds of the package and deploy jobs, you must first allocate VM build executors and make the appropriate deployment configurations. Without the appropriate configuration or VM executors, the builds won't run.

• A pipeline to run the build jobs in a sequence.

  In the navigation menu, click Builds and then click the Pipelines tab to see the pipeline:

  
  Description of the illustration default_visualapp_pipeline.png
• A private workspace to edit the visual application in the VB Studio Designer.

  In the navigation menu, click Workspaces to see the workspace:

  
  Description of the illustration default_visualapp_workspace.png
• By default, the project uses the organization's default markup language. Your project's users use the markup language to format wiki pages and comments. If required, you can change the project's markup language from the Project Administration page. See Change a Project’s Wiki Markup Language.
• A VM executor is created if this project is VB Studio's first project and no build VM executors had existed when you created the project. The VM executor uses the System Default OL7 for Visual Builder build executor template. You can use this VM executor to run build jobs that reference the System Default OL7 for Visual Builder template in the current project and other projects as well.

  In the navigation menu, click Organization and then click the VM Build Executors tab to see the VM executor.

  
  Description of the illustration vbs-builtin-freevm.png

Configure the Deployment Job

The deployment job deploys the visual application's build artifact to your Visual Builder development instance. In the job, specify the application's version and profile, and the credentials required to connect and deploy build artifact to your Visual Builder development instance.

1. In the navigation menu, click Builds .
2. In the Jobs tab, click the deployment job.
3. Click Configure.
4. Click Configure .
5. Click the Steps tab.
6. In Username and Password, enter yours or a user's credentials who can connect and deploy to the Visual Builder development instance.
   The credentials will be used when the package and deploy build pipeline runs.
7. (Optional) To overwrite the application's default version, specify the new version in Application Version. Leave it empty to use the version defined in the application's visual-application.json file.
   Don't deselect the Include the application version in the URL check box.
8. (Optional) In Application Profile, specify the development application profile. Leave it empty to use the application's default profile.

   Your visual application accesses data from different servers for REST services and may need different security settings for different environments, such as development and production. Using application profiles, you can define different combinations of servers and security settings for each of your environments, and use them when deploying the application to an environment. This simplifies management of the visual application as you move through development to production. To learn more, see About Application Profiles.

9. (Optional) To use the existing application's database, in Data Management, select Keep existing environment data. To use a clean database for the application, in Data Management, select Use clean database.
10. Click Save.

Run the Pipeline Manually

The development build pipeline runs automatically when a commit is pushed to the Git repository's branch specified in the packaging job.

If you want to run the pipeline manually:

1. In the navigation menu, click Builds .
2. Click the Pipelines tab.
3. In development pipeline's row, click Build .

To monitor the pipeline and see each job's status, click the pipeline's name. To see a job's build log, click the job's name and click Build Log .

If you want to run a job's build manually, open the job's details page and click Build Now. You can monitor its build on the job's details page.

View the Deployed Visual Application

After the deployment job has successfully run, you can view the deployed applications in the Deployments tab of the Environments page.

1. In the navigation menu, click Environments .
2. Select the Visual Builder environment.
3. Click the Deployments tab.
4. If not enabled, click the Visual Applications toggle button.
5. If the Visual Builder instance is from a different identity domain, provide its access credentials.
6. Expand the app's name to see the deployed app's link.

   The Deployments tab displays the applications you've deployed from the current project. It doesn't show applications deployed by other users of the project, or applications deployed from other projects.

   Example:

   
   Description of the illustration visualapp_deployment.png

Add Users to the Project

You must explicitly add users before they can work within a project, as explained in this table:

If you want to:	Do this:
Add a user to the project	In the navigation menu, click Project Home . Click the Team tab. Click + Create Member. Click the Username drop-down list. Under Users, select the user. If you can't find a particular user, enter the user's name or username in the search box. As you begin typing, users matching the search term are displayed. From the membership option types, select the user's membership. Click Add.
Add a group to a project	In the navigation menu, click Project Home . Click the Team tab. Click + Create Member. Click the Username drop-down list. Under Groups, select the group. From the membership option types, select the membership you want to assign to the group's members. Click Add.
Add multiple users or groups to the project	In the navigation menu, click Project Home . Click the Team tab. Click + Create Member. Click the Username drop-down list. From the drop-down list, select a user or a group. Click Username again to select another user or group. If you can't find a particular user, enter the user's name or username in the search box. As you begin typing, users matching the search term are displayed. From the membership option types, select the user's membership. Click Add.
Change a user’s or a group's project membership	To change a user’s or a group's project membership, click the Change Membership icon . From the dropdown, select a new project membership (Contributor, Developer, Developer Limited, or Project Owner).
Remove a user or a group from the project	Before removing a user, change the ownership of any assigned issues and merge requests to another user. For the user or the group you to remove, click Remove .

Optional Configuration

After setting up the project, you can follow these optional steps to configure some advanced settings in your project. You can perform these steps at any time during your development cycle.

To perform this action:	See this:
Add more VM executors or executor templates. By default, VB Studio is connected to its built-in free account and uses one free VM build executor with fixed software packages in the executor template. If you want to add more VM executors or customize executor template's software packages, configure VB Studio to connect to your OCI account.	Add More VM Build Executors or Build Executor Templates
Configure the packaging job to change the visual application's archive file names. By default, the packaging job generates two archive files: sources.zip and built-assets.zip. If you want to specify custom file names, configure the packaging job.	Specify a Different Version for the Extension
Protect the Git repository's main branch for unapproved code updates. By default, a branch is accessible to all project users and anyone can make changes to its files. To restrict changes and push commits to the main branch, set restrictions on it to allow branch merges only after they are approved.	Set Merge Restrictions on the main Branch

Add More VM Build Executors or Build Executor Templates

If you want to add more VMs to reduce the wait time for your organization's members or create custom VM templates, or use advanced features for VMs (such as use your own VCN or use a different VM shape), you should configure VB Studio to connect to your own OCI account.

1. Set up your OCI account and get the required input values.

   See Set Up the OCI Account and Get the Required OCI Input Values.

2. In the navigation menu, click Organization .
3. Click Connect OCI Account.
4. Enter the required details and click Validate.
5. After successful validation, click Save.

The executor template and the free VM build executor of your built-in free account migrate to the OCI account.

To create custom executor templates, see Create and Manage Build Executor Templates. Remember to add Node.js 14 (or a higher version) to the VM template. Node.js 14 is the minimum version required for packaging visual applications.

To add more VM executors:

1. Click the VM Build Executors tab.
2. Click + Create VM.
3. In the Add VM Build Executor dialog box, in Quantity, specify the number of VM executors you want to allocate.

   To minimize build execution delays, set the number of VM executors to the number of jobs that you expect to run in parallel using that template. If the OCI Compute VM quota is available, that number ofVM executors will be added to the Virtual Machines tab.

   If you're not sure about the number of VM executors you'll need, start with one VM executor and then add more as required. Note that the more VM executors you have running at a specific time, the higher the cost of OCPUs. To minimize the higher cost, use the Sleep Timeout setting on the VM Build Executors page to automatically shut down inactive VM executors. You can always return to the VM Build Executors tab to remove or add VM executors, based on your actual usage.

4. In Build Executor Template, select System Default OL7 for Visual Builder or a executor template with Node.js 14 (or higher) software.
5. In Region, Shape, and VCN Selection specify the OCI VM's region, shape, and Virtual Cloud Network (VCN).
   • A region is a localized geographic area where the data centers are located. Remember, a VM executor is a VM on OCI Compute. Choose the region where your VB Studio account is or the one that's closest to you geographically.
   • A shape is a template that determines the number of CPUs, amount of memory, and other resources allocated to the created instance. Choose a shape of your preference.
   • A VCN is a software-defined network that you set up in the Oracle Cloud Infrastructure data centers in a particular region. By default, builds run in your VB Studio's compartment. To run builds in your own VCN, select Custom and specify its details.

   To learn more about regions and shapes, see Regions and Availability Domains and VM Shapes. To find more about VCNs, see VCNs and Subnets.

6. Click Add.

Configure the Packaging Job

From the source files in the Git repository's main branch, the packaging job generates two archive files: a source archive file that contains the visual application's source files and a build artifact archive file.

If you don't want to change the visual application's default archive file names, no need to configure the packaging job. If you want to specify custom names, follow these steps:

1. In the navigation menu, click Builds .
2. In the Jobs tab, click the packaging job.
3. Click Configure.
4. Click Configure .
5. Click the Steps tab and navigate to the Visual Application Packaging section.
6. By default, the build jobs minifies the application's source code before running the build. If you don't want to minify the source files, deselect the Optimize application check box.
   Minification is a process to remove the unnecessary characters (such as blank spaces, new lines, and comments) from the source code and reduce the size of the files, making the transfer of files consume less bandwidth and storage.
7. If you want to change the default names of the archive files, in File names, select Use custom file names.
   In Sources, specify the visual application source archive file's name and path. In Build Artifact, specify the build artifact archive file's name and path.

   You'll need both archive files to deploy the visual application.

8. Click Save.

If you change the default file names of archive files, then remember to configure the deployment job to use the same file names.

1. In the Jobs tab, click the deployment job.
2. Click Configure.
3. Click Configure .
4. Click the Steps tab and navigate to the Oracle Deployment section.
5. In File names, select Use custom file names.
6. In Sources and Build Artifact, enter the same file names (with path) you specified in the packaging job.
7. Click Save.

Set Merge Restrictions on the main Branch

By default, the main branch is accessible to all project users and anyone can make changes to its files. To restrict changes and who can push commits to it, you may want to set restrictions on it to allow branch merges only after they are approved.

1. In the navigation menu, click Project Administration .
2. Click Branches.
3. In Repository and Branches, select the Git repository and the main branch.
4. Select the Requires Review option.
5. In Default Reviewers, enter and select the users.
   A default reviewer is a project member who is automatically added as a reviewer when a merge request is created on the branch.
6. From the Approvals drop-down list, select the minimum number of reviewers who must approve the review branch of a merge request, where the selected branch is the target branch
7. (Optional) To allow a review branch to be merged to the selected branch only if the last build of the linked job in Merge Request is successful, select the Require successful build check box.
   To use this option, link a build job to a merge request.
8. (Optional) If you want to reset the approval status of reviewers if change is pushed to a branch after they have approved the merge request, select the Reapproval needed when branch is updated check box.
9. (Optional) To ensure changes pushed to the target branch match the contents of the review branch, select the Changes pushed to target branch must match review content check box.
10. (Optional) In Merge Request Exempt Users, specify users who can bypass the branch restrictions and merge the review branch of a merge request outside VB Studio or without required approvals.
    This is useful if you want to allow some users to merge the review branch irrespective of review conditions being met.
11. Click Save.

What Next?

Now that you've set up VB Studio and created a visual application project and added users to it, guide your organization members who develop visual applications to these documents to learn more about VB Studio.

• Build Web and Mobile Applications with VB Studio in Building Web and Mobile Applications with Visual Builder Studio describes how to create, edit and publish visual applications.

• Get Started in Using Visual Builder Studio is a good resource, as it explains how to manage a project, create and manage issues and Agile boards, review source code with merge requests, and more.

Set Up the Project to Deploy for Production

After your development and test cycles are complete, you may want to configure the project to build and deploy visual applications to the Visual Builder production instance.

Before you proceed, contact the Visual Builder administrator and make sure that the Visual Builder production instance is properly configured and running. For example, make sure that the production instance's security options are configured and the instance points to the correct database.

Here's a summary of how to set up the VB Studio project for deployment:

To perform this action:	See this:
1. In the VB Studio project, create an environment for the Visual Builder production instance.	Add the Visual Builder Production Instance to an Environment
2. Create a production branch from the main branch. Use this branch to push your application to production.	Create a Production Branch
3. Create the production packaging and deployment build jobs, and set up the pipeline.	Create and Configure Production Build Jobs
4. (Optional) Restrict users who can edit the production jobs or run their builds.	Configure a Job's Privacy Setting

Before you run production jobs, make sure that all code changes have been pushed to the production branch and there are no open merge requests.

Add the Visual Builder Production Instance to an Environment

To deploy a visual application to the Visual Builder production instance, you must create a separate VB Studio environment and add the production instance to it. You can add only one Visual Builder instance to an environment.

The Visual Builder production instance usually resides in another identity domain. To add the production instance to an environment, you'll need any of these details:

• Production instance's identity domain ID, region, and a user's credentials who can access the instance
• Visual Builder production instance's base URL and a user's credentials who can access the instance

After adding a Visual Builder instance to an environment, in the Service Instances tab, click Expand to see its release version and home page URL.

When you add a Visual Builder instance (a service instance or an IDCS resource) to an environment, VB Studio creates an IDCS Application (also known as a Client Application) in the background. The IDCS Application generates an OAuth token to access the newly added Visual Builder instance and handles authentication when VB Studio tries to access the target instance. Provisioning of the IDCS Application takes a few seconds to complete after VB Studio adds the Visual Builder instance to an environment.

If the newly added instance stays in the Unknown status for some time, it usually indicates that the IDCS Application provisioning may have failed. VB Studio added the Visual Builder instance but can't access it. In such a case, click Actions and select Remove to delete the Visual Builder instance from the environment, and then click Add to add it again.

Add a Connection to Visual Builder of Another Identity Domain

1. In the navigation menu, click Environments .
2. Click + Create Environment.
   In Environment Name and Description, enter a unique name and description, and click Create.
   If you want to add the production instance to an existing environment, select it.
3. In the Service Instances tab, click Add Instance.
4. In the Add Service Instances dialog box, select the Visual Builder option button.

If you have these details of the Visual Builder instance:	Follow these steps:
Identity domain ID, region, username, and password	Select the Identity Domain option. Click Edit next to the current identity domain's details. In Identity Service Id/Identity Domain, enter the Visual Builder instance's identity domain name or its ID. The ID is usually in the idcs-<hexadecimalID> format. You can find the identity domain name and the Identity Service ID in the About dialog box of IDCS Dashboard. In Region, select the identity domain's region. In Username and Password, enter the credentials of a user who can access the Visual Builder instance. Click Update. Select the check box for the Visual Builder instance you want to add and click Add.
Visual Builder instance's base URL and credentials of a user who can access the instance	Select the Visual Builder Credentials option. To add a standalone Visual Builder instance, select the Visual Builder option. To add an Oracle Integration's Visual Builder instance, select the Oracle Integration option. In Base URL, enter the base Visual Builder instance's URL. In Instance Name, if required, update the instance's display name. The name will be displayed in the Service Instances tab. In Username and Password, enter the credentials of a user who can access the Visual Builder instance. Click Add.

Create a Production Branch

Follow your organization's guidelines to create a branch and protect it from unverified changes. To protect the branch, you can set merge restrictions, make the branch private and restrict who can push commits to it, or freeze it.

1. In the navigation menu, click Git .
2. Click the Refs view and then click Branches .
3. From the Repositories drop-down list, select the repository.
4. Click + Create Branch.
5. In the New Branch dialog box, in Name, enter the branch name. From the Base drop-down list, select the main branch as the base branch.
6. Click Create.

After creating the production branch, if you want to set merge restrictions on it, see Set Review and Merge Restrictions on a Repository Branch. To freeze the branch or make it private, or set other restrictions, see Protect a Branch.

Create and Configure Production Build Jobs

You need to set up some packaging and deployment jobs before you can deploy visual applications to your Visual Builder production instance. This topic explains how to do that.

Before you configure production build jobs, make a note of these:

• In the production packaging job, use the Git repository's production branch to generate production artifacts.
• In the development packaging job, if you changed the default file names of archive artifact files, get the new names and their paths. You'll need them when you configure the production packaging job.
• If you configured the development packaging job to overwrite the application's version defined in visual-application.json, get the new version. You'll need it when you configure the production packaging job.
• While configuring deployment build jobs, you specify whether to include the application's version in its URL. A visual application without the version in its URL is called a Live application. Usually, you deploy a live application to a production instance.
• If you deploy a version of a visual application that's never been deployed, VB Studio overwrites the last deployed version with the new version.

  VB Studio doesn't undeploy the previously deployed version from the production instance. It continues to remain on the target instance, but is inaccessible.

• If you want to redeploy a live application or a previously deployed version, undeploy it first, else the deploy build fails. To undeploy a previously deployed visual application version, configure a undeploy build job and run it. You can't undeploy it manually from the Environments page.
• If you've created an application profile for production, get its name. You'll need it when you configure the production deployment job.

Create a Production Packaging Build Job

The production packaging job generates a visual application artifact that's ready to deploy.

1. In the navigation menu, click Builds .
2. In the Jobs tab, click + Create Job.
3. In the New Job dialog box, in Name, enter a unique name.
4. In Description, enter the job's description.
5. In Template, select the System Default OL7 for Visual Builder template.
6. Click Create.
7. Click Configure .
8. Click the Git tab.
9. From the Add Git list, select Git.
10. In Repository, select the Git repository. In Branch or Tag, select the production branch.
11. Click the Steps tab.
12. From Add Step, select Visual Application, and then select Package.
13. By default, the build jobs minifies the application's source code before running the build. If you don't want to minify the source files, deselect the Optimize application check box.
    Minification is a process to remove the unnecessary characters (such as blank spaces, new lines, and comments) from the source code and reduce the size of the files, making the transfer of files consume less bandwidth and storage.
14. If you want to change the default names of the archive files, in File names, select Use custom file names.
    In Sources, specify the visual application source archive file's name and path. In Build Artifact, specify the build artifact archive file's name and path.

    You'll need both archive files to deploy the visual application.

15. Click the After Build tab.
16. From Add After Build Action, select Artifact Archiver.
17. In Files to archive, enter the build artifact name. You can also use wild characters. For example, *.zip.
18. If you want to discard old artifacts of the build, click Settings . In the General tab, select the Discard Old Builds check box and specify the discard options.
19. Click Save.

Create a Production Deployment Build Job

The production deployment job deploys the visual application's artifact that was generated in the production packaging job to the Visual Builder production instance. Before you create the job, get the access credentials of a user who can connect and deploy to the Visual Builder production instance.

1. In the navigation menu, click Builds .
2. In the Jobs tab, click + Create Job.
3. In the New Job dialog box, in Name, enter a unique name.
4. In Description, enter the job's description.
5. In Template, select the System Default OL7 for Visual Builder template.
6. Click Create.
7. Click Configure .
8. Click the Before Build tab.
9. From Add Before Build Action, select Copy Artifacts.
10. In From Job, select the production packaging job that generated the visual application's artifact.
11. In Which Build, select Last Successful Build.
12. Leave other fields with their default or empty values.
13. Click the Steps tab.
14. From Add Step, select Oracle Deployment.
15. In Target Instance, select the Visual Builder production instance.
16. In Username and Password, enter the user's credentials who can connect and deploy to the Visual Builder production instance.
17. In the production packaging job, if you changed the default file names of archive artifact files, then in File names, select Use custom file names.
    In Sources and Build Artifact, enter the same file names (with path) you specified in the packaging job.

    If you didn't change the file names, use the default option.

18. (Optional) If you configured the development deployment job to overwrite the application's default version, specify the same version in Application Version. Leave it empty to use the version defined in the application's visual-application.json file.
    If the version is already deployed, undeploy it first.
19. Deselect the Include the application version in the URL check box.
    When deploying to a production instance, don't include the application's version in the deployed application's URL.
20. (Optional) In Application Profile, specify the production application profile. Leave it empty to use the application's default profile.

    Your visual application accesses data from different servers for REST services and may need different security settings for different environments, such as development and production. Using application profiles, you can define different combinations of servers and security settings for each of your environments, and use them when deploying the application to an environment. This simplifies management of the visual application as you move through development to production. To learn more, see About Application Profiles.

21. To use a clean database for the application, in Data Management, select Use clean database.
22. Click Save.

Configure a Production Job's Privacy Setting

Mark a job as private to restrict who can see or edit a job's configuration, or run its build.

A private job must be run manually. It won't run if a non-authorized user tries to run the job directly, through an SCM/periodic trigger or a pipeline.

1. In the navigation menu, click Project Administration .
2. Click Builds.
3. Click the Job Protection tab.
4. From the jobs list, select a production job.
5. Select the Private option.
6. In Authorized Users, add yourself.
   Then, to add other users, select them individually or, under Groups, select a group (or groups) of users.
7. Repeat the steps 4-6 for the deployment production job.
8. Click Save.

A private job shows a Lock icon in the jobs list on the right side of the Job Protection page, in the Jobs tab of the Builds page, and in the pipelines.

Create and Configure a Pipeline

To ensure the production deployment job runs automatically after the production packaging job, create a pipeline and set the dependency.

1. In the navigation menu, click Builds .
2. Click the Pipelines tab.
3. Click + Create Pipeline.
4. In the Create Pipeline dialog box, in Name and Description, enter a unique name and description.
5. Click Create.
6. On the design page, from the Jobs list, drag-and-drop the packaging job and the deployment job to the designer area.

   Example:

   
7. Mouse over the Start node's Gray circle . The cursor icon changes to the + cursor icon. Drag the cursor from the Gray circle handle to the packaging job's White circle handle. An arrow line appears.

   Example:

   
8. Mouse-over the packaging job's Blue circle handle and drag-and-drop the arrow head over the deployment job's White circle .

   Example:

   
9. Click Save.

Run the Pipeline

When you're ready to deploy the visual application to the production instance, run the production pipeline.

1. In the navigation menu, click Builds .
2. Click the Pipelines tab.
3. For the production pipeline, click Build .

After a successful build, you'll find the deployed application's link in the Deployments tab of the Environments page.

To view the latest build log of a job, open the Builds page, click the job's name, and then click Build Log .

Undeploy a Visual Application

If you want to undeploy a visual application that's deployed to Visual Builder, you can do so manually or through a job configuration.

You can undeploy a visual application manually if it is deployed to a Visual Builder instance that's in the same identity domain as VB Studio. If the visual application is deployed to a Visual Builder instance in a different identity domain than VB Studio (such as your production instance) or the Visual Builder instance was added to an environment through credentials, you should configure a build job to undeploy it.

Undeploy a Visual Application Manually

You can undeploy a visual application that's deployed to your current identity domain's Visual Builder manually from the Deployments tab of its environment.

Note:

If your visual application is deployed to an identity domain that's different than your VB Studio instance, you'll need to follow the instructions in Configure a Build Job to Undeploy a Visual Application to undeploy the application.

1. In the navigation menu, click Environments .
2. Select the environment where the visual application is deployed.
3. Click the Deployments tab.
4. Expand the application.
5. For the visual application to undeploy, click Actions and select Undeploy.
6. If the visual application is a live application (without the version number in the URL), select the Yes, I'm sure check box.
7. Click Undeploy.

Configure a Build Job to Undeploy a Visual Application

To undeploy a visual application deployed to the production instance, or another identity domain's Visual Builder instance, configure a build job. Before you configure the job, get the access credentials of a user who can access the Visual Builder instance where the visual application is deployed.

1. In the navigation menu, click Builds .
2. In the Jobs tab, click + Create Job.
3. In the New Job dialog box, in Name, enter a unique name.
4. In Description, enter the job's description.
5. In Template, select the System Default OL7 for Visual Builder template.
6. Click Create.
7. Click Configure .
8. Click the Steps tab.
9. From Add Step, select Visual Application, and then select Undeploy.
10. In Instance, select the Visual Builder instance where the application is deployed.
11. In Username and Password, enter the user's credentials who can connect and undeploy to the Visual Builder instance.
12. In Application URL Root and Application Version, enter the visual application's root URL and its version.
    You can find the application's root URL and its version from the Deployments tab of the environment where the visual application is deployed.

    Example:

    
    Description of the illustration visualapp_deployment.png
13. Click Save.
14. To run a build, click Build Now.

After the build is successful, open the build's log. You'll see a similar message:

[2020-01-01 12:00:00] === Begin VB App Ops Undeploy Application===
[2020-01-01 12:00:00] Application employee-manager-visual-web-app/0.1 has been undeployed
[2020-01-01 12:00:00] === End VB App Ops Undeploy Application ===
Executor log size 364 B (364)
[2020-01-01 12:00:02] 
[2020-01-01 12:00:02] Build completed.
[2020-01-01 12:00:02] Status: DONE Result: SUCCESSFUL Duration: 7.0 sec