6 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
Service

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.

Servers

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 development instance may be used for development as it will not contain customer data while a production instance contains live customer data.

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

Endpoints

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.

Headers

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

Transforms

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.

Source

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 Visual Builder instance. 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 tenant 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 service administrator for this Visual Builder instance 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 Visual Builder instance, your service administrator 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. If no backend service type has been set for your Visual Builder instance, or you want to override the settings for your 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. Choose Settings in the visual application’s Options menu in the toolbar.
  2. Open the Services tab in the Settings editor.
  3. 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.
  4. 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.

About Application Profiles

Application profiles in Visual Builder 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 service(s) 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, Visual Builder 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. Visual Builder 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, stage, 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 stage or publish your visual app by selecting the appropriate option from the menu that appears to the right of the newly-created application profile.

Description of vb-app-profiles_prod-config.png follows
Description of the illustration vb-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 vb-app-profiles-server.png follows
Description of the illustration vb-app-profiles-server.png