2 Manage Instance Settings

After a Visual Builder instance is created, users with the role of Visual Builder Administrator can manage and set global options for applications in the instance and create associations between the instance and other services.

Manage Applications in the Service Instance

An Oracle Visual Builder administrator can manage any application in the service instance and does not need to be a team member to see an application on the Home page. Administrators can perform all the tasks of a developer, including adding and removing team members, and opening, staging and publishing applications.

The Home page displays a list of the applications in the service instance. Developers can only see and manage an application when they are a member of the application’s team. Administrators can select the Administered by me checkbox if they want the list of applications to include all the applications in the instance, even the applications where they are not a team member. The checkbox is not visible to developers who do not have the role of administrator.


Description of admin-homepage-applications.png follows
Description of the illustration admin-homepage-applications.png

Note:

On the Home page for classic applications, administrators can select the Applications I administer checkbox in the Filter by pane to display the applications where they are not a team member.


Description of admin-homepage1.png follows
Description of the illustration admin-homepage1.png

Access Instance Settings

Administrators can access a page for managing the instance’s global settings. The settings page contains panels for configuring security settings, specifying Access Denied messages and specifying Oracle Process Cloud Service details.

You can access the instance settings page from any Visual Builder page, but the steps for opening the page will depend on if you are developing visual applications or classic applications.

To open an instance’s settings page:

  1. Click Home in the Visual Builder title bar to open the main menu.
  2. Click Settings in the main menu.

    If you are developing visual applications, open the main navigation pane on the Home page and select Settings.


    Description of admin-settings-menu.png follows
    Description of the illustration admin-settings-menu.png

    If you are developing classic applications, select Administer Visual Builder in the Administration Options menu and then click Global Settings.


    Description of admin-options-menu.png follows
    Description of the illustration admin-options-menu.png
The settings available for the instance are grouped on the page.

Configure Security Options for Applications

Administrators can use the Security panel in the settings page to require authentication for all applications in the instance.

When an administrator enables the Allow only secure applications to be created option, all published and staged applications in the instance will require user authentication. When the option is enabled, users must be assigned a role by the identity domain administrator and log in to access an application. When the option is not enabled, applications can be created that allow access to anonymous users.

When an application has the default security settings, any user with a valid login can access the pages in an application. A developer can modify the default security settings to define the roles that can access applications, pages and components. When the secure application option is enabled, an administrator can enable an option that users must be assigned the role of Visual Builder User in addition to any other roles used to secure access to staged and published applications. For example, security can be configured so that users assigned the role Visual Builder Developer can access the designer but can’t access the published application and data because they are not assigned the role Visual Builder User.

To block access by anonymous users to all applications in the instance:

  1. Open the instance’s settings page.
  2. In the Security panel, enable Allow only secure applications to be created.

    Anonymous users can’t access the applications when this option is enabled.


    Description of admin-settings-security.png follows
    Description of the illustration admin-settings-security.png

    When the secure applications option is enabled, administrators can enable the Only Visual Builder Users can access secure applications option.

Set Page Messages for Access Denied Errors

Administrators can use the instance’s settings page to specify a URL that users are navigated to when they are denied access to an application or page.

Authenticated users might see an Access Denied page or message when they attempt to access an application or page in an application that their user role is not permitted to access. Administrators can set the default page or message that users see when they are denied access to an application or page. Access Denied messages that are set at the application level in the General Settings of an application will override messages set in the instance’s settings page. The default Access Denied page and message is used if the message options in this panel are not set.

To specify an Access Denied page or message for applications in the instance:

  1. Open the instance’s settings page.
  2. In the Security panel, type a URL that users are directed to when denied access to an application.

    The URL that you specify is used as the Access Denied page for all applications in the instance and should be accessible to users who are not logged in.


    Description of admin-settings-messages.png follows
    Description of the illustration admin-settings-messages.png

    Note:

    If you are configuring settings for classic applications, the Access Denied settings are set in the Messages panel.
  3. Type the message that you want users to see when they are denied access to a page.

    The message that you enter will be displayed in the Access Denied page for all applications in the instance except for those where a message was set at the application level in the application’s General Settings page.

Allow Other Domains Access to Services

Use the Global Settings page to specify the domains that are permitted to interact with services in your instance.

