Set Up VB Studio to Extend Oracle Cloud Applications

This chapter tells you how to set up Oracle Visual Builder Studio (VB Studio) so your users can work with Oracle Cloud Applications in an extension.

An extension is what your team members use to deliver new capabilities into Oracle Cloud Applications. In most cases, an extension contains the work a user has done to customize an app to meet specific business needs. See What Is an Extension? to learn more.

While this chapter explains everything you need to set up VB Studio for use by others, there are only a handful of activities that MUST be done before a user tries to use VB Studio, described in Essential Set-up Tasks. After you have completed these steps, users need only click the Edit in Visual Builder button in their Oracle Cloud Application, and VB Studio will guide them through the necessary steps so they can begin their work. Of course, there are a few other activities that you may want to perform after completing the essential tasks, as described in Advanced Administrator Tasks, but those are purely optional.

Manage Your Instances

Only one VB Studio instance can be provisioned in an Oracle Cloud account.

By default, a VB Studio instance is provisioned with your first Oracle Cloud Applications TEST instance. If you wish to use VB Studio with a different Oracle Cloud Applications TEST or DEV instance, file a service request so that we can terminate the VB Studio instance associated with your current *-TEST or *-DEV instance, create a new one, and associate the new one to your preferred instance. Provisioning VB Studio for PROD instances is not supported. Only one move between pods is allowed, unless a pod must be terminated for some reason and therefore requires another association.

When you file the service request, please ask for instructions to backup your VB Studio projects so you don’t lose any data.

Your organization may have multiple environment families, each with its own TEST instance. If you need to determine which TEST instance VB Studio is associated with, contact your Oracle Cloud account administrator, who has access to your organization's cloud account and can retrieve this information.

While you can use the VB Studio instance that was provisioned alongside your Oracle Cloud Applications account to create visual applications, you’ll need an instance of Visual Builder to deploy them to. By default this instance is in a different identity domain than VB Studio, so you'll need to follow the procedures described in Create and Set Up a Project for Development (Different Identity Domain). If you decide to create this instance in the same domain as your VB Studio and Oracle Cloud Applications instance, see Create and Set Up the Project for Development (Same Identity Domain).

Essential Set-up Tasks

Before you can start setting up or using VB Studio, there are a few tasks that must be performed first:

  1. Make sure you have 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

    You’ll need these permissions to set up VB Studio and your Oracle Cloud Applications instances, and to deploy an extension to an Oracle Cloud Application environment.

  2. Make sure you are assigned the DEVELOPER_USER or DEVELOPER_ADMIN VB Studio role in your instance so you can access VB Studio. If you don't have either one of these roles, you need to sign into the IDCS console and assign yourself or your user(s) one of them. If you can't do this yourself, please consult with the infrastructure administrator at your site who has the necessary IDCS identity administrator privileges.

    See Assign VB Studio Roles in Oracle Identity Cloud Service (IDCS). Without these role assignments, the first user (you or one of your users) who begins to create a simple extension will see the error, "You are not a member of this Organization."

  3. If your Oracle Cloud Applications instances restrict ingress IP access, you’ll need to add your VB Studio infrastructure IP address to the list of allowed IP addresses in your Web Application Firewall (WAF) and/or Location Based Access Control (LBAC) configuration.
  4. Ask the Oracle Cloud Applications administrator to enable Cross-Origin Resource Sharing (CORS) by adding the VB Studio's root URL to the Oracle Cloud Application's ORA_CORS_ORIGINS profile option. This option is used to specify which domains can talk to each other.
    Note

    Production to Test (P2T) and other operations that replace the database can cause the profile option value to change. You must repeat these steps if you perform any operation that replaces the database.

    To enable CORS, the Oracle Cloud Applications admin must:

    1. Open VB Studio from the Oracle Cloud Applications instance and copy the VB Studio URL from the browser's address bar.
    2. In the Oracle Cloud Applications instance, click Navigator the Menu icon .
    3. Under Others, click Setup and Maintenance.
    4. On the right side of the page, click Tasks,Tasks icon then click Search.
    5. In the search box, enter Manage Administrator Profile Values and click the Search icon.
    6. In the search results, click Manage Administrator Profile Values.
    7. In Profile Options Code, enter ORA_CORS_ORIGINS, then click Search.
    8. Under ORA_CORS_ORIGINS: Profile Values, if you see a value with Profile Value set to * you can ignore the remaining steps, because this Oracle Cloud Applications instance is already set to allow all origins.

      If you don't see the * value, or if you want to restrict allowed origins from all origins to certain origins, such as your VB Studio instance, proceed to the next step.

    9. Under ORA_CORS_ORIGINS: Profile Values, click New.
    10. In Profile Level, select Site.
    11. In Profile Value, enter 'self' (including the single quotes), followed by VB Studio's root URL. For example: 'self' https://abcd-test-DEVCSAPP-07012210-2070-abcd.developer.ocp.oraclecloud.com
      Note

      Don't include port numbers, wild cards, or extraneous characters after the root. For example, if the VB Studio’s full URL is https://abcd-test-DEVCSAPP-07012210-2070-abcd.developer.ocp.oraclecloud.com:443/abcd-test-devcsapp-07012210-2070-abcd, the root is simply https://abcd-test-DEVCSAPP-07012210-2070-abcd.developer.ocp.oraclecloud.com.

      Your screen should look something like this:
      Description of oraclecloudapps_vbstudio_root.png follows

    12. Click Save and Close.

