3 Set Up Oracle Visual Builder Studio for Extending Oracle Cloud Applications

This chapter tells you how to set up Oracle Visual Builder Studio (VB Studio) so that your users can customize certain Oracle Cloud Applications by creating application extensions.

An app extension is an artifact that allows you to extend certain Oracle Cloud Applications to meet your business needs. You deploy an app extension to an Oracle Cloud Applications instance. This documentation assumes that you have created and set up Oracle Cloud Applications instances for development, test, and production environments in different identity domains.

Here's a summary of how to set up VB Studio for developing app extensions:

To perform this action: See this: Why do I need to perform this action?
1. Get the required IDCS roles assigned to you Before You Begin To create and set up the VB Studio instance, you must be assigned some specific IDCS roles.
2. (Optional) Create the VB Studio instance Create the VB Studio Instance To use any Oracle Cloud service, you must first create an instance of the service. If the VB Studio instance isn't provisioned for you, create it.
3. Set up OCI or OCI Classic connections Connect to OCI or OCI Classic You need a connection to OCI or OCI Classic Compute VMs because this is where your VB Studio builds will run.
4. Assign Oracle Cloud Applications users VB Studio access Set Up VB Studio Users To allow Oracle Cloud Applications access to VB Studio, sync Oracle Cloud Applications with Oracle Identity Cloud Service (IDCS) and then assign them VB Studio roles.
5. Create a project for app extensions Create a Project for Application Extensions To develop an app extension, you must create a VB Studio project based on the Application Extension template.
6. Set up the project for development Set Up the Project for Development When you create a project based on the Application Extension template, some artifacts are created by default. These artifacts require additional configuration before your team members can use them.
a) Add Build VMs Add Build VMs To run app extension's development, test, or production builds, you must create build jobs. Build jobs in VB Studio run on Build VMs. Only VB Studio administrators can create and manage the Build VMs.
b) Configure the packaging and deployment jobs Configure the Packaging Job and Configure the Deployment Job When you create an app extension project, certain packaging and deployment build jobs are created by default, but they're missing some configuration options. You must specify them manually.
7. Add Oracle Cloud Applications users to the project Add Users to the Project To allow your team members to access the app extension project, invite them to join the project.
8. Set up the project for testing Set Up the Project For Testing After your team members have completed their development tasks, you'll want to deploy the app extension to your Oracle Cloud Application's test instance.
a) Add the Oracle Cloud Application's test instance to an environment Add an Oracle Cloud Application's Instance to an Environment Create an environment for testing and add the Oracle Cloud Application's test instance to the environment.
b) Migrate Oracle Cloud Application's customization data from the development instance to the test instance Migrate Your Oracle Cloud Application’s Customizations Create and configure jobs to migrate customization data from the Oracle Cloud Applications development instance to the test instance.
c) Create the packaging and deployment build jobs, and set up a build pipeline Create a Packaging Build Job, Create a Deployment Build Job, and Create and Configure a Pipeline Create and configure the packaging and deployment jobs so that your app extensions will be promoted to your Oracle Cloud Application's test instance.
d) (Optional) Restrict access to the test build jobs Configure a Job's Privacy Setting To restrict who can view a build job's configuration, edit it, or run its build, mark the job as private.
9. Set up the project for deployment to production Set Up the Project to Deploy to Production You will likely want to set things up so that after your team members have completed their development tasks and tested the application thoroughly, the app extension is deployed to your Oracle Cloud Application's production instance.
a) Add the Oracle Cloud Application's production instance to an environment Add the Oracle Cloud Application's Production Instance to an Environment First, create an environment and add the Oracle Cloud Application's production instance to it.
b) Migrate Oracle Cloud Application's customization from the test instance to the production instance Migrate Your Oracle Cloud Application’s Customization Create and configure jobs to migrate customization data from the Oracle Cloud Applications test instance to the production instance.
c) 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 to promote your app extensions to your Oracle Cloud Application's production instance.
d) (Optional) Restrict access to the production 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.

This table lists the Oracle Cloud Applications and identity domain roles you'll need to set up VB Studio:

You must be assigned this role: To ...
Identity Domain Administrator or User Administrator Add users and assign IDCS roles.
DEVCS_APP_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.
Compute.Compute_Operations and Storage.Storage_Administrator Create and manage VMs on OCI Compute Classic and store artifacts on OCI Object Storage Classic. These roles are required only if you're an OCI Classic user.
FND_ADMINISTER_SANDBOX_PRIV privilege in Oracle Cloud Applications, or any of these roles in your Oracle Cloud Application's development, test, and production instances:
  • APPLICATION ADMINISTRATOR
  • APPLICATION DEVELOPER
  • SALES_ADMINISTRATOR
  • CUSTOMER RELATIONSHIP MANAGEMENT APPLICATION ADMINISTRATOR
Access sandboxes and your Oracle Cloud Application's development, test, and production instances.

Best Practices