Cross-Origin Resource Sharing (CORS) is a mechanism that enables you to specify the domains that are allowed to exchange data with applications in your instance. By default, incoming requests from domains not on your instance’s list of allowed origins are blocked from accessing application resources.

To add a domain to the list of allowed origins:

  1. Open the instance’s settings page.
  2. In the Allowed Origins panel, click New Origin and type the URL of the domain that you want to allow. Click Submit.

    The Allowed Origins panel lists all origins that are permitted to retrieve information from the instance.


    Description of admin-settings-origins.png follows
    Description of the illustration admin-settings-origins.png

Switch to Your Own Oracle DB Instance

If the 5GB limit of the database provisioned with your Visual Builder instance is insufficient for your tenant schema, you can configure your instance to use an Oracle DB instance that has more space instead of the default database.

To use a different Oracle DB instance, you use a wizard in the Tenant Settings to create a connection to the database instance and export the applications stored in tenant's current database. You can connect to an Oracle DBaaS or Autonomous Transaction Processing Database (ATP) instance.

If you decide to use JDBC to connect to your DBaaS instance, you must include the privileges required to enable the ADMIN user to create a tenant schema. The following SQL shows the grants that are needed:

CREATE USER [adminuser] IDENTIFIED BY [password];
GRANT CONNECT, RESOURCE, DBA TO [adminuser];

GRANT SELECT ON SYS.DBA_PROFILES TO [adminuser] WITH GRANT OPTION;
GRANT SELECT ON SYS.DBA_USERS TO [adminuser] WITH GRANT OPTION;
GRANT SELECT ON SYS.DBA_DATA_FILES TO [adminuser] WITH GRANT OPTION;
GRANT SELECT ON SYS.DBA_SEGMENTS TO [adminuser] WITH GRANT OPTION;

If you decide to use ATP, you might want to create a new ATP ADMIN user with the correct admin privileges. The following SQL statement shows how to create a second ATP ADMIN user in SQL*Plus or SQL Developer.

DROP USER [adminuser] CASCADE;
CREATE USER [adminuser] IDENTIFIED BY [password];
GRANT CREATE USER, ALTER USER, DROP USER, CREATE PROFILE TO [adminuser] WITH ADMIN OPTION;
GRANT CONNECT TO [adminuser] WITH ADMIN OPTION;
GRANT RESOURCE TO [adminuser] WITH ADMIN OPTION;
GRANT CREATE SEQUENCE, CREATE OPERATOR, CREATE SESSION,ALTER SESSION, CREATE PROCEDURE, CREATE VIEW, CREATE JOB,CREATE DIMENSION,CREATE INDEXTYPE,CREATE TYPE,CREATE TRIGGER,CREATE TABLE,CREATE PROFILE TO [adminuser] WITH ADMIN OPTION;
GRANT UNLIMITED TABLESPACE TO [adminuser] WITH ADMIN OPTION;
GRANT SELECT ON SYS.DBA_PROFILES TO [adminuser] WITH GRANT OPTION;
GRANT SELECT ON SYS.DBA_USERS TO [adminuser] WITH GRANT OPTION;
GRANT SELECT ON SYS.DBA_DATA_FILES TO [adminuser] WITH GRANT OPTION;
GRANT SELECT ON SYS.DBA_SEGMENTS TO [adminuser] WITH GRANT OPTION;

In the wizard you need to select and export all the applications in your instance that you want to keep. After confirming that your instance is using the new database instance, you must import the exported applications into Visual Builder to save them in the new database instance.

To switch to a different Oracle DB instance:

  1. Open the instance’s Tenant Settings page.
  2. Click Use Different Database in the Tenant Database panel to open the Change Tenant Database wizard.

    In the Change Tenant Database wizard you supply the details for the connection to your Oracle DB instance.



  3. Select a Connection Type in the drop-down list.

    You can connect to your Oracle DB instance using either JDBC or an ATP Cloud Wallet.

  4. Provide the details for connecting to your database. Click Next.

    The details you need to provide will depend upon the type of connection you selected.

  5. Select all the applications that you want to export. Click Finish.

    You must select and export all the applications that you want to keep. Any applications that are not exported will be lost.



When you click Finish, the applications that you selected are downloaded to your local file system. Exported application archives include the details about the application's user roles, and they will be available when the app is re-imported into the new database.