Create a Simple Extension

The easiest way to set up VB Studio for others and ensure everything is working properly is to create a simple extension yourself, which walks you through the required steps. There are some other steps you may want to complete later, but those are optional.

The best practice is to create one project for each Oracle Cloud Application your users will want to configure, so that all the code for that Application is stored in the same Git repository. (A VB Studio project gathers all the resources you need for your software development effort, depending on what that is.) For that reason, you’ll need to repeat the following steps for each such Oracle Cloud Application:

  1. Navigate to a page in the Oracle Cloud Application, then click Edit Page in Visual Builder:
    Description of editpagenew.png follows

    If you don't see the pencil in the lower right corner, open the Settings and Actions menu and click Edit Page in Visual Builder:
    Description of fa-edit-page-link.png follows

  2. In the New App Extension Project dialog, enter a unique name for the project, as well as some team members or groups you think might use this project to extend this Oracle Cloud Application:
    Description of newappextproj.png follows

    Note

    After you've completed this procedure, make sure that the team members you've added have the proper roles, by following the steps in Set Up VB Studio Users.

    VB Studio shows you a status dialog so you can follow along as each asset is created:
    Description of projprogress.png follows

    If you're curious about these assets, you can find out more about them in What Project Artifacts Are Created?.

    By default, VB Studio creates a private project that’s discoverable, which means that users you haven’t added explicitly to the project will be allowed to choose the project when they click Edit Page in Visual Builder from the associated Oracle Cloud Application. Remember, it’s best to keep all work for a given Oracle Cloud Application within the same project, so VB Studio will place a “Recommended” badge next to the project’s name to encourage users to select it.

  3. VB Studio opens the page you were just viewing in the Designer, with the extendable components outlined in green, like this:
    Description of extendableareasingreen.png follows

  4. Make a small change to the page, just for testing purposes. You can drag a Heading component onto the page, for example, or add or remove a field on a dynamic form. VB Studio implicitly saves your changes as you work.
  5. In the Designer's header, click Publish:
    Description of designer-publish-changes-action.png follows

    The Publish action automatically commits your changes and pushes them to the Git repo, then opens this dialog:
    Description of publishchanges.png follows

  6. Add a brief comment to describe your changes, then click Publish Changes.
  7. Add valid credentials for this Oracle Cloud Applications instance. Be sure to supply Oracle Cloud Application credentials, as opposed to those for Visual Builder Studio, SSO, or any other system. Once you do this, other users deploying to this instance will not be prompted for credentials.

    The pipeline that was created as part of the project contains two jobs: a package job (called extensionName-Package), which generates the extension's artifact file, and a deploy job (extensionName-Deploy, which deploys the extension's artifact file to the Oracle Cloud Application's Development environment. After testing, you can set up a separate pipeline to publish the build artifact to the live (PROD) instance; see Set Up the Project to Deploy to Production.

    Let's take a look at the pipeline that's kicked off as part of the Publish process.

  8. Click the upper left hand arrow to exit the Designer:
    Description of gotoprojectside.png follows

  9. In the VB Studio left navigator, click Builds, then click Job Queue:
    Description of jobqueue.png follows

    In this example, you can see that the package job has already begun running, which will be followed by the deploy job. Depending on how long it takes for you to arrive on the Job Queue tab, you may see a message in the Progress field that says the job is waiting for a VM executor to become available. This should resolve itself shortly.

    Take a moment now to investigate the Jobs, Pipelines, and Pipeline Queue tabs.

  10. View your published changes.

    After the deploy job completes, you'll be able see your work by going to your Oracle Cloud Applications instance and pointing your browser to the App UI you just configured. You may need to re-authenticate to see your latest changes.

  11. As this was just a simple test and not a real extension, you may want to remove it. To do so, see Delete an Extension Manually.
What's Next?

At this point, you have several options:

Set Up VB Studio Users

To extend Oracle Cloud Applications applications with VB Studio, users need roles in both Oracle Cloud Applications and IDCS.

As an administrator, you must have certain privileges to assign the necessary roles:
  • In Oracle Cloud Applications, you must have one of these privileges: cloud administrator, service administrator, or application administrator.
  • In IDCS, you must have either an Identity Domain Administrator or User Administrator role.
This table shows how to map the VB Studio IDCS roles to users with Oracle Cloud Application roles:
Oracle Cloud Applications users with these roles: Need to be granted this VB Studio IDCS role:

Application Administrator (ORA_FND_APPLICATION_ADMINISTRATOR_JOB)

Sales Administrator (ORA_ZBS_SALES_ADMINISTRATOR_JOB)

Customer Relationship Management Application Administrator (ORA_ZCA_CUSTOMER_RELATIONSHIP_MANAGEMENT_APPLICATION_ADMINISTRATOR_JOB)

VB Studio administrator (DEVELOPER_ADMINISTRATOR)

Application Developer (ORA_FND_APPLICATION_DEVELOPER_JOB)

VB Studio user (DEVELOPER_USER)
How Do I Assign the Roles?