Here are some best practices to follow while setting up VB Studio to develop app extensions.

  • Follow your organization's guidelines to create and set up Oracle Cloud Applications 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 Oracle Cloud Applications instances for development, test, and production environments, where each instance is in a different identity domain.

  • Create the VB Studio instance in the same Oracle Cloud account and identity domain as the Oracle Cloud Applications development instance. See Create the VB Studio Instance.
  • Ensure that you and your organization's users are assigned the correct Oracle Cloud Applications and VB Studio roles, as discussed in Assign VB Studio Roles to Oracle Cloud Applications Users.
  • If you're using OCI, keep these things in mind while setting up the OCI connection in VB Studio:
    • Create a separate compartment for VB Studio resources. This allows you to organize resources better because they aren't mixed with the other resources in your tenancy.
    • Create a separate group and a user to access the compartment.
    • Create a policy that defines access to the compartment.

    Set Up the OCI Connection tells you more about setting up a compartment, a group, and a policy.

  • Before you create a project, make sure that your Oracle Cloud Application's development, test, and production instances are up and running.
  • Create one project for each of your base Oracle Cloud Applications, taking care to use the Application Extension project template.
  • After creating the project, add Oracle Cloud Applications users to the project and assign them proper project roles.

    For example:

    • Assign the Limited Developer role to users who want to work on customization, but not run build jobs.
    • Assign the Contributor role to users who can access the project, but not update the code files.
    • Assign the Developer role to trusted users who can access code files, build, and deploy the application.
  • If you use the Application Extension template to create your project, VB Studio automatically creates a Development environment that points to the Oracle Cloud Application's development instance you specify. The build jobs, created by default, package and deploy the app extension's artifact to the Oracle Cloud Application's development instance.

    If you want to use VB Studio to also deploy to your Oracle Cloud Application's test or production instance, you'll need to manually create a VB Studio environment for each of those instances.

  • To add Oracle Cloud Application's test and production instances from other identity domains, get either the identity domain's details, or a user's credentials or personal access token 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 master branch for development. This documentation assumes that you'll continue to use master as the development branch and create separate branches for test and production.
  • You should set restrictions on the test and production branches to control who can merge to it.
  • Build jobs in VB Studio run on Build VMs. Build VM templates define the operating system and software installed on Build VMs. By default, a System Default OL7 for Visual Builder Build VM template is available with the necessary software to build app extensions, but no Build VMs are available.

    Before you run builds of the default build jobs, you should add Build VMs that use the default System Default OL7 for Visual Builder Build VM template.

  • To deploy to your Oracle Cloud Application's test or production instance, create separate jobs to package the artifact and to deploy it to the Oracle Cloud Applications instance. Then, create a pipeline to run the packaging and deploy jobs in sequence.
  • Set restrictions on who can edit or run production jobs.
  • Before you run production build jobs or pipelines, make sure that all code changes have been pushed to the production branch and there are no open merge requests.

Get Access to Oracle Cloud Applications Instances

To deploy your app extension to Oracle Cloud Applications development, test, and production instances, you'll need credentials or personal access tokens of users who can access them. Contact the Oracle Cloud Applications administrator and get the details of users.

You should also make sure that each Oracle Cloud Applications instance is properly configured and running.

If an instance isn't available or not configured, then follow the Oracle Cloud Applications documentation to create and configure it.

Create the VB Studio Instance and Set Up the OCI Connection

  1. (Optional) Create the VB Studio Instance if it isn't provisioned for you in the same Oracle Cloud account and identity domain as the Oracle Cloud Applications development instance.
  2. Set Up the OCI Account.

Set Up VB Studio Users

To allow access to VB Studio, you must add your Oracle Cloud Applications users to Oracle Identity Cloud Service (IDCS) and assign them VB Studio IDCS roles. Instead of adding users manually, you can synchronize Oracle Cloud Applications users with IDCS and then grant them correct roles.

When a new user is added in Oracle Cloud Applications, the user is automatically synchronized with IDCS. Note that it can take up to an hour for the user to be synced with IDCS.

Here's a summary of how to synchronize Oracle Cloud Applications users with IDCS:

To perform this action: See this:
1. Set up single sign-on and synchronize Oracle Cloud Applications users with IDCS Configure Single Sign-On (SSO) and Synchronize Users
2. Set Oracle Cloud Applications as the default identity provider Set Oracle Cloud Applications as the Identity Cloud Service Provider
3. Assign VB Studio IDCS roles to Oracle Cloud Applications users Assign VB Studio Roles to Oracle Cloud Applications Users

To perform the above steps, you must be assigned the Identity domain administrator and the Security administrator role in IDCS, and the security admin privileges in your Oracle Cloud Applications environment.

Configure Single Sign-On (SSO) and Synchronize Users

To set up SSO and synchronize users, follow these steps:

  1. In Oracle Cloud Applications, assign the FND_ADMINISTER_SANDBOX_PRIV privilege, or one of these Oracle Cloud Applications roles to users who want to access VB Studio:

    • Application Administrator (ORA_FND_APPLICATION_ADMINISTRATOR_JOB)
    • Application Developer (ORA_FND_APPLICATION_DEVELOPER_JOB)
    • Sales Administrator (ORA_ZBS_SALES_ADMINISTRATOR_JOB)
    • Customer Relationship Management Application Administrator (ORA_ZCA_CUSTOMER_RELATIONSHIP_MANAGEMENT_APPLICATION_ADMINISTRATOR_JOB )

    Here's an example of a user assigned the Application Developer role:

  2. Enable SSO for Oracle Cloud Applications users.

    To do that, set IDCS as the identity provider and Oracle Cloud Applications as the service provider, as described in Configure Single Sign-On of Oracle Identity Cloud Service - Application Catalog.

    After the successful configuration, open the IDCS Console. You should see a SuccessfulConfigured message under Single Sign-On.

    Here's an example:

  3. Enable synchronization between Oracle Cloud Applications and IDCS.

    To do that, establish a connection from IDCS to your Oracle Cloud Applications environment, as described in Configure Provisioning and Synchronization of Oracle Identity Cloud Service - Application Catalog.

    To verify Oracle Cloud Applications users in IDCS, open the IDCS console, click Navigation Drawer Navigation Drawer and select Users.

    Here's an example of the IDCS Users page with synchronized Oracle Cloud Applications users:

    For each Oracle Cloud Applications role, IDCS automatically creates a group representing users assigned to that role. For example, the Application Administrator IDCS group represents users who are assigned the Application Administrator role in Oracle Cloud Applications.

    Here's an example of the Application Administrator group in IDCS:

Set Oracle Cloud Applications as the Identity Cloud Service Provider

When you set up single sign-on, by default, both IDCS and Oracle Cloud Applications are set as identity providers. To avoid any conflict, remove IDCS as the identity provider. To find out how to do that, see Remove Identity Provider Policies in Administering Oracle Identity Cloud Service.

After removing IDCS, you should see Oracle Cloud Applications as the only identity provider on the Identity Providers page.

Here's an example:

Assign VB Studio Roles to Oracle Cloud Applications Users