Reset an Expired Password or ATP Wallet for Your Oracle DB Instance

If you switch to use your own Oracle DB instance and the credentials you use to access the instance expire, you can renew the expired credentials using the Update Tenant Database Connection dialog.

To regenerate the expired values, you need to provide the ADMIN user credentials that you provided when you first switched to your own Oracle DB instance. Visual Builder uses the ADMIN user credentials to generate new Visual Builder tenant credentials to replace the expired credentials. Visual Builder does not store the ADMIN user credentials that you supply.

To reset expired credentials:

  1. Open the General tab of the instance’s Tenant Settings page.
  2. In the Tenant Database field, click the Edit icon to open the Update Tenant Database Connection wizard.
  3. In the Update Tenant Database Connection wizard, supply the ADMIN user credentials that Visual Builder will use to reset the expired credentials for your Oracle DB instance.
  4. Click Finish.

Add a Connection to Oracle Cloud Applications

The list of REST services in the service catalog of a visual application is retrieved from an Oracle Cloud Applications backend service. Specify the instance URL of the Oracle Cloud Applications backend service in the Tenant Settings page or in the Settings page of a visual application.

All visual applications in the tenant will use the Oracle Cloud Applications instance URL specified in Tenant Settings, but a visual application can be configured to use a different Oracle Cloud Applications backend service by specifying a different instance URL in the visual application’s Settings page. The tenant-level backend configuration is ignored if you or a visual application developer configures a different Oracle Cloud Applications backend service in a visual application’s Settings page.

The authentication choices available to configure a tenant-level Oracle Cloud Applications backend are:
  • Oracle Cloud Account: Needs federation between Oracle Cloud Applications and Visual Builder.
  • Propagate Current User Identity: Same as Oracle Cloud Applications. That is, it needs federation between Oracle Cloud Applications and Visual Builder.
  • None: This assumes your Oracle Cloud Applications REST API can be called without any authentication, which is not usually the case.

If the necessary pre-requisites for setting a tenant-level Oracle Cloud Applications backend service are not available, then a visual application developer can set up a backend service at the visual application level where more options are available. Another option is for you (the service administrator) to configure the Oracle Cloud Applications backend with None and let the visual application developer override the authentication setting at the visual application level.

To specify an Oracle Cloud Applications service for the tenant:

  1. Open the instance’s Tenant Settings page.
  2. In the Services tab, click Create Backend and choose Oracle Cloud Applications in the Backend Service Type dialog.

    When specifying the URL in the Tenant Settings, you (the service administrator) only need to provide the instance URL of the Oracle Cloud Applications backend service to retrieve the list of services.


    Description of admin-settings-fa-url.png follows
    Description of the illustration admin-settings-fa-url.png
  3. In the dialog, type the Server URL of the backend service, and configure other settings, such as security, as needed.
  4. (Optional) After you configure settings for the backend, add headers to the backend.
    Backend headers that you add will be applicable for any service connection to this backend, irrespective of the server or application profile that is used.
  5. Click Create.

    Visual Builder automatically discovers the interfaceCatalogs endpoint of the Oracle Cloud Applications backend, which retrieves the list of services and their metadata. This endpoint is typically in the form:

    https://<My Oracle Cloud Applications Instance URL >

    This endpoint is publicly accessible without any authentication.

    If there is a problem creating the connection, verify the instance URL of the Oracle Cloud Applications instance.

Manage Self-signed Certificates

Administrators can use the Certificates page to upload and manage the self-signed certificates used by the instance to enable inbound and outbound SSL communications to a service’s REST APIs

When creating connections to REST services that use self-signed certificates, you might need to add an API’s certificate to your Visual Builder instance to validate SSL connections to that service. You can use the Certificates page to upload and remove certificate files (.pem)  for services. Uploading a service’s certificate file to the keystore will allow all applications in the instance to communicate with that service. The Certificates page displays a list of certificates that have been added. You can click the Delete button in a row to remove the certificate.