Role assignment is a two-step process:

  1. Create an Oracle Cloud Applications user, then assign a role to that user using the Oracle Cloud Applications Identity manager. See Assign Oracle Cloud Application Roles.
  2. In IDCS, manually assign a VB Studio role (DEVELOPER_ADMIN or DEVELOPER_USER) to the Oracle Cloud Applications user. See Assign VB Studio Roles in Oracle Identity Cloud Service (IDCS).
Assign Oracle Cloud Application Roles

Before beginning the process, review some background information:

  • Standard roles (listed in step 7 below) are predefined. Their permissions are automatically updated as necessary, such as when new features or services are added.
  • Custom roles are created as substitutes for standard roles, allowing only specific privileges.

    Any custom roles you create for Oracle Cloud Applications users must contain two privileges, FND_ADMINISTER_SANDBOX_PRIV and FND_MANAGE_SANDBOX_PRIV. The custom roles are assigned to VB Studio IDCS roles in the same manner as standard roles, with administrative roles mapping to the VB Studio administrator role in IDCS and non-administrative roles being assigned the VB Studio developer role in IDCS.

To assign an Oracle Cloud Applications role to a new or existing Oracle Cloud Applications user:

  1. Sign in to the Applications Console.
    Make sure that you specify the identity domain where you want to create the user.
  2. Click Navigation the Menu icon menu to open the navigation menu and, under Tools, click Security Console.

    Description of fa-tools-security-console.png follows

  3. Click Users in the navigation pane.
    The User Accounts page is displayed.
    Description of fa-user-accounts-page.png follows

  4. To create a new user, click Add User Account and follow the prompts. To assign a role to an existing user, use the Search field to find the user you want, then skip to step 6.
    The Add User Account page is displayed.
  5. Fill out the User Information fields (First Name, Last Name, Email, Password, Confirm Password).

    Description of fa-add-user-account-page-filled.png follows

    The User Name field has been filled in for you, using the first and last names you entered separated by a period.

  6. Click Add Role.
    The Add Role Membership from Role page is displayed.
  7. Select one of the standard Oracle Cloud Applications roles:
    • Application Administrator (ORA_FND_APPLICATION_ADMINISTRATOR_JOB)
    • Sales Administrator (ORA_ZBS_SALES_ADMINISTRATOR_JOB)
    • Customer Relationship Management Application Administrator (ORA_ZCA_CUSTOMER_RELATIONSHIP_MANAGEMENT_APPLICATION_ADMINISTRATOR_JOB)
    • Application Developer (ORA_FND_APPLICATION_DEVELOPER_JOB)

    If you created a custom role, you can select it instead of a standard role.

  8. After you select the role to assign to the user, click Add Role Membership.

    Description of fa-add-role-membership-done.png follows

  9. Click Done.
    The Add User Account page is displayed, showing the new user with an assigned role.
    Description of fa-add-user-account-role-all-filled.png follows

  10. Click Save and Close.

Now it's time to assign one of the VB Studio roles in IDCS to the Oracle Cloud Application user.

Assign VB Studio Roles in Oracle Identity Cloud Service (IDCS)

If you just created a new user in Oracle Cloud Applications, it will take at least 30 minutes for the user profile to show up in IDCS so that you can assign a VB Studio user role to it.

IDCS has two different interfaces (upgraded and Classic), so choose the process that's applicable to you.

Assign Roles with the Upgraded IDCS Interface

Assign VB Studio access to users in the IDCS stripe associated to the Oracle Cloud Application instance:
  1. Sign in to your Identity domain using your credentials and the URL you received.

    If your Identity Cloud Service instance has been upgraded to an identity domain on Oracle Cloud Infrastructure (OCI), you'll see this page:
    Description of oci-upgrade-screen.png follows

  2. Click the Take me there button.
    The domain's Overview page is displayed.
    Description of oci-domain-overview-screen.png follows

    Tip:

    If you click the Don't show me this again check box, the page with the upgrade notice will be bypassed and you'll see the domain's Overview page after you log in.

    If you see a page that looks quite different, your IDCS hasn't been upgraded and you're using the Classic interface. See Assign Roles with the Classic IDCS Interface.

  3. If your login didn't take you to the service you need to modify, click the Navigation menu and, under the Identity domain list, click Oracle Cloud Services. Select the service in which you want to assign users from the list.
  4. In the Resources list, click Application roles.

    All member roles, in this case DEVELOPER_ADMINISTRATOR and DEVELOPER_USER, that can be assigned for the VB Studio service are displayed.
    Description of oci-application-roles-list-screen.png follows

  5. Click the down arrow on the right side of the role's row to display the list of resources you can manage:


    Description of oci-application-roles-manage-users-screen.png follows

  6. Click Manage next to Assign Users.

    The Manage user assignments dialog is displayed.
    Description of oci-manage-user-assignments-screen.png follows

  7. Click + Show available users, then use Search to locate the user name you are searching for.


    Description of oci-manage-user-assignments-locate-user-screen.png follows

  8. After you locate the user, click the Assign checkbox on the left side of the user's row, then click the Assign button.

    The Assigned users section of the panel shows the new user you assigned.
    Description of oci-manage-user-assignments-adding-user-screen.png follows

  9. Click the Close button.
  10. Repeat steps 7-10 to assign additional users.