After Oracle Cloud Applications users are synchronized and are available in IDCS, open the Oracle Cloud console and assign the VB Studio IDCS roles to users or groups. To assign roles, you must be assigned the IDCS Identity domain administrator role or the Security administrator role.

  1. Sign in to Oracle Cloud and open the Oracle Cloud Console page.
  2. In the upper-left corner, click Navigation Menu the Menu icon.
  3. Under Governance and Administration, select Identity, and then select Federation.
  4. On the Federation page, to assign a role to a user, in the Users tab under Resources, click the user's name.
    To assign a role to a group, in the Groups tab under Resources, click the group's name.
  5. Click Manage Roles.
  6. On the Manage Service Roles page, search for the service with Developer Cloud Service description, click the Actions icon (three vertical dots) and select Manage Instance Access.
  7. On the Manage Access page, in the Instance Role column, select the role.
    Assign the DEVELOPER_ADMINISTRATOR role to Oracle Cloud Applications administrators or to the APPLICATION ADMINISTRATOR group.

    Assign the DEVELOPER_USER role to non-admin users or groups, such as the APPLICATION DEVELOPER group.

    To find more about VB Studio IDCS roles, see IDCS Roles.

  8. Click Update Instance Settings.
  9. Click Apply Role Settings.

To learn more about assigning and managing roles for a group, see Managing Oracle Identity Cloud Service Roles for Groups; for users, see Managing Oracle Identity Cloud Service Roles for Users.

Create a Project for Application Extensions

A project gathers all the resources you need for developing software. To ensure an optimal environment for your employees creating application extensions, be sure to base your project on the Application Extension project template.

  1. Sign in to VB Studio. See Access VB Studio from the Oracle Cloud Home Page.
  2. On the Organization page, click + Create Project.
  3. On the Project Details page, 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 Application Extension template, then click Next.
  8. On the Application Extension Project Properties page:
    1. In Oracle Cloud Applications Development Instance, select the base application's development instance.
      The list shows Oracle Cloud Applications instances defined in the same identity domain as the VB Studio.
    2. (Optional) In Git Repository Name, update the project's Git repository's default name, if required.
    3. In Base Application, select the Oracle Cloud Application you want to extend in this project.
    4. To create a private workspace along with the project, click the Create Workspace toggle button.

      A workspace contains all the artifacts that you need to develop app extensions and 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?

      In Workspace Name, enter a unique name.

      If you don't want to use the Git repository's master branch as the workspace's working branch, in Working Branch Name, enter the new branch's name. When the project is provisioned, VB Studio creates a copy of the master branch, renames it your specified name and uses it as the workspace's working branch.

    5. In Wiki Markup, select the project's wiki markup language.
      Project's users use the markup language to format wiki pages and comments. If you're not sure which markup language to choose, use the default markup language. You can change the markup language later from the Project Administration page. See Change a Project’s Wiki Markup Language.
  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 environments; and Git repositories. Review the activities feed and the Environments box for any errors.

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

  • A Git repository, which contains the app extension'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:

  • A Development environment pointing to the development instance where your base Oracle Cloud Application is running.

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

  • Build jobs that package and deploy the app extension's artifact to Oracle Cloud Application's development instance.

    By default, Application-Extension-Package and Application-Extension-Deploy jobs are created for you. The Application-Extension-Package job generates the app extension's artifact file. The Application-Extension-Deploy job deploys the app extension's artifact file to Oracle Cloud Application's development instance.

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

    By default, the packaging job uses the Git repository's master branch as the source and triggers a build whenever a commit is pushed to it. To enable a user to run a build, you must first allocate Build VMs and make the appropriate deployment configurations. See Set Up the Project for Development. Without the appropriate configuration or VMs, the build will fail.

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

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

  • (Optional) A private workspace to edit the app extension in the VB Studio Designer.

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

Set Up the Project for Development

Before your team members can use the project for developing app extensions, you need to make a few configuration settings in the project.

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

To perform this action: See this:
1. Add Build VMs.

VMs are needed to run build jobs for the project.

Add Build VMs
2. (Optional) Configure the packaging job.

By default, the packaging job uses the app extension's version defined in the visual-application.json file. If you want to specify another version when a build runs, configure the job.

Configure the Packaging Job
3. 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
4. (Optional) Protect the Git repository's master branch.

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 master branch, set restrictions on it to allow branch merges only after they are approved.

Set Merge Restrictions on the master Branch

Add Build VMs

Builds in VB Studio run on Build VMs running in a Virtual Cloud Network (VCN). A Build VM Template defines the operating system and software installed on Build VMs.

To find out more about Build VMs and Build VM templates, see What Are Build VMs and Build VM Templates?

You can run Build VMs in the VB Studio's default VCN or in your VCN. See Use VB Studio's Default VCN to learn about VB Studio's default VCN. To run builds in your own VCN, see Run Build VMs in Your VCN.

To run builds of your app extensions, you should add Build VMs that use the default System Default OL7 for Visual Builder VM template. The System Default OL7 for Visual Builder VM template includes Node.js 10, which is the minimum version required for packaging app extensions.

  1. In the navigation menu, click Organization Organization.
  2. Click the Virtual Machines tab.
  3. Click + Create VM.
  4. In the Add Build VM dialog box, in Quantity, specify the number of VMs you want to allocate.

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

    If you're not sure about the number of VMs you'll need, start with one Build VM and then add more as required. Note that the more VMs 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 Virtual Machines page to automatically shut down inactive VMs. You can always return to the Virtual Machines tab to remove or add VMs, based on your actual usage.

  5. In VM Template, select System Default OL7 for Visual Builder.
  6. In Region, Shape, and VCN Selection specify the VM's region, shape, and Virtual Cloud Network (VCN).
    • A region is a localized geographic area where the data centers are located. Remember, a Build VM is a VM on OCI Compute or OCI Compute Classic. 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.

  7. Click Add.

Configure the Packaging Job

The packaging job generates the app extension's build artifact from the source files in the Git repository's master branch.

The app extension's version is defined in the visual-application.json file. If you want the build artifact to use the same version, don't make any changes to the packaging job's default configuration.

If you want to specify another version when a build runs without modifying the visual-application.json file, follow these steps:

  1. In the navigation menu, click Builds Builds.
  2. In the Jobs tab, click the packaging job.
  3. Click Configure.
  4. Click Configure the Tools icon.
  5. Click the Steps tab.
  6. Specify the new version in Extension Version.
    When a build runs, VB Studio overwrites the app extension's version defined in the visual-application.json file with the new version.
  7. Click Save.

Configure the Deployment Job