To upload a self-signed certificate:

  1. Open the Visual Builder main menu and click Certificates.

    The Certificates page displays a list of the certificates already uploaded to the instance.


    Description of admin-certificates-page.png follows
    Description of the illustration admin-certificates-page.png
  2. Click Upload to open the Upload Certificate dialog box.

    You use the Upload Certificate dialog box to create an alias for the certificate and upload the service’s certificate file from your local system.


    Description of admin-certificates-upload.png follows
    Description of the illustration admin-certificates-upload.png
  3. Type the alias in the Certificate Alias Name field.

    The alias is used to identify the certificate in the table in the Certificates page. The Certificate Type dropdown list is read-only because only Trust Certificates are supported.

  4. Drag the certificate file from your local system into the upload target area, or click the upload target area to browse your local system.
  5. Click Upload to add the certificate to the service keystore.

Manage Your Component Exchange

If your team develops custom components for visual applications and want the components to be available to all users in the Visual Builder Components tab, you'll need to first set up a component exchange. This chapter tells you how to set up the Component Exchange in Visual Builder.

What is a Component Exchange?

A component exchange is a repository of custom components available in VB Studio. You can use these components in your visual applications, such as web components and application templates. Many of the components provided by Oracle can be installed from a component exchange.

To integrate a component exchange with a Visual Builder instance, you provide the exchange's URL and credentials in the Tenant Settings. The exchange can be a private exchange in a VB Studio project or one of the exchanges maintained by Oracle.

If your organization develops or uses proprietary components, these components can be published to a private exchange hosted by a VB Studio project. For example, if you have a web component designed to be used in applications in your tenant, you can set up your own exchange and use it to distribute the component to developers in the tenant. Additionally, components provided by Oracle are automatically available from all private component exchanges.

Oracle maintains two component exchanges containing components validated by Oracle that are publicly available to all developers. If you don't have a private exchange but you want to give developers access to these Oracle components, you can add one of the following exchanges maintained by Oracle. If your instance is in the US, use the following details.

If your instance is in Europe, use the following details.

About Component Exchanges Hosted in VB Studio Projects

A VB Studio project can host a secure component exchange to store and distribute components only available to developers in the instance.

Each VB Studio project includes the component exchange 'compcatalog', which is the service used to access components stored in the project. The compcatalog service is provisioned by default with each project. Any project can be used to host an exchange if storage is enabled for the VB Studio instance. Component developers can use the service's APIs to publish components to the exchange.

To integrate a private exchange in a VB Studio project with a Visual Builder instance, an administrator specifies the URL for the project's compcatalog service and the credentials for a user that can access the project. The credentials used to connect to the exchange must be an owner or member of the VB Studio project hosting the exchange. All developers in the tenant use these credentials to connect to the exchange to get the components and application templates they want to use in their projects.

The URL for the project's compcatalog service has the following form: https://<hostname>/<org_id>/s/<project_id>/compcatalog/0.2.0/

In the URL, "compcatalog" is the exchange service and "0.2.0" is the API version of the service.

To determine the URL for the compcatalog service, you need to know the following details about the VB Studio project:

  • <hostname>. This is the VB Studio server where the project is hosted.
  • <org_id>. This is the organization (tenant) name.
  • <project_id>. This is a project identifier unique to the tenant. This is not the same as the project display name entered by the project owner and is not displayed in the VB Studio UI.

If you do not know the <project_id> for the project hosting the exchange, you can get it from the Git or Maven configuration, or by using the VB Studio Projects API. The following table describes how to get the <project_id>.

Method Steps
From a Git or Maven configuration
  1. In VB Studio, open the project and locate the Repositories tab on the project's Home Page.
  2. Expand the the Git or Maven section and copy the repository URL.

The Git repository URL will be similar to the following: https://{user_id}@{hostname}/{org_id}/s/my-org_testproject_5/scm/my-repo.git

The Maven repository URL will be similar to the following: http://{hostname}/{org_id}/s/my-org_testproject_5/maven/

In these examples, "my-org_testproject_5" is the project identifier. In this case, the URL for the 'compcatalog' service will be similar to https://{hostname}/my-org/s/my-org_testproject_5/compcatalog/0.2.0/

Using VB Studio Projects API

If you know the name of the project sharing your exchange instance, you can get the project metadata using a REST call to the VB Studio API.

For example, you can use cURL to send a REST call similar to the following:

curl -X GET -u '{username}:{password}'https://{hostname}/{org_id}/api/v2/projects/info/name:TestProject

The return should be similar to the following:

[
  {
    "organization":"my-org",
    "identifier":"my-org_testproject_5",
    "name":"TestProject",
    "urlId":"testproject",
    "description":null,
    "accessibility":"PRIVATE",
    "template":false,
    "state":"READY",
    "locked":false,
    "relation":{"membership":"OWNER","favorite":false}
  }
]

In this example, the identifier property in the return is the project identifier that is needed for the "compcatalog" service URL.

Add a Connection to a Component Exchange

When an instance is integrated with a component exchange, all developers using the instance can access and install components stored there.

After an exchange is added to the instance, all developers can use the Components tab in the Navigator to install and manage the components from the exchange that they want to use in their applications. When creating an application in the Create Application wizard, developers can also select any of the application templates that have been published to the exchange.

To add a connection to the Component Exchange:

  1. Open the instance’s Tenant Settings page.
  2. In the Component Exchange panel, enter the URL and credentials for the component exchange.

    Description of admin-settings-componentexchange.png follows
    Description of the illustration admin-settings-componentexchange.png

    If you are adding a connection to a private component exchange, it is recommended that the credentials you provide are for an administrator who is a member of the VB Studio project hosting the exchange or the project owner.

Configure Support for a Custom Domain

When a custom domain (for example, mycustom.example.org) is mapped to your instance, customers can use it to access a web application instead of using the default URL generated by Visual Builder.

A custom domain is a customer-provided hostname and domain (FQDN) created by adding a subdomain to your domain. After configuring your instance to use a custom domain, app users accessing the app using the custom domain will not see the typical Oracle domain (for example, myvbinstance-accountname.builder.ocp.oraclecloud.com) in the URL, and instead could see and use, for example, mycustom.example.org.

After configuring a custom domain:

  • Users can access a single web app by typing just the custom domain URL in the browser, for example, mycustom.example.org. The app is loaded from the custom domain root ("/"), and no additional path information or query parameters are required in the URL.
  • http can be redirected to https, so if a user types "mycustom.example.com", this will resolve to https://mycustom.example.com, and load the default web app.
  • For applications that contain business objects, the Business Object REST API can also use the custom domain configuration.

You can configure multiple custom domains for your instance, but each custom domain must be mapped to a different visual application. For example, if the visual application myvisualapp1 is mapped to the subdomain mysubdomain1, if you want to map mysubdomain2 to an application it must be mapped to a different visual application (myvisualapp2).

Custom domains are also subject to other limitations:

  • You can't access the Visual Builder design-time using a custom domain. You'll need to use the original Oracle Cloud URL to access the Visual Builder designer.
  • A custom domain can only access a published app. It will not work for apps that are only staged.
  • A custom domain can only be used to access one live app (in the visual application configured for the root URL). You can access other live apps in the same instance only by using the full Oracle Cloud URL or by creating and configuring a different custom domain and visual application.
  • If a visual application contains more than one web app, only one of them can be accessed using the custom domain. It's not possible to specify which app in a visual application will be available at the custom domain because the domain is configured in the Settings for the visual application, not for individual web apps. If you are going to use a custom domain, it is recommended that the visual application only contain one web app to ensure that the correct app is loaded.
  • If you publish a different web app in your visual application, it immediately becomes the default app for the custom domain, and the previous web app will no longer be available at the custom domain.
  • Mobile and PWA apps are not supported at this time. Custom domains can only be used for web apps.

To configure a custom domain for your instance, you must be the registered owner of the domain and have access to its SSL certificate bundle information. You must also have an Oracle Visual Builder or Oracle Integration instance (the following tasks do not apply to Visual Builder in Oracle Integration Generation 2 on Oracle Cloud Infrastructure). You'll also need the ability to configure Oracle Cloud Infrastructure Web Application Firewall (WAF) for your OCI account.

To use a custom domain you need to perform the following tasks:

  • Create and configure a WAF policy
  • Through your DNS provider, create a subdomain, and add a CNAME record for the subdomain which points to the WAF policy

  • Log a Service Request through your Oracle Support Representative to configure the server backend to handle requests for the subdomain.

  • Set the custom domain in the visual application's Settings editor and publish the app.

Create a WAF Policy

To create and edit a policy you'll need to have the ability to configure Oracle Cloud Infrastructure Web Application Firewall (WAF) for your OCI account.