Assign Roles with the Classic IDCS Interface

To assign VB Studio access to Oracle Cloud Applications users in the Classic stripe:
  1. Sign in to your Identity domain using your credentials and the URL you received in the Welcome email.

    The Identity Cloud Service Welcome page is displayed.
    Description of idcs-welcome-screen-classic.png follows

  2. Click the Navigation the Menu icon menu.

    The Navigation drawer is displayed.

  3. Click Oracle Cloud Services to display the list of service instances that are available in your identity domain.
  4. Scroll to find the service (or use the Search bar to find it), then click the box on the left side of the row to select it:


    Description of idcs-service-instances-screen-classic.png follows

    The App Details page is displayed.
    Description of idcs-app-details-screen-classic.png follows

  5. Select the Application roles tab, click the Menu icon on the right and select Assign Users.


    IDCS Classic Application Roles tab with the Assign Users menu option selected.

  6. In the Assign Users page, use Search to locate the user that you want to assign the VB Studio IDCS role to, then click the check box on the left side of the row to select the user.


    Description of idcs-assign-users-screen-classic.png follows

  7. Click OK.

    The Application Roles tab should now show an additional user (the one you just assigned the role to).
    Description of idcs-assign-users-screen-new-user-classic.png follows

  8. To verify that the user was assigned correctly, click the # Users Assigned link.

    The Users Assignments page is displayed, listing all the users who've been assigned the VB Studio IDCS role.

What Project Artifacts Are Created?

When you create a new project, several other VB Studio artifacts are also created for you. VB Studio shows you a status diagram so you can follow along as each artifact is generated:


Description of projprogress.png follows

These artifacts include:

  • A Git repository, which will contain the source code for all the extensions based on this project.

    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 default_appextn_git_repository.png follows

  • A Development environment, pointing to the development instance where the Oracle Cloud Application you plan to customize is running. (A VB Studio environment can include one or more instances of Oracle Cloud Applications, Visual Builder, Oracle Cloud SaaS, or Oracle Cloud Infrastructure service instances, so you can treat them as a single entity.) To see the definition for the Development environment, click Environments in the VB Studio navigator:
    Description of developmentenv.png follows

  • A workspace, which is a private area where you work on your extensions. Each user has a unique workspace, although users can collaborate on the same extension by cloning each other's workspace (which also clones the project's Git repository).
  • Build jobs that package and deploy the extension's artifact to Oracle Cloud Application's development instance.

    The package job, named extensionName-Package, generates the extension's artifact file. The deploy job, extensionName-Deploy, deploys the extension's artifact file to the Oracle Cloud Application instance defined in the Development environment. (If you create a project manually, these jobs are named Application-Extension-Package and Application-Extension-Deploy.)

  • The extensionName-Package and Deploy pipeline, which runs the package and deploy build jobs in a sequence. (If you create a project manually, this pipeline is named Application Extension - Package and Deploy.)
  • A VM executor, but only if this is the first project in this VB Studio's instance and this instance did not already have any VM executors. (Builds in a build system run in build executors. The operating system and software packages required to run builds on build executors are defined in build templates.) The VM executor uses the System Default OL7 for Visual Builder 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.

Advanced Administrator Tasks

Once you’ve completed the essential tasks and set up one or more projects, there are a few other things you may want to do to tailor operations so they better suit your organization’s needs:

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 and allow branch merges only after they are approved.

Be sure to repeat this process for each project you created in Create a Simple Extension.
  1. In the navigation menu, click Project Administration 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) 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.

Set Up the Project to Deploy to Production

By default, a project deploys extensions to the Development environment, which is the Oracle Cloud Application instance you were using when you clicked Edit Page in Visual Builder. Follow these steps to deploy to the PROD instance, so users can deploy to it after their development and test cycles are complete.

The Oracle Cloud Applications PROD instance resides in a different identity domain from the DEV and TEST instances, which means you’ll need the URL for the PROD instance, as well as user credentials that VB Studio can use to deploy to this instance.

To set up a project to deploy to PROD:

  1. Add the PROD instance to an environment
  2. Create a production branch
  3. Create and configure production build jobs
  4. Configure the pipeline so that the packaging and deployment jobs run in succession
  5. Run the production pipeline.
Add the Oracle Cloud Application's Production Instance to an Environment

Only one Oracle Cloud Applications instance can be added to an environment. As the Development environment already points to the TEST instance (or DEV, if you asked Oracle to re-associate it), you must create a new environment for the PROD instance.

To create a new environment for the PROD instance:

  1. In the VB Studio navigator, click Environments.
  2. Click + Create Environment.
  3. In the Service Instances tab, click + Add Instance.
  4. In the Add Service Instances dialog box, select the Oracle Cloud Applications option button.
  5. Under Authentication Method, select the Application Credentials option.
  6. In Base URL, enter the Oracle Cloud Application's base URL.
  7. In Instance Name, if required, update the instance's display name. The name will be displayed in the Service Instances tab.
  8. In Username and Password, enter the credentials of a user who can access this Oracle Cloud Applications instance.
  9. Click Add.