The deployment job deploys the app extension's build artifact to your Oracle Cloud Application's development instance. In the job, specify the credentials required to connect and deploy build artifact to your Oracle Cloud Application's development instance.

  1. In the navigation menu, click Builds Builds.
  2. In the Jobs tab, click the deployment job.
  3. Click Configure.
  4. Click Configure the Tools icon.
  5. Click the Steps tab.
  6. In the Oracle Deployment section, under Authorization, select one of these options:
    • To authenticate using a username and a password, select Use Credentials. 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 development instance.
    • To authenticate using an Oracle Cloud Applications user's personal access token, select Use Access Token. Click Set Access Token, upload the token file, and click OK.

      Note that personal access tokens have a short life. Before uploading, ensure that the access token isn't expired. If you need to generate a personal access token, see Get an Oracle Cloud Applications User's Personal Access Token.

  7. Click Save.

Get an Oracle Cloud Applications User's Personal Access Token

To get a user's personal access token, sign in to the Oracle Identity Cloud Service console with the user's credentials. To learn more, see Generate Personal Access Tokens.

Personal access tokens have a short life. Generate them only when you need them.

Run the Pipeline

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 Builds.
  2. Click the Pipelines tab.
  3. For the pipeline you want to run, click Build Build.

To monitor the pipeline, click the pipeline's name on the Builds page.

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 Application Extensions

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

  1. In the navigation menu, click Environments Environments.
  2. Select the Oracle Cloud Application's environment.
  3. Click the Deployments tab.
  4. Click the Application Extensions toggle button.
  5. If the Oracle Cloud Application's a personal access token has expired or its access credentials have changed, provide the token or the credentials again.
  6. Expand the base Oracle Cloud Application to view its deployed app extensions.
    For each app extension, the page displays its ID, name, version, and status.

    Here's an example:

    In the packaging build step, if you didn't specify a version to overwrite the app extension's version defined in /visual-application.json, the Version column appends the build's timestamp to the version number and displays it in the <version_number>.<build_run_timestamp> format.

To open the Oracle Cloud Application with the deployed app extension, copy the application's base URL and paste it in a web browser.

Delete an App Extension

You can delete an app extension that's deployed to your current identity domain's Oracle Cloud Applications manually from the Deployments tab of its environment, or configure a build job to delete it.

To delete an app extension that's deployed to Oracle Cloud Applications of another identity domain, configure a build job and run it. You can't delete it manually.
Delete an App Extension Manually
  1. In the navigation menu, click Environments Environments.
  2. Select the environment where the app extension is deployed.
  3. Click the Deployments tab.
  4. Expand the base application's name.
  5. For the app extension to delete, click Actions Hamburger icon and select Delete.
  6. In the confirmation dialog box, click Delete.
Configure a Job to Delete an App Extension
To delete an app extension through a build job, you'll need either a personal access token or access credentials of a user who can access the Oracle Cloud Application's instance where the app 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 the System Default OL7 for Visual Builder Build VM template.
  6. Click Create.
  7. On the Job Configuration page, click Configure the Tools icon.
  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 Authorization, select one of these options.
    • To authenticate using a username and a password, select Use Credentials. In Username and Password, enter the user's credentials who can connect to the Oracle Cloud Applications instance.
    • To authenticate using the user's personal access token, select Use Access Token. Click Set Access Token, upload the token file, and click OK.

      Note that personal access tokens have a short life. Before uploading, ensure that the access token isn't expired. If you need to generate a personal access token, see Get a Visual Builder User's Personal Access Token.

  12. In Base Application, Name, and Version, enter the app extension's base application, name, and version.
    You can find the details on the Deployments tab of the environment where the app extension is deployed.

    Example:

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

Set Merge Restrictions on the master Branch

By default, the master 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.

  1. In the navigation menu, click Project Administration Gear.
  2. Click Branches.
  3. In Repository and Branches, select the Git repository and the master 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.

Learn More About VB Studio

Now that you've set up VB Studio, created an app extension project and added Oracle Cloud Applications users to it, it's time to learn more about the other features that VB Studio offers.

  • Get Started in Managing Your Development Process with 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.

  • How Do I Use Visual Builder Studio to Extend Oracle Cloud Applications in Extending Oracle Cloud Applications with Visual Builder Studio describes how to create, edit and publish app extensions.

Add Users to the Project

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

Action How To

Add a user to the project

  1. In the navigation menu, click Project Home Project Home.
  2. Click the Team tab.
  3. Click + Add Member.
  4. In the Add Member dialog box, specify the new member’s project membership in Membership.

    To learn about different types of memberships, see What Are the VB Studio Project Memberships?

  5. In Username, enter or select the user from the list.
  6. Click Add.

Add multiple users to the project

  1. In the navigation menu, click Project Home Project Home.
  2. Click the Team tab.
  3. Click + Add Member.
  4. In the Add Member dialog box, select the Multiple Users check box.
  5. In Username, enter or select the user from the list, and click Add User the add user icon.

    The selected user is added to the Username List text box. If you know the usernames of users to add, enter them manually separated by a space, a comma, a semicolon, or a new line.

  6. Click Add.
Add users from another project
  1. Open the project that has users already added.
  2. In the navigation menu, click Project Home Project Home.
  3. Click the Team tab.
  4. Click Export the export members icon.
  5. In the Members List Export dialog box, copy the names of project members.
  6. Click OK or Close the close icon to close the dialog box.
  7. Open the project where you want to add the copied users.
  8. In the navigation menu, click Project Home Project Home.
  9. Click the Team tab.
  10. Click + Add Member.
  11. In the Add Member dialog box, select the Multiple Users check box.
  12. In Username List text box, paste the copied names of project members.
  13. Click Add.

Change a user’s project membership

To change a user’s membership, mouse over the user's name, click Change Membership the Change Membership icon, and then select the membership.

Set Up the Project For Testing

After your development and QA cycles are complete, you may want to configure the project to build and deploy app extensions to the Oracle Cloud Application's test instance, or the instance you use to test the application before deploying it to the production instance.

Before you proceed, contact the Oracle Cloud Applications test instance administrator and make sure that the test instance is properly configured and running.

Here's a summary of how to set up the VB Studio project for test or other non-production environments.

