5 Work with Service Connections

When you want to access external REST service APIs in your visual application, you create connections to these services (service connections) in the Service Connection tab of the Navigator.

About Service Connections

A service connection describes the connection to a specific service, including the connection details and properties, and the specific REST endpoints provided by the service that you want to use in your applications.

You can create a service connection in the following ways:

  • Selecting a service in your integrated service catalog of pre-configured Oracle SaaS/PaaS REST Services
  • Providing a document that describes the external service
  • Providing the location of a REST service endpoint of the external service

You use the Services tab in the Navigator to add new connections and manage your existing service connections. Selecting a service connection in the list opens a tab for the connection in the editor where you can view and edit the details of the connection and the endpoints that are available.

You can delete a service connection by right-clicking the service in the Navigator and choosing Delete.

For each of your service connections, you can use the following tabs in the connection editor to view and edit the connection’s details.

Tab Description

The Service tab displays the title and version of the REST API that you create a service connection to. You can edit the title of the service as it appears in your visual application editors.

When  Server Only Connections is selected in the Service tab, the service connection can only be used by the server, for example, from a Groovy script.


The Servers tab displays the server(s) associated with the service connection. A server entry is a collection of the base URL, header, security, and network configuration attributes that you need to connect to the REST service. You can add, edit, or remove servers to the service connection. You may have one or more servers if the REST service you access is hosted on different instances. For example, a production instance is likely to contain live customer data, while an in-house development instance would probably not contain this type of data.

You use the Add Server button to add new servers where you specify details such as:


The Endpoints tab displays a list of the endpoints of the service that you selected when you created the connection. You can use the tab to add and manage endpoints.

You can click + Endpoint to open a menu where you can choose to add more endpoints from the service or to add custom endpoints. Each endpoint in the list has an options menu where you can choose to edit, duplicate or delete the endpoint.

See Understand Data Access Through REST for more on the options and parameters that you can use to configure service connections.


The Headers tab displays the headers written in the REST call to the service. You can add and edit headers in the tab.


The Transforms tab displays the transform.js JavaScript file with the functions used to interpret requests to and responses from the service. You can edit the file to add transform functions. You typically use transform scripts to perform the following types of functions:

  • Pagination functions that limit the number of records that are displayed on a page in the REST client.
  • Filtering functions that define filter operations to specify the data to be returned and displayed in the REST client.
  • Sorting functions specify how to sort items returned from a collection resource.

The Source tab displays the OpenAPI 3 description of the service’s REST API. The file contains the details about the connection settings, response and request definitions and other parameters that are used in your applications. You can edit the entries in the Source tab.

Manage Backend Services in Your Visual Application

You use the Services tab in your application’s Settings editor to manage the backend service types that your visual application can access, such as Integration Applications, Oracle Cloud Applications, and Process Applications.

A backend service type is a collection of servers that you use in your visual application to access backend services, such as endpoints from Oracle Cloud Applications, in association with application profiles, so that you can successfully develop, test, and deploy your application. When you create a service connection using a REST API from the Service Catalog, you are choosing one of the backends defined in your VB Studio environment. For example, if you choose Sales and Service, the service connection resolves using the backend configured at the application level and, if not present, it resolves to the backend configured at the environment level.

Description of backend-diagram-final.png follows
Description of the illustration backend-diagram-final.png

The following image shows three backends (Integration Applications, Oracle Cloud Applications, and Process Applications). The project owner for this environment has configured the Oracle Cloud Applications backend type to connect to an Oracle Cloud Applications instance that provides access to the three types of application shown under the Oracle Cloud Applications backend.

In your VB Studio environment, you, or your project owner, specifies the backend service type details (Instance URL, authentication type, and so on) that provide the catalog of applications from that backend service type that your visual application can access. When your environment's Visual Builder instance is provisioned as a part of Oracle Integration, you can access the Integration and Process backends associated with your Visual Builder instance. If no backend service type has been set for your environment, or you want to override the settings for your environment's Visual Builder instance, use the dialogs that you can invoke from the Services tab in your application’s Settings editor.