If the newly added instance stays in the Unknown status for some time, it typically indicates that the IDCS Application provisioning may have failed. In other words, VB Studio added the Oracle Cloud Applications instance, but can't access it. In this case, click Actions Three horizontal dots and select Remove to remove the Oracle Cloud Applications instance from the environment, and then click Add to add it again.

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 Git.
  2. Click the Refs view and then click Branches 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, any changes pushed to the main branch aren't automatically available in the production branch. You must create a merge request or manually push the changes to the production branch.

If you want to set merge restrictions on the production branch, 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 extensions to your Oracle Cloud Application's PROD instance. Follow this process:

  1. Migrate the configurations to the production Oracle Cloud Application instance. See Overview of Configuration Life Cycle and Overview of Migration in Configuring and Extending Applications for instructions.
  2. Create a build job that packages the extension. See Create the Production Packaging Build Job for instructions.
  3. Create a build job that deploys the extension to the production instance. See Create the Production Deployment Build Job for instructions.
  4. (Optional) Restrict who can see or edit the production build jobs or run their builds. See Configure a Job's Privacy Setting for instructions.
  5. Configure the pipelines to run the packaging and deployment jobs in succession. See Create and Configure the Production Pipeline for instructions.
  6. Run the production pipeline to package the extension and deploy it to the production instance. See Run Production Pipelines for instructions.
Before You Configure Build Jobs and Pipelines

Here are some things you need to know before you configure and run build jobs and pipelines:

  • Make sure that the source and target instances are of the same release, with the same standard and one-off patches applied to both environments.
  • In the development packaging job, if you changed the default artifact's file name, get the new name and its path.
  • If you configured the development packaging job to overwrite the application's version defined in visual-application.json, get the new version. You'll configure the production's packaging job to use the same version.
Create the Production Packaging Build Job

The packaging job generates an extension artifact that's ready to deploy to the mainline.

  1. In the navigation menu, click Builds 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 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 Application Extension, and then select Package.
  13. By default, the packaging step minifies the application's source code before running the build. If you don't want to minify the source files, deselect the Optimize extension 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.

    Note

    When you deselect the Optimize extension check box, this warning is displayed: Optimization not selected. Packaging without optimization can cause performance problems, so avoid doing so unless you're debugging or troubleshooting.
  14. (Optional) If you want to change the artifact file's name, in Artifact, enter the new name. By default, it is extension.vx.
  15. (Optional) If you configured the development packaging job to overwrite the extension's default version defined in the visual-application.json file, specify the same version in Extension Version.
  16. Click the After Build tab.
  17. From Add After Build Action, select Artifact Archiver.
  18. In Files to archive, enter the build artifact name. You can also use wild characters. For example, *.vx.
  19. If you want to discard the build's old artifacts, click Settings the Gear icon. In the General tab, select the Discard Old Builds check box and specify the discard options.
  20. Click Save.
Create the Production Deployment Build Job

The deployment job deploys the extension's artifact that was generated in the packaging job to the Oracle Cloud Application's production instance. Before you create the job, make sure you have credentials that VB Studio can use to access the Oracle Cloud Application's PROD instance.

  1. In the navigation menu, click Builds 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 Configure.
  8. Click the Before Build tab.
  9. From Add Before Build Action, select Copy Artifacts.
  10. In From Job, select the packaging job that generated the extension's artifact.
  11. In Which Build, select one of the following:
    • Last successful build (default)
    • Last keep forever build
    • Upstream build in this pipeline instance
    • Specified by permalink
    • Specific build
    • Specified by build parameter
    Depending on what you select, you may be prompted to select which permalink, build, or build parameter you want to be used.
  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 environment with the Oracle Cloud Application's production instance.
  16. In Username and Password, enter the credentials of an IDCS user who is not only an Oracle Cloud Applications user, but one who can connect and deploy to the Oracle Cloud Application's production instance.
  17. In Build Artifact, enter the same artifact name that you used in the packaging build step.
  18. Click Save.
Note

If you develop an extension on, say, 23D in your Test environment, then want to deploy the extension to your 23C Prod environment, you'll have to wait until your Prod instance has been upgraded to 23D before you can deploy successfully. In most cases, there shouldn't be more than a two week gap between pod upgrades.
Configure a Job's Privacy Setting

The project owner can mark a job as private to restrict who can see or edit a job's configuration, or run its build:

  1. In the navigation menu, click Project Administration Project Administration.
  2. Click Builds.
  3. Click the Job Protection tab.
  4. From the jobs list, select the job.
  5. Select the Private option.
  6. Select the Allow commits and triggers to start this private job checkbox if you want SCM commits and triggers to be able to automatically run this job.

    Description of job-protection-all-commits-and-triggers-checkbox-selected.png follows

    With the checkbox selected, periodic triggers will run any job or pipeline, including private jobs set to allow commits and triggers to start the private job. If a private job with this option selected is included in a pipeline and a non-authorized user attempts to run the pipeline manually, the private job won't run but periodic triggers and SCM commits will.

    Leave the checkbox unselected if you don't want the job to be started when it is triggered by an SCM commit or timer.

    Note

    Best Practice:

    If you use the checkbox to enable the protected build to be triggered by an SCM commit, you need to protect the branch that the build job is tied to. If you don't do this, anyone can trigger the protected build by making a commit to trigger the build.

  7. Click in the Authorized Users/Groups field to view a list of Users and Groups that have permission to access this project.

    From the list, select one or multiple users and groups. Don't forget to add yourself.


    Description of job-protection.png follows

  8. Click Save.