To perform this action: See this:
1. In the VB Studio project, create an environment for the Oracle Cloud Application's test instance. Add an Oracle Cloud Application's Instance to an Environment
2. Create a Git repository test branch from the master branch. Create a Test Branch
3. Create test packaging and deployment build jobs, and then set up a pipeline.

You may also want to restrict who can see or edit the test build jobs' configuration, or run its build.

Create and Configure Build Jobs
4. Migrate your Oracle Cloud Application's customizations to the test instance. Migrate Your Oracle Cloud Application’s Customizations

Add an Oracle Cloud Application's Instance to an Environment

If you want to set up things so that app extensions are deployed to the Oracle Cloud Application's test or any other instance, you must create separate VB Studio environments and add the correct instances to it. You can only add one Oracle Cloud Applications instance to an environment.

Here's an example of environments for development, test, stage, and pre-production instances:

Your Oracle Cloud Applications instance can reside either in your current identity domain or in another identity domain. If your test instance resides in another identity domain, to add it to an environment, you'll need any of these:

  • A user's personal access token who can access the instance
  • Base Oracle Cloud Application's URL and a user's credentials who can access the instance

When you add an Oracle Cloud Applications 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 Oracle Cloud Applications 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 the Oracle Cloud Applications instance is added to an environment.

If the newly added instance stays in the Unknown status for some time, it typically indicates that the IDCS Application provisioning may have failed. VB Studio added the Oracle Cloud Applications instance but can't access it. In such a case, delete the Oracle Cloud Applications instance from the environment and add it again.

Add a Connection to Oracle Cloud Applications of Your Current Identity Domain
  1. In the navigation menu, click Environments Environments.
  2. Select an existing environment or create one.
    To create an environment, click Create (or Create Environment if the page is empty). In Environment Name and Description, enter a unique name and description, and click Create.
  3. In the Service Instances tab, click Add.
  4. In the Add Service Instances dialog box, click the Oracle Cloud Applications toggle button.
  5. Select the Identity Domain option.
  6. Select the check box for the Oracle Cloud Applications instance you want to add and click Add.
    You can add only a single Oracle Cloud Applications instance to an environment.
Add a Connection to Oracle Cloud Applications of Another Identity Domain
  1. In the navigation menu, click Environments Environments.
  2. Select an existing environment or create one.
    To create an environment, click Create (or Create Environment if the page is empty). In Environment Name and Description, enter a unique name and description, and click Create.
  3. In the Service Instances tab, click Add.
  4. In the Add Service Instances dialog box, click Oracle Cloud Applications toggle button.
If you have these details of the target Oracle Cloud Applications instance: Follow these steps:
Personal access token of a user who can access the instance

To generate the personal access token, see Get an Oracle Cloud Applications User's Personal Access Token.

  1. Select the Personal Access Token option.
  2. Drag and drop the token file to the Drag and Drop Token File area, or copy the token's text and paste it in paste token here.
  3. Click Add.
Base Oracle Cloud Application's URL and credentials of a user who can access the instance
  1. Select the Application Credentials option.
  2. In Base URL, enter the base Oracle Cloud Application's URL.
  3. In Instance Name, if required, update the instance's display name. The name will be displayed in the Service Instances tab.
  4. In Username and Password, enter the credentials of a user who can access the Oracle Cloud Applications instance.
  5. Click Add.

Create a Test Branch

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

To use an existing branch for Test, create a merge request with master as the review branch and the test branch as the target branch. After approvals from reviewers, merge the review branch into the target branch.

To create a branch from master, follow these steps:

  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 master as the base branch.
  6. Click Create.
After creating the test 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 Build Jobs

To deploy app extensions to your Oracle Cloud Application's test or any other instance, you'll need to set up separate packaging and deployment jobs. You should also set restrictions on who can see or edit the job's configuration, or run its build.

Here's an example of jobs that generate and package the app extension's artifact, and deploy it to the development and test instances:

Here's an example of development and test pipelines:

Before you create and configure the jobs, you'll need these:

  • Access credentials or the personal access token of an Oracle Cloud Applications user who can connect and deploy to the test instance.
  • Artifact's file name

    If you changed the default artifact's file name in the development packaging job, get the new name and its path.

  • Application's version

    If you configured the development packaging job to overwrite the application's version defined in visual-application.json, get the new version.

Create a Packaging Build Job

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

  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 the Tools icon.
  8. Click the Git tab.
  9. From Add Git, select Git.
  10. In Repository, select the Git repository. In Branch or Tag, select the repository's test branch (or tag).
  11. Click the Steps tab.
  12. From Add Step, select Application Extension, and then select Package.
  13. (Optional) If you want to change the artifact file's name, in Artifact, enter the new name. By default, it is extension.vx.
  14. (Optional) If you want to overwrite the app extension's default version defined in the visual-application.json file, in Extension Version, specify the new version.
  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, *.vx.
  18. 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.
  19. Click Save.
Create a Deployment Build Job

The deployment job deploys the app extension's artifact that was generated in the packaging job to the Oracle Cloud Application's instance. Before you create the job, get the access credentials or the personal access token of an IDCS user who can also access the Oracle Cloud Application's 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 the Tools icon.
  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 app extension's artifact.
  11. In Which Build, select the build that generated the artifact.
  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 target instance.
  16. In Authorization, select one of these options.
    • To authenticate using an IDCS user's credentials who is also an Oracle Cloud Applications user, select Use Credentials. In Username and Password, enter the credentials.
    • To authenticate using an Oracle Cloud Applications user's personal access token, select Use Access Token. Click Set Access Token, upload the token file and click OK.

      Note that personal access tokens have a short life. Before uploading, ensure that the access token hasn't expired. To generate a personal access token, see Get an Oracle Cloud Applications User's Personal Access Token.

  17. In Build Artifact, enter the same artifact name that you used in the packaging build step.
  18. Click Save.
Configure a 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 Gear.
  2. Click Builds.
  3. Click the Job Protection tab.
  4. From the jobs list, select the job.
  5. Select the Private option.
  6. In Authorized Users, add yourself.
    To add other users, select their names.
  7. Click Save.

A private job shows a Lock 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.

A non-authorized user who tries to view a private job will see this message: This job is private. You need permission from your project owner to view this job.