The high-level steps to add or modify a backend service type are the same for each backend service type. Taking Oracle Cloud Applications as an example, you supply the Instance URL of your Oracle Cloud Applications instance (for example, https://my-oracle-cloud-instance.example.com). This will automatically discover the interfaceCatalogs endpoint (typically <Oracle Cloud Applications Base URL>/helpPortalApi/otherResources/latest/interfaceCatalogs) of the Oracle Cloud Applications instance and retrieves the list of available services from the most recent ADF Describe. You also need to specify an authentication mechanism for accessing the instance. Your visual application only supports one URL for any specific Service Catalog at a time. It is possible to edit all the server details (instance URL, authentication mechanism, and so on) of a server after it is registered in a backend service. The server that you specify is used by default in the Base configuration application profile, unless you specify an alternative application profile.

If you do not see any services in your catalog after confirming the Catalog Base URL and authentication mechanism are correct, you should consult your administrator to confirm that you have the proper credentials and that your user role is authorized to access services from the service instance.

To set the URL of the Service Catalog for your application:

  1. In the visual application's header, click the Menu option in the upper right corner.
  2. Click Settings.
  3. Open the Services tab in the Settings editor.
  4. If you want to create a backend:
    1. Click Create Backend and select the backend service type that you want to create.
      You can only create one backend of each type in your visual application. You can specify more than one server that provides access to the backend service by adding additional servers that host the service.
    2. In the dialog that appears, enter the instance URL for the backend service and other information, such as authentication details and headers, that your visual application requires to successfully connect to the service.
    3. Click Create.
  5. If you want to modify an existing backend service type, select the backend service type (for example, Oracle Cloud Applications) and click the Override Tenant Settings radio button to enable the UI controls that allow you to modify the settings specified by your system administrator.
    You can add a new server that hosts the backend service, or modify an existing server. If you have multiple servers defined for the backend service, you can delete one or more, but you must retain a minimum of one.

Add an Oracle Cloud Application Instance to a Visual Application

If you want to populate the service catalog of a visual application with the REST services from an Oracle Cloud Application backend service, you need to add the Oracle Cloud Application instance URL to the same environment as your Visual Builder instance.

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

You can add only one Oracle Cloud Application instance to an environment. The Oracle Cloud Application instance can reside either in your current identity domain or in another identity domain. When adding an external Oracle Cloud Application instance, you'll be asked for the credentials of an Oracle Cloud Application user who can access the instance, so be sure you have that available.

Add an Oracle Cloud Applications Instance From Your Current Identity Domain
  1. In the navigation menu, click Environments Environments.
  2. In the Service Instances tab, click Add.
  3. In the Add Service Instances dialog box, click the Oracle Cloud Applications tab.
  4. Select the Identity Domain option.
  5. 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 an Oracle Cloud Applications Instance From Another Identity Domain

To add an instance of Oracle Cloud Applications from another identity domain, you'll need the credentials of an Oracle Cloud Application user who can access the instance.

  1. Identify a user who can access the Oracle Cloud Application instance and get that user's credentials.
  2. Open VB Studio.
  3. In the navigation menu, click Environments Environments.
  4. 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.
  5. In the Service Instances tab, click Add instance.
  6. In the Add Service Instances dialog box, click Oracle Cloud Applications.
  7. Select the Application Credentials option and follow these steps:
    1. In Base URL, enter the base Oracle Cloud Application's URL.
    2. In Instance Name, if required, update the instance's display name. The name will be displayed in the Service Instances tab.
    3. In Username and Password, enter the user's credentials.
    4. Click Add.

About Application Profiles

Application profiles in VB Studio facilitate the development of web and mobile apps that consume REST services.

As you develop your web and mobile apps, you need access to the REST services that your app will consume when it goes into production. Given that it may not be possible or appropriate to use production instances of the service as you develop your app, you use development and test instances that provides the same APIs as the production instance of the service for the development and test phases of application development.

To make the task of changing between development, test, and production instances easier, VB Studio provides you with the ability to define application profiles in your visual application where you specify the appropriate details to use for an app when you deploy it to a development, test, or production environment. For example, basic authentication may be acceptable to use during the development of your application, but it is not recommended that you use this authentication type when you deploy your app to production. In this scenario, you can configure an application profile for development where you use the basic authentication mechanism that is less onerous to implement. The application profile that you use to deploy the app to production uses a more secure authentication mechanism.

Description of vb-app-profiles.png follows
Description of the illustration vb-app-profiles.png

You access application profiles from the Application Profiles tab of your visual application’s Settings page. VB Studio provides one ready-to-use application profile (Base configuration) that is the default application profile to use when you deploy web and mobile apps in this visual application to development, test, and production.

To create additional application profiles, click Duplicate and provide a new name (for example, Production configuration), ID, and description in the Duplicate Application Profile dialog that appears. Having created the new profile, you can make it the default to use when you deploy your visual app by selecting the appropriate option from the menu that appears to the right of the newly created application profile.

Description of vbs-app-profiles-prod-config.png follows
Description of the illustration vbs-app-profiles-prod-config.png

The application profiles that you create can be associated with the various servers (dev, test, and prod) used by the REST service that your app consumes. In the following example, a service connection for a REST service that returns contact information (contactsapi) lists three servers that host the REST service. The development server uses the base configuration application profile while the test and production servers use the corresponding application profiles.

Description of vbs-app-profiles-server.png follows
Description of the illustration vbs-app-profiles-server.png