You can see if a job is private from several places in the VB Studio user interface. A private job is indicated by a Lock Lock icon:

  • In the jobs list found on the Project Administration tile's Builds page's Job Protection tab, to the right of each protected job's name.

  • In the Private column on the Builds page's Jobs tab.

  • In the jobs shown in the the Builds page's Pipelines tab.

An unauthorized user can't run a private build job manually, or through a pipeline, or via an SCM/periodic trigger.

Create and Configure the Production Pipeline

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

  1. In the navigation menu, click Builds 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 Pipeline Configuration page, right-click the Start node and select Add New Start jobs.
  7. Click in the Select new on success job(s) field, select the packaging job and click Save.
  8. Right-click the packaging job and select Add, then Add New On Success Jobs.
  9. Click in the Select new on success job(s) field, select the deployment job, and click Save.

    Here's an example of the final pipeline:


    Description of build_appextn_prod_pipeline_deploy.png follows

  10. Click Save.
Run Production Pipelines

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

  1. In the navigation menu, click Builds Builds.
  2. Click the Pipelines tab.
  3. In the production pipeline's row, click the Actions Actions menu and select Run Pipeline.

After a successful build, you can see the deployed application's link in the Environments page's Deployments tab. You should also notify the Oracle Cloud Applications administrator that the extension has been pushed to the Oracle Cloud Application's production instance.

Set Up the Project to Deploy to Other DEV and TEST Instances

If you've followed this chapter to this point, you've configured VB Studio to deploy extensions to your primary Oracle Cloud Applications Development environment. This topic explains how to set up other Oracle Cloud Application instances, such as DEV and TEST, where your team members may want to test their extensions before deploying to PROD.

This involves creating an environment for each instance you want to deploy to, as well as configuring jobs and pipelines to package up and deploy extensions to those target instances.

Before you proceed, make sure that the Oracle Cloud Applications instances are up and running.

Add an Oracle Cloud Application Instance to an Environment

To deploy an extension to an Oracle Cloud Applications instance, you must create a VB Studio environment and add the instance to it. You can add only one Oracle Cloud Applications instance to each environment.

Each Oracle Cloud Applications DEV and TEST instance has its own identity domain. This means you'll need the target instance's URL—as well as a user's credentials that can access the instance—to set up the environment.

Here's what your Environments page might look like after you've added three new environments, one for another DEV instance and two for some TEST instances:
Description of vbs_environments.png follows

To create a new VB Studio environment:

  1. In the VB Studio navigation menu, click Environments.
  2. Click + Create Environment. In Environment Name and Description, enter a unique name and description, then click Create.
  3. In the Service Instances tab, click + Add Instance.
  4. In the Add Service Instances dialog box, select the Oracle Cloud Applications option button.
  5. Under Authentication Method, select the Application Credentials option.
  6. In Base URL, enter the Oracle Cloud Application's base URL.
  7. In Instance Name, if required, update the instance's display name. The name will be displayed in the Service Instances tab.
  8. In Username and Password, enter the credentials of a user who can access the Oracle Cloud Applications instance.
  9. Click Add.

If the newly added instance stays in the Unknown status for some time, it typically indicates that the provisioning may have failed. VB Studio added the Oracle Cloud Applications instance but can't access it. In such a case, click Actions Three horizontal dots and select Remove to remove the Oracle Cloud Applications instance from the environment, and then click Add to add it again.

Create and Configure Deployment Build Jobs and Pipelines