Create and Configure a 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 design page, from the Jobs list, drag-and-drop the packaging job and the deployment job to the designer area.

    Example:

    Pipeline jobs
  7. Mouse over the Start node's Gray circle Gray circle on the right of the Start node handle. The cursor icon changes to the + cursor icon. Drag the cursor from the Gray circle Gray circle on the right of the Start node handle to the packaging job's White circle White circle on the left side of the job node handle. An arrow line appears.

    Example:

    Setting the start job in a pipeline
  8. Mouse-over the packaging job's Blue circle Blue circle on the right side of the job node handle and drag-and-drop the arrow head over the deployment job's White circle White circle on the left side of the job node handle.

    Example:

    Setting a job's dependency in a pipeline
  9. Click Save.
Run the Pipeline

To run the packaging job and the deployment job in sequence, run the pipeline.

  1. In the navigation menu, click Builds Builds.
  2. Click the Pipelines tab.
  3. For the pipeline you want to run, click Build Build.

After 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 Latest Console.

Delete an App Extension

You can delete an app extension that's deployed to your current identity domain's Oracle Cloud Applications manually from the Deployments tab of its environment, or configure a build job to delete it.

To delete an app extension that's deployed to Oracle Cloud Applications of another identity domain, configure a build job and run it. You can't delete it manually.
Delete an App Extension Manually
  1. In the navigation menu, click Environments Environments.
  2. Select the environment where the app extension is deployed.
  3. Click the Deployments tab.
  4. Expand the base application's name.
  5. For the app extension to delete, click Actions Hamburger icon and select Delete.
  6. In the confirmation dialog box, click Delete.
Configure a Job to Delete an App Extension
To delete an app extension through a build job, you'll need either a personal access token or access credentials of a user who can access the Oracle Cloud Application's instance where the app 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 the System Default OL7 for Visual Builder Build VM template.
  6. Click Create.
  7. On the Job Configuration page, click Configure the Tools icon.
  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 Authorization, select one of these options.
    • To authenticate using a username and a password, select Use Credentials. In Username and Password, enter the user's credentials who can connect to the Oracle Cloud Applications instance.
    • To authenticate using the user's personal access token, select Use Access Token. Click Set Access Token, upload the token file, and click OK.

      Note that personal access tokens have a short life. Before uploading, ensure that the access token isn't expired. If you need to generate a personal access token, see Get a Visual Builder User's Personal Access Token.

  12. In Base Application, Name, and Version, enter the app extension's base application, name, and version.
    You can find the details on the Deployments tab of the environment where the app extension is deployed.

    Example:

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

Migrate Your Oracle Cloud Application’s Customizations

When you’re ready to deploy your app extension to the Oracle Cloud Application's test instance, you should also migrate your Oracle Cloud Application's customization data from your source development instance to the target test instance.

You can migrate the customization manually from the source Oracle Cloud Applications instance’s Customization Migration page to the target instance, or configure Customization Set Migration (CSM) builds jobs in VB Studio to automate the migration process.

To migrate CSM data, VB Studio provides these CSM build steps in jobs:

Build Step Description
Export Data Generate the migration set from the source Oracle Cloud Applications instance and gets the customization set ID.
Import Data Import the generated migration set from source Oracle Cloud Applications instance to the target Oracle Cloud Applications instance.
Apply Migration Apply the imported migration set to the target instance.
Abort Migration Delete the generated migration set.

While configuring CSM build jobs, add only one CSM build step in each job and run them in this order:

  1. Run the CSM export job.
  2. Run the CSM import job only if the export job is successful.
  3. If the CSM import job fails, run the CSM abort migration job.
  4. If the CSM import is successful, manually test the changes on the target Oracle Cloud Applications instance.
  5. Run the CSM apply migration job after your tests are successful.
Before You Migrate Customization

Here are some things you need to do before you configure and run CSM build jobs to migrate customization from the source instance to the target instance:

  • Ensure that your source Oracle Cloud Applications instance’s sandboxes are published.
  • On your source Oracle Cloud Applications instance's Migration page, ensure that the Target Instance is set to point to the target Oracle Cloud Applications instance's URL.

    Here's an example of an Oracle Cloud Applications migration page:

  • Get the access credentials or personal access tokens of users who can access the source and the target Oracle Cloud Applications instances. You'll need them to configure CSM build jobs.
  • Run the CSM export and import build jobs after you've deployed the app extension to the target Oracle Cloud Applications instance.
Configure a Job to Export Customization

Configure a job to generate the outbound migration set from the source Oracle Cloud Applications 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 the Tools icon.
  8. Click the Steps tab.
  9. From Add Step, select Customization Set Migration, and then select Export Data.
  10. In Source Instance, select the environment that points to the Oracle Cloud Application's source instance.
  11. In ID Parameter Name, enter a name for the parameter that defines a unique ID for the customization set. By default, it's set to CUSTOMIZATION_SET_ID.
    When a build runs, the job generates a unique customization set ID, assigns it to CUSTOMIZATION_SET_ID, and passes it to downstream jobs when the job runs in a pipeline.
  12. In Name and Description, enter a name and description for the customization set.
    If you're not sure about the name and description at the time of job's configuration, you can use build parameters and enter the details when you run the job's build. Here's an example:
    Build job with parameters

    Remember to define the build parameters in the Parameters tab.

    Build parameters
  13. In Authorization, select one of these options.
    • To authenticate using an IDCS user's credentials who is also an Oracle Cloud Applications user, select Use Credentials. In Username and Password, enter the credentials.
    • To authenticate using an Oracle Cloud Applications user's personal access token, select Use Access Token. Click Set Access Token, upload the token file and click OK.

      Note that personal access tokens have a short life. Before uploading, ensure that the access token hasn't expired. To generate a personal access token, see Get an Oracle Cloud Applications User's Personal Access Token.

  14. Click Save.
Configure a Job to Import Customization