To create the WAF policy:

  1. Sign in to the Oracle Cloud Infrastructure Console and open WAF Policies under Security.
  2. Select the compartment you want the WAF policy to be created in and click Create WAF Policy.
  3. Enter the details for the policy in the Create WAF Policy dialog box.


    In the Create WAF Policy dialog box you need to enter a policy name, primary domain, WAF origin name and URI.

    • Policy Name: provide a name for the WAF policy (for example, mycustom_example_com_waf_policy)
    • Primary Domain: the customer's chosen DNS name (for example, mycustom.example.com)
    • Additional Domains: (empty, or additional (sub)domains)
    • Origin Name: provide a name for the primary origin (for example, mycustom_vb_waf_origin)
    • URI: the URI of the Visual Builder service (for example, myvbcsinstance-example.builder.ocp.oraclecloud.com)

    Note:

    If you would like to have more than one custom domain pointing to different applications on the same Visual Builder instance (for example, mysubdomain1.example.com pointing to myvisualapp1, and mysubdomain2.example.com pointing to myvisualapp2), you can configure this in a single WAF policy by adding additional (sub)domains in the Domains section of the WAF policy dialog box.

  4. Click Create WAF Policy.
    After you click Create WAF Policy, it might take several minutes to create the policy. The CNAME target is displayed after the policy is created.
  5. Note the CNAME Target for the WAF policy.

    At the top of the WAF policy view you'll see a message with the name. You'll need this CNAME when you configure your domain's DNS record at your DNS provider to map the subdomain to your instance. The CNAME Target will look similar to this:

    mycustom-example-com.b.waas.oci.oraclecloud.net

You still need to upload the SSL certificate for your domain to your WAF policy so you can enable HTTPS. You can get the SSL certificate when you configure your domain's DNS record.

Create and Configure a Subdomain and Configure SSL in the WAF Policy

To use a custom URL for your app you'll need to use your domain provider's tools to create a subdomain that points to the WAF CNAME target for your instance that was generated for you after you created the WAF policy.

Using the tools for administering your domain, you will need to edit your domain's DNS record to create or identify the subdomain and map it to the WAF CNAME of your Visual Builder instance. Your WAF CNAME will look similar to mycustom-example-com.b.waas.oci.oraclecloud.net. If you are unsure about how to create a subdomain and CNAME entry with your domain provider, please check with your organization's network administrator.

After editing the DNS record, you'll need to get the SSL certificate for the domain so you can upload it to your WAF policy. You'll then need to log a Service Request to configure the instance backend.

To create and configure a subdomain for your instance:

  1. Open the tool of your domain provider for creating a subdomain.
  2. Create the subdomain you want to use (for example, mycustom.example.com) and edit it's CNAME record to point to the WAF CNAME of your WAF policy.
  3. Confirm there is a valid SSL certificate that applies to the subdomain.

    The certificate might be provided by your domain provider or through a valid certifying authority (CA) (for example, Comodo, DigiCert). It shouldn't be a self-signed certificate. You will need to provide the CA-signed SSL certificate in the WAF policy, so you might want to consider an SSL certificate specifically for the subdomain rather than a wildcard SSL cert (*.example.com).

  4. Extract or export the bundle containing the certificate and private key.


    Depending on your domain provider, you may need to indicate that you want to use the certificate on your own server in order to download the bundle.


    Description of url-icert-nstall-message.png follows
    Description of the illustration url-icert-nstall-message.png
  5. In the OCI Console, locate and open the policy you created to view the WAF policy details.
  6. Click Settings for your WAF policy, and then click Edit.
  7. Select Enable HTTPS Support and upload the SSL Certificate and Private Key for your DNS name (for example, mycustom.example.com).

    Keep the HTTP to HTTPS Redirect option enabled.

  8. Click Save.

    It will take some time for the configuration change for the SSL certificate to complete.

  9. Log a Service Request through your Oracle Support representative to request that your Visual Builder instance be configured to handle requests for your custom subdomain.

    When you file the service request you will need to provide the following information:

    • your IDCS GUID
    • name of your Oracle Visual Builder or Oracle Integration instance
    • domain/subdomain created in the DNS CNAME record and mapped to the WAF policy (for example, mycustom.example.com)

After these setup steps have been completed by you and Oracle, you can map your visual application to the custom domain.