To deploy extensions to other Oracle Cloud Applications instances, you need to set up or create a packaging job, one or more deploy jobs, and a pipeline. Specifically:

  • A packaging job packages the extension and creates a build artifact. Instead of creating new packaging jobs, you can use the extensionName-Package job that was created with the project. (If you created this project manually, the package job is called Application-Extension-Package.) This job packages the extension and creates a build artifact from the same branch your team members used to deploy to the primary Oracle Cloud Applications Development instance. Remember, this packaging job is configured to trigger a build on every SCM commit.
  • Create one deploy job for each Oracle Cloud Applications instance you plant to deploy to. You'll also need a user's credentials who can deploy to each Oracle Cloud Applications instance. To create the job, see Create a Deployment Build Job.
  • After you've created deployment jobs, create pipelines to run the package job and deployment jobs in sequence. You can create either of these pipelines:
    • A pipeline to deploy the extension to the primary and other Oracle Cloud Applications instances.

      Instead of creating a new pipeline, configure the existing extensionName-Package and Deploy pipeline to deploy to other instances as well. (If you created this project manually, this pipeline's name is Application-Extension Package and Deploy.) See Configure the Default Pipeline to Deploy to Other Oracle Cloud Applications Instances. Remember, the default pipeline runs automatically when a code change is pushed to the main branch. After you've configured the pipeline, it deploys the extension to all development and test instances on every SCM commit to the main branch.

      After creating this pipeline, you'll have one pipeline in your project that deploys to all DEV and TEST instances.

      Here's an example of what this pipeline could look like:


      Description of build_appextn_main_pipeline.png follows

    • A pipeline to deploy the extension to other DEV and TEST Oracle Cloud Applications instances manually. See Create and Configure a Pipeline to Deploy to Other Oracle Cloud Applications Instances.

      Create this pipeline if you don't want to deploy the extension to other instances on every SCM commit, but only after your team members have validated the extension on the on the primary development instance.

      After creating this pipeline, you'll have two pipelines in the project: 1) Your primary pipeline, which deploys to the primary development instance, and 2) this pipeline, which deploys to other DEV and TEST instances.

      Here's an example of what these pipelines could look like:


      Description of build_appextn_main_and_other_pipeline.png follows

Create a Deployment Build Job

The deployment job deploys the extension's artifact that was generated in the default packaging job to the Oracle Cloud Application's instance. Before you create the job, make sure you have credentials that VB Studio can use to access the instance.

  1. In the navigation menu, click Builds 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. Select the Copy From Existing check box.
  6. From the Copy From drop-down list, select the Application-Extension-Deploy job.
  7. In Template, make sure that the System Default OL7 for Visual Builder template is selected.
  8. Click Create.
  9. Click Configure the Hammer icon.
  10. Click the Steps tab.
  11. In Target Instance, select the environment with the target Oracle Cloud Applications instance.
  12. In Username and Password, enter the credentials of a user who can deploy to the Oracle Cloud Applications instance.
  13. Click Save.
Configure the Default Pipeline to Deploy to Other Oracle Cloud Applications Instances

If you want to deploy to other DEV and TEST instances along with your primary Oracle Cloud Applications instance, you can configure the default pipeline to deploy to other instances as well.

  1. In the navigation menu, click Builds Builds.
  2. Click the Pipelines tab.
  3. In the extensionName-- Package and Deploy pipeline row, click the Actions menu and select Configure Pipeline. (If you created the project manually, the pipeline name is Application Extension - Package and Deploy.)
  4. Right-click the extensionName-Package job and select Add, then Add New On Success Jobs.

    Here's an example:


    Description of pipeline-appextn-add-jobs.png follows

  5. Click in the Select new on success job(s) field, select the jobs that you want to add from the list, and click Save.

    Description of pipeline-appextn-test-jobs.png follows

    Here's an example of the final diagram:

    Description of pipeline-appextn-test-jobs-final.png follows

  6. Click Save.
Create and Configure a Pipeline to Deploy to Other Oracle Cloud Applications Instances
  1. In the navigation menu, click Builds 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. Deselect the Auto start when pipeline jobs are built externally check box.
  6. Click Create.
  7. On the Pipeline Configuration page, right-click the Start node and select Add New Start jobs.
  8. Click in the Select new on success job(s) field, select extensionName-Package, and click Save.

    Description of build_appextn_other_pipeline.png follows

  9. Right-click the extensionName-Package job and select Add, then Add New On Success Jobs.
  10. Click in the Select new on success job(s) field, select the jobs that you want to add from the list, and click Save.
    Here's an example of a finished pipeline:

    Description of build_appextn_other_package_pipeline.png follows

  11. Click Save.
Run the Pipeline
  1. In the navigation menu, click Builds Builds.
  2. Click the Pipelines tab.
  3. In the pipeline's row, click the Actions Actionsmenu and select Run Pipeline.

After a successful build, you'll find the deployed application's link on the Environments page's Deployments tab. Newer extensions, which are based on App UIs, are shown under Application Extensions, while older extensions are shown under Application Extensions Classic. You can learn more about this in Package, Deploy, and Manage Application Extensions.

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

Delete an Extension

The method you use to delete an extension depends on if it is deployed to the Oracle Cloud Instance named in your primary Development environment, or if it's deployed to another pod (a different DEV pod, or a TEST or PROD instance).

You delete an extension manually if the extension is deployed to an Oracle Cloud Applications instance that's in the same identity domain as VB Studio (by default a TEST pod, although it could be a DEV pod or a different TEST pod if you requested that Oracle re-associate VB Studio to a different pod). If the extension is deployed to a different identity domain (typically your PROD instance), you should configure a build job to delete it.

Delete an Extension Manually

Use the manual method to delete an extension that's deployed to the Oracle Cloud Applications instance that's in the same identity domain as your VB Studio instance:

  1. In the navigation menu, click Environments Environments.
  2. Select the Development environment where the extension is deployed.
  3. Click the Deployments tab.
  4. Expand the base application's name.
  5. Click Actions Three horizontal dots and select Delete next to the extension you want to delete.
  6. In the confirmation dialog box, click Delete.

Configure a Build Job to Delete an Extension

To delete an extension that's deployed to your PROD Oracle Cloud Applications instance (or to any Oracle Cloud Applications instance in a different identity domain from VB Studio), configure a build job and run it. You can't delete it manually.

Before you configure and run the job, delete the extension from the DEV instance (or TEST instance, if applicable) and make sure there aren't any adverse effects. For example, let's assume you have an attribute that's hidden in both the extension's business object and the user interface. After you delete the extension, the user interface shows the attribute that is still hidden in the business object. This may cause an error.

To configure the job, make sure you have valid credentials for the Oracle Cloud Application's instance where the extension is deployed.

  1. In the navigation menu, click Builds 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 System Default OL7 for Visual Builder.
  6. Click Create.
  7. On the Job Configuration page, click Configure Configure.
  8. Click the Steps tab.
  9. From Add Step, select Application Extension, and then select Delete.
  10. In Instance, select the Oracle Cloud Applications instance where the application is deployed.
  11. In Username and Password, enter the credentials of an IDCS user who is not only an Oracle Cloud Applications user, but one who can connect and undeploy from the Oracle Cloud Application's production instance.
  12. In Base Application, Name, and Version, enter the extension's base application, name, and version.
    You can find the details on the Deployments tab of the environment where the extension is deployed.

    Example:


    Description of appextn_deployment.bmp follows

  13. Click Save.
  14. To run a build, click Build Now.

Manual Administrator Tasks

VB Studio is designed to make accessing the product and creating a project quick and easy, simply by clicking the Edit Page in Visual Builder link in an Oracle Cloud Application. However, there are times when you may want to complete these tasks manually.

Manually Create a Project for Extensions

The easiest way to create a project for extensions is through the Edit Page in Visual Builder link in an Oracle Cloud Application, although the option to create a project manually is always available. Ideally, you'll create one project for each Oracle Cloud Application you plan to extend, such as Sales, Journeys, and so on.

To create an extension project manually:

  1. On the Organization page, click + Create.
  2. On the Project Details page of the New Project wizard, in Name and Description, enter a unique name and description for the project.
  3. In Security, select the project's privacy setting:
    1. Select Private to restrict access to project members only.
      The Discoverable checkbox, selected by default for private projects, allows organization members that aren't org admins or project members to see basic information, such as name and owner contact information, about your private project. Private projects that aren't discoverable won't be exposed to non-members.
      Note

      If you want this project to be visible to users when they use the "Edit Page in Visual Builder" option to make changes to their Oracle Cloud Applications page in VB Studio, mark it as Discoverable. This gives users an opportunity to select a project that's already associated with the page they want to modify (or they can create a new project, if they prefer).

    2. Select Shared to make the project code, wiki docs, tasks, and builds available to anyone inside your organization.
  4. 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.
  5. Click Next.
  6. On the Template page, select the Application Extension template, then click Next.
    If you don’t see the Application Extension 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.

    When you create a project, VB Studio also creates a workspace and an extension for you. Use these to create your own extension, if you like, or let one of your team members use it.

  7. On the Project Properties page:
    1. In Extension Name, if necessary, change the extension's name. Make sure that the extension name is unique across all the extensions created for this Oracle Cloud Application. By default, the name is <project_name> Extension.
    2. In Extension Id, if necessary, change the extension's ID. Make sure that the ID is unique across all the extensions created for this Oracle Cloud Application. By default, the ID is site_<extension_name>.
    3. 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 extensions, 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? Again, you don't have to use this workspace to develop an extension; it's created purely for your convenience. (When a team member accesses VB Studio from their Oracle Cloud Application, a workspace is automatically created for the user if one doesn't already exist.)

    4. In Oracle Cloud Applications Development Instance, VB Studio preselects your current identity domain's Oracle Cloud Applications instance and uses it as the development instance to develop extensions.
      If there are multiple Oracle Cloud Applications instances in your identity domain, you'll be asked to choose. Make sure to select the Oracle Cloud Applications instance you want to use to develop extensions. Make sure that the selected instance has a VB Studio instance provisioned and also has the Oracle Cloud Application you want to extend.
    5. From Base Application, select the Oracle Cloud Application you want to extend in this project.
    6. In Git Repository Name, change the Git repository's default name, if required. When a team member creates a workspace, a copy of this repository is made for the user's local changes. When the user executes the Git Push command, the changes are copied to the project's repository (also known as the "remote repository", in VB Studio terms).
    7. In Working Branch Name, if required, change the workspace's working branch name. By default, it is branch1.
      Follow your organization's guidelines for creating and managing Git repository's branches. When the project is provisioned, the Git repository's main branch is ready for you to start working on an extension, should you opt to do so. Whenever someone creates a workspace, VB Studio creates a copy of the main branch, renames it with the specified name, and uses it as the workspace's working branch. This documentation assumes that you'll continue to use main as the development branch and create a separate branch for production.
  8. On the Team page:
    1. Click Add Members and select Oracle Cloud Applications users or groups to add to the project, from the list displayed, if you know they may work in this project.
    2. Select the membership (Project Owner, Developer Full Access, Developer Limited Access, or Contributor) that the members you're adding will have in the project: See What Are Project Memberships? for more information about each membership.
    3. Click Add.
    4. Repeat substeps a, b, and c for different users and groups with various membership types, if needed.
  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; and Git, Maven, and NPM repositories. Review the activity feed and the Environments box for any errors.

Access VB Studio from Oracle Cloud Applications

While the Edit Page in Visual Builder link in an Oracle Cloud Application is the easiest way to access VB Studio, there is an alternative approach:

  1. In your Oracle Cloud Applications instance, click Navigator the Menu icon .
  2. In the navigation menu, under Configuration, select Visual Builder.

    Description of oracle_apps_navigator_vbstudio.png follows

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.