Configure a job to import the migration set to the target Oracle Cloud Applications 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 the Tools icon.
  8. Click the Steps tab.
  9. From Add Step, select Customization Set Migration, and then select Import Data.
  10. In Target Instance, select the environment that points to the Oracle Cloud Application's target instance.
  11. In ID Parameter Name, if you changed the default parameter name in the CSM export job, then enter the same parameter name in the $<PARAMETER_NAME> or ${<PARAMETER_NAME>} format. By default, it's set to ${CUSTOMIZATION_SET_ID}.
    When a build of this job runs, the job gets the unique customization set ID generated by the CSM export job. If no ID is found, it fails.
  12. In Authorization, select one of these options.
    • To authenticate using an IDCS user's credentials who is also an Oracle Cloud Applications user, select Use Credentials. In Username and Password, enter the credentials.
    • To authenticate using an Oracle Cloud Applications user's personal access token, select Use Access Token. Click Set Access Token, upload the token file and click OK.

      Note that personal access tokens have a short life. Before uploading, ensure that the access token hasn't expired. To generate a personal access token, see Get an Oracle Cloud Applications User's Personal Access Token.

  13. Click Save.
Configure a Job to Abort Customization Migration

If for some reason your CSM import job fails, you should abort the migration process. To do that, configure an abort migration job.

  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 the Tools icon.
  8. Click the Steps tab.
  9. From Add Step, select Customization Set Migration, and then select Abort Migration.
  10. In Target Instance, select the environment that points to the Oracle Cloud Application's target instance.
  11. In ID Parameter Name, if you changed the default parameter name in the CSM export job, then enter the same parameter name in the $<PARAMETER_NAME> or ${<PARAMETER_NAME>} format. By default, it's set to ${CUSTOMIZATION_SET_ID}.
    When a build of this job runs, the job gets the unique customization set ID generated by the CSM export job. If no ID is found, it fails.
  12. In Authorization, select one of these options.
    • To authenticate using an IDCS user's credentials who is also an Oracle Cloud Applications user, select Use Credentials. In Username and Password, enter the credentials.
    • To authenticate using an Oracle Cloud Applications user's personal access token, select Use Access Token. Click Set Access Token, upload the token file and click OK.

      Note that personal access tokens have a short life. Before uploading, ensure that the access token hasn't expired. To generate a personal access token, see Get an Oracle Cloud Applications User's Personal Access Token.

  13. Click Save.
Configure a Job to Apply and Save the Customization Migration

After your import job is successful and you have manually tested the changes on the target Oracle Cloud Applications instance, you should save the migration set. To do that, configure an apply migration job.

  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 the Tools icon.
  8. Click the Steps tab.
  9. From Add Step, select Customization Set Migration, and then select Apply Migration.
  10. In Target Instance, select the environment that points to the Oracle Cloud Application's target instance.
  11. In ID Parameter Name, if you changed the default parameter name in the CSM export job, then enter the same parameter name in the $<PARAMETER_NAME> or ${<PARAMETER_NAME>} format. By default, it's set to ${CUSTOMIZATION_SET_ID}.
    When a build of this job runs, the job gets the unique customization set ID generated by the CSM export job. If no ID is found, it fails.
  12. In Authorization, select one of these options.
    • To authenticate using an IDCS user's credentials who is also an Oracle Cloud Applications user, select Use Credentials. In Username and Password, enter the credentials.
    • To authenticate using an Oracle Cloud Applications user's personal access token, select Use Access Token. Click Set Access Token, upload the token file and click OK.

      Note that personal access tokens have a short life. Before uploading, ensure that the access token hasn't expired. To generate a personal access token, see Get an Oracle Cloud Applications User's Personal Access Token.

  13. Click Save.
Create and Configure the CSM Pipeline

To ensure the CSM jobs runs automatically in the correct order, create a pipeline and set the dependency.

When you define the pipeline, make sure that the CSM import job runs after the CSM export job is successful. If the CSM import job fails, run the CSM abort migration job. Don't add the CSM apply migration job to the pipeline. You should run it manually after verifying your changes on the target Oracle Cloud Applications instance.
  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 design page, from the Jobs list, drag-and-drop the CSM export, import, and abort jobs to the designer area.

    Here's an example:

    CSM Jobs in the Pipeline designer
  7. Mouse over the Start node's Gray circle Gray circle on the right of the Start node handle. The cursor icon changes to the + cursor icon. Drag the cursor from the Gray circle Gray circle on the right of the Start node handle to the export CSM job's White circle White circle on the left side of the job node handle. An arrow line appears.
  8. Mouse-over the export CSM job's Blue circle Blue circle on the right side of the job node handle and drag-and-drop the arrow head over the import CSM job's White circle White circle on the left side of the job node handle.
  9. Mouse-over the import CSM job's Blue circle Blue circle on the right side of the job node handle and drag-and-drop the arrow head over the abort CSM job's White circle White circle on the left side of the job node handle.
    Your pipeline diagram should look like this example:
    Dependencies in the CSM pipeline's diagram
  10. Click to select the line that that goes from the import CSM job's Blue circle Blue circle on the right side of the job node to the abort CSM job's White circle White circle on the left side of the job node handle.

    Here's an example:

    Dependency from the import CSM job to the abort CSM job
  11. Click Configure Selected LinkGear icon.
  12. In the Pipeline flow config editor dialog box, from Result Condition, select Failed and click Apply.
  13. Click Save.
Run the Pipeline

To run the CSM jobs in sequence, run the pipeline.

  1. In the navigation menu, click Builds Builds.
  2. Click the Pipelines tab.
  3. For the pipeline you want to run, click Build Build.
  4. If you've defined build parameters in the CSM jobs, enter the required details in the Build Pipeline dialog box, and click Build Now.

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

Set Up the Project to Deploy to Production

After your development and test cycles are complete, you may want to configure the project to build and deploy app extension to the Oracle Cloud Application's production instance.

Before you proceed, contact the Oracle Cloud Applications production instance administrator and make sure that the production instance is properly configured and running.

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 Oracle Cloud Application's production instance. Add the Oracle Cloud Application's Production Instance to an Environment
2. Create a production branch from the test branch. Use this branch to push your application to production. Create a Production Branch
3. Create the packaging and deployment build jobs, and set up the pipeline. Create and Configure Build Jobs
4. (Optional) Restrict users who can edit the production jobs or run their builds. Configure a Job's Privacy Setting
5. Migrate your Oracle Cloud Application's customization data to the production instance Migrate Your Oracle Cloud Application’s Customization

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 Oracle Cloud Application's Production Instance to an Environment

To deploy an app extension to the Oracle Cloud Application's production instance, you must create a VB Studio environment and add the correct instance to it. You can only add one Oracle Cloud Applications instance to an environment.

The Oracle Cloud Applications production instance usually resides in another identity domain. To add an Oracle Cloud Applications production instance that resides in another identity domain to an environment, you'll need any of these:

  • A user's personal access token who can access the instance
  • Base Oracle Cloud Application's URL and a user's credentials who can access the instance

When you add an Oracle Cloud Applications 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 Oracle Cloud Applications 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 the Oracle Cloud Applications instance is added to an environment.

If the newly added instance stays in the Unknown status for some time, it typically indicates that the IDCS Application provisioning may have failed. VB Studio added the Oracle Cloud Applications instance but can't access it. In such a case, delete the Oracle Cloud Applications instance from the environment and add it again.

Add a Connection to Oracle Cloud Applications of Another Identity Domain
  1. In the navigation menu, click Environments Environments.
  2. Select an existing environment or create one.
    To create an environment, click Create (or Create Environment if the page is empty). In Environment Name and Description, enter a unique name and description, and click Create.
  3. In the Service Instances tab, click Add.
  4. In the Add Service Instances dialog box, click Oracle Cloud Applications toggle button.
If you have these details of the target Oracle Cloud Applications instance: Follow these steps:
Personal access token of a user who can access the instance

To generate the personal access token, see Get an Oracle Cloud Applications User's Personal Access Token.

  1. Select the Personal Access Token option.
  2. Drag and drop the token file to the Drag and Drop Token File area, or copy the token's text and paste it in paste token here.
  3. Click Add.
Base Oracle Cloud Application's URL and credentials of a user who can access the instance
  1. Select the Application Credentials option.
  2. In Base URL, enter the base Oracle Cloud Application's URL.
  3. In Instance Name, if required, update the instance's display name. The name will be displayed in the Service Instances tab.
  4. In Username and Password, enter the credentials of a user who can access the Oracle Cloud Applications instance.
  5. 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.

If you're using an existing branch for Production, you should create a merge request with the test branch as the review branch and the production branch as the target branch. After approvals from reviewers, merge the review branch into the target branch.

To create a production branch from the test branch, follow these steps:

  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 test 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 Build Jobs

You need to set up some packaging and deployment jobs before you can deploy app extensions to your Oracle Cloud Application's production instance. This topic explains how to do that.

Before you create and configure the jobs, you'll need these:

  • Access credentials or the personal access token of an Oracle Cloud Applications user who can connect and deploy to the production instance.
  • Artifact's file name

    If you changed the default artifact's name in the test packaging job, get the new name and its path.

  • Application's version

    If you configured the development packaging job to overwrite the application's version defined in visual-application.json, get the new version.

Create a Production Packaging Build Job

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

  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 the Tools icon.
  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. (Optional) If you want to change the artifact file's name, in Artifact, enter the new name. By default, it is extension.vx.
  14. (Optional) If you want to overwrite the app extension's default version defined in the visual-application.json file, in Extension Version, specify the new version.
  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, *.vx.
  18. 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.
  19. Click Save.
Create a Production Deployment Build Job

The deployment job deploys the app extension's artifact that was generated in the packaging job to the Oracle Cloud Application's production instance. Before you create the job, get the access credentials or the personal access token of an IDCS user who can also access the Oracle Cloud Application's production 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 the Tools icon.
  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 app extension's artifact.
  11. In Which Build, select the build that generated the artifact.
  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 Authorization, select one of these options.
    • To authenticate using an IDCS user's credentials who is also an Oracle Cloud Applications user, select Use Credentials. In Username and Password, enter the credentials.
    • To authenticate using an Oracle Cloud Applications user's personal access token, select Use Access Token. Click Set Access Token, upload the token file and click OK.

      Note that personal access tokens have a short life. Before uploading, ensure that the access token hasn't expired. To generate a personal access token, see Get an Oracle Cloud Applications User's Personal Access Token.

  17. In Build Artifact, enter the same artifact name that you used in the packaging build step.
  18. Click Save.
Configure a Job's Privacy Setting

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 Gear.
  2. Click Builds.
  3. Click the Job Protection tab.
  4. From the jobs list, select the job.
  5. Select the Private option.
  6. In Authorized Users, add yourself.
    To add other users, select their names.
  7. Click Save.

A private job shows a Lock 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.

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.

Create and Configure a 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 design page, from the Jobs list, drag-and-drop the packaging job and the deployment job to the designer area.

    Example:

    Production pipeline jobs
  7. Mouse over the Start node's Gray circle Gray circle on the right of the Start node handle. The cursor icon changes to the + cursor icon. Drag the cursor from the Gray circle Gray circle on the right of the Start node handle to the packaging job's White circle White circle on the left side of the job node handle. An arrow line appears.

    Example:

    Packaging job
  8. Mouse-over the packaging job's Blue circle Blue circle on the right side of the job node handle and drag-and-drop the arrow head over the deployment job's White circle White circle on the left side of the job node handle.

    Example:

    Deploy job
  9. Click Save.
Run the Pipeline

To run the packaging job and the deployment job in sequence, run the pipeline.

  1. In the navigation menu, click Builds Builds.
  2. Click the Pipelines tab.
  3. For the pipeline you want to run, click Build Build.

After 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 Latest Console. After a successful build, inform the Oracle Cloud Applications administrator that the app extension's artifact has been pushed to the Oracle Cloud Application's production instance.

After a successful build, inform the Oracle Cloud Applications administrator that the app extension's artifact has been pushed to the Oracle Cloud Application's production instance.

Migrate Your Oracle Cloud Application’s Customization

When you’re ready to deploy your app extension to the Oracle Cloud Application's production instance, you should also migrate your Oracle Cloud Application's customization from your source instance, such as the test instance, to the target production instance.

Before you migrate your customizations to the production instance, make sure that you have migrated and applied customizations from all app extensions you're developing to the test instance. After successfully verifying the migration, configure CSM jobs to migrate all customizations from the test to the production instance.

See these topics to configure your jobs and set up the pipeline. Remember to use the environment with the Oracle Cloud Applications test as your source, and the environment with the Oracle Cloud Applications production instance as your target.

Run the CSM Apply job's build after manually testing your changes on the target production instance.