5 Work with Services
To access external REST APIs in your visual application, you create connections to the services that provide access to these API endpoints.
What Are Service Connections?
To work with an external service's REST API, Visual Builder needs basic information about that service. A service connection provides this information by describing the connection to the service, including connection details, properties, and the REST endpoints provided by the service that you want to use in your application.
- By selecting a service from a catalog of preconfigured Oracle SaaS/PaaS REST services
- By providing a Swagger or ADF-Describe specification that describes the external service
- By providing the location of a REST endpoint for the external service
A Visual Builder catalog of predefined services includes backends, such as Oracle Cloud Applications, Integration Applications, and Process Applications. These backends expose REST APIs that your visual application can consume right out of the box. You can also create custom backends to access services that aren't listed in this catalog, either by providing the service specification or by providing the URL of a REST endpoint of the service.
Use the Services tab in the Navigator to add new service connections and manage your existing ones. You can also manage your application’s catalog of backends here:
Description of the illustration service-connections-browser.png
What Are Backends?
A backend is a collection of servers that your visual application uses to access REST endpoints in a known resource, like Oracle Cloud Applications or Oracle Integration.
Each backend is associated with one or more servers, and each server has different instances for development, test, and production. These backend instances are defined in the Tenant Settings of your Visual Builder instance by your administrator and provide the out-of-the-box catalog that all visual applications in your instance can access. Your application uses these backend definitions (instance URL, authentication type, and so on), in association with application profiles, to connect to the right server, so you can successfully develop, test, and deploy your application, as shown here:
Description of the illustration backend-diagram-final.png
A typical backend catalog includes the built-in Integration, Oracle Cloud Applications, and Process backends. You can also create backends that map to other types of custom servers.
The catalog is described in an OpenAPI-compliant file called catalog.json, which contains the list of backends and their details at the tenant level. Because this definition applies to all visual applications, you can easily connect to REST APIs from the predefined catalog without having to specify instance URLs, authentication, and other details every time you create a visual application. You can choose to override the tenant-level definition for a single application, either to customize an existing backend (say, connect to a different instance or change the authentication mechanism) or to create your own—all of which is then stored at the application level in the services/catalog.json file.
When you create a service connection from a catalog, 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.
All new service connections will require a backend. If a backend doesn't exist, you'll be prompted to create one. Service connections created previously without a backend will continue to work and their configuration settings can be changed as well. You can create a custom backend when you create a service connection or create the backend first, and add the service connections to it later. You'll know when services are "derived" from a backend because you’ll see something like this:
Clicking the backend will take you to the Backends editor, where you can edit the backend’s details if you want.
Service Connections: Static Versus Dynamic
Service connections in Visual Builder are defined by the service's OpenAPI metadata, which describes the available endpoints and details required to connect to the service. How you want your connection to retrieve this service metadata—either statically or dynamically—is entirely up to you. Both options have their advantages and disadvantages.
https://service.com/openapidef. You can set up your service connection to retrieve this definition in one of two ways:
- Copy the service definition from
https://service.com/openapidefat the time of development and save it to the visual application's sources. That is, statically retrieve the service metadata saved to the application when the service connection was first created—a static service connection. - Always get the service definition from
https://service.com/openapidef. That is, dynamically retrieve the service metadata from the source URL each time you open the application—a dynamic service connection. The service definition in this case is only a "reference", a pointer to the OpenAPI document located outside Visual Builder.
In the service connection wizard, you can use the Metadata Retrieval Option to specify how you want to retrieve service metadata:
Description of the illustration static-dynamic-serviceconnections-appui.png
Here's what each option provides:
- Choose Dynamically retrieve metadata if your service definition changes frequently and you want to include these updates, especially during development, when things are rapidly evolving. In other words, by creating a dynamic service connection, you guarantee that a new field added to the service definition will be available to your application, because the service metadata is fetched every time the application is opened. This picks up all changes made to endpoints, including the new field. The metadata will always be up to date.
Note:
You can dynamically retrieve metadata only for service connections that provide a service specification or those derived from a catalog, specifically the Oracle Cloud Applications backend.
- For better runtime performance, consider the Copy full OpenAPI to your application to your application option. Dynamic service connections pull entire resources, not just individual endpoints, which can make the
openapi3.jsonmetadata file unwieldy. If you check the Automatically include list of values (LOV) check box as well, the size of the file increases even more. Coupled with factors such as complexity of the schema and network latency, dynamically retrieving metadata may take a while to retrieve and process. Using the Copy full OpenAPI option and selecting just the endpoints you need for your application can improve performance, as your endpoint definitions are stored locally in the application for faster retrieval. - While you might consider creating a dynamic service connection for development, then converting the connection to a static one when your application is ready for production, there’s a better option: Copy minimal OpenAPI to the application. This option provides the best of both worlds when you create a service connection that points to an ADF Describe.
The Copy minimal OpenAPI to the application option is available only for services that are based on ADF Describe (like Oracle Cloud Applications' ADF BC-based REST APIs) and have a minimal describe endpoint to get limited metadata. This option stores service metadata for the endpoints you select in your extension's sources, much like a static service connection, but it only copies the minimal describe for those endpoints. It also dynamically retrieves the parameter or request/response schema similar to a dynamic service connection. But it does this only when required (say, when a user tries to bind a table with an endpoint's response), not every time the extension is opened. Because only the minimal OpenAPI is copied to your application only for the endpoints you select, the size of the metadata file is reduced. And because the schema object is still referenced, the latest service definition is dynamically retrieved whenever required. For optimal performance, this is the recommended option for ADF Describe-based services.
| Service Connection Option | Advantage | Disadvantage |
|---|---|---|
| Copy full OpenAPI to your application (Static) | Better performance as service metadata is retrieved locally from the application's sources | Application is out of sync from the latest service definition and might not have recent customizations. Also, because full service metadata (including child objects) is saved to the application's sources, runtime performance may be impacted if this metadata is very large. Optimizing your resources can help in reducing the fetch time of the static OpenAPI. |
| Dynamically retrieve metadata (Dynamic) | Provides the most up-to-date service definition for your application | Performance may be impacted, though not always |
| Copy minimal OpenAPI to the application (recommended) (Static + Dynamic)
Note: Available only for ADF Describe-based services like Oracle Cloud Applications |
Optimal performance as minimal service metadata is stored and can be retrieved faster from the application's sources; granular endpoint selection is also possible. Dynamically referenced schema objects provide the ability to retrieve the most up-to-date request/responses schema. | Performance may be impacted when schema objects are retrieved |
No matter which option you choose to create your service connection, you can switch it up any time you want, as described in Convert a Service Connection (Static to Dynamic or Dynamic to Static). You can also change things when you edit a service connection to add endpoints, as described in Add More Endpoints to a Service Connection.
What Are Application Profiles?
Application profiles in Visual Builder facilitate the development of applications 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 provide 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 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. 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 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 backend that returns contact information (contactsBackend) lists three servers that host the relevant REST service. The development server uses the base configuration application profile while the test and production servers use the corresponding application profiles.
Manage Backends in Your Visual Application
Backends define servers that your visual application can access. You can view and manage the backends available to your application on the Backends tab, which you access from the Services tab in the Navigator.
The following image shows the built-in Integration Applications (ICS), Oracle Cloud Applications, and Process Applications backends, which have been defined in the tenant-level catalog: 
Description of the illustration backends.png
Description of the illustration backends-vbs.png
The administrator for this Visual Builder instance has configured the Oracle Cloud Applications backend to connect to an Oracle Cloud Applications instance that provides access to the three child backends shown under the top-level backend: Enterprise Resource Planning Supply Chain, Sales and Service, and Human Capital Management. You can create custom backends to map to other types of servers, either by providing an OpenAPI/Swagger file or by pointing to the URL of a custom Oracle ADF Describe.
If a backend hasn't been defined for your Visual Builder instance or you want to override the settings for your Visual Builder instance and create a catalog just for a particular application, use the Services tab to create a new backend or edit an existing backend.
| Tab | Description |
|---|---|
| Overview | Displays the name and type of the backend (which can be Integration Applications, Oracle Cloud Applications, Process Applications, or a custom backend).
You can use the + Service Connection button to create a service connection based on the backend. Note: The Process backend is not used to define service connections. It is used only when you access Process-related tasks in Visual Builder. See Work with Business Processes.If any service connections have been defined for the backend, they'll be listed below the + Service Connection button. Dynamic service connections, which are defined in the |
| Servers | Displays the servers associated with the backend and includes the instance URL and the application profile associated with the instance. You can add, edit, or remove backend servers. You may have one or more servers if the backend is hosted on different instances.
You use the Add Server button to add new servers where you specify details such as:
|
| Headers | Displays the static headers defined for the backend at the server level. You can add and edit headers in the tab. |
| Source | Displays the description of the backend stored in the tenant-level catalog.json file. If you override the tenant-level definition, this file shows the contents of the application-level catalog from the services/catalog.json file. You can edit the entries in the Source tab, if you want.
|
Note:
If you do not see any services in your catalog after confirming the URL and authentication mechanism are correct, contact your administrator to confirm that you have the proper credentials and that your user role is authorized to access services from the backend instance.Create a Backend
If your environment does not include Oracle-provided backends such as Integration Applications, Oracle Cloud Applications, or Process Applications, you can add these backends to create an application-level catalog for your visual application. You can create only one instance of each backend in your visual application.
The high-level steps to add a backend are the same for each backend and involve providing the URL of the instance that hosts the backend service, authentication mechanism to access the instance, and so on.
Let's say you want to add the Oracle Cloud Applications backend: You supply the URL of your Oracle Cloud Applications instance (for example, https://my-oracle-cloud-app-instance.example.com). This will automatically discover the interfaceCatalogs endpoint (typically Oracle Cloud Applications Base URL/helpPortalApi/otherResources/latest/interfaceCatalogs) of your Oracle Cloud Applications instance and retrieve the list of available services from the most recent ADF Describe.
To create a backend that connects you to the Integration Applications, Oracle Cloud Applications, or Process Applications catalog:
- Click Services in the Navigator.
- In the Services pane, click + sign and select Backend.
- In the Create Backend wizard, select the backend you want to create:
- To register an Oracle Cloud Applications instance as a backend, click Oracle Cloud Applications Instance.
- To register an Integrations instance as a backend, click Integrations.
- To register a Process Applications instance as a backend, click Process.
- Enter the instance URL and other information, such as authentication details and headers, that your visual application requires to successfully connect to the backend.
- Click Create.
It is possible to edit all the server details (instance URL, authentication mechanism, headers, connection type, and so on) after the backend is registered. You can also specify more than one server that provides access to the backend by adding additional servers that host the backend. See Edit a Backend.
Create a Custom Backend
You can create your own backend to map to a custom server other than the built-in Integration, Process, and Oracle Cloud Applications backends.
A custom backend is essentially the same as a service connection. You specify the instance URL, description, authentication, and static headers, and define application profiles—just as you would to manage any other service connection.
To create a custom backend:
- In the Name field, enter a name and description for the custom backend. Your description will be the backend's display name in your application.
- Enter the instance URL and other information, such as authentication details and headers, that your visual application requires to successfully connect to the custom backend.
Note:
If you're using an IP address instead of a proper DNS-based URL in a production environment, you're probably using self-signed certificates. You need to be aware that certificates based on IP addresses are less secure and more difficult to maintain than DNS-based ones and, to avoid potential security issues, self-signed certificates should never be used in production environments.An audit warning will be displayed whenever you use an IP address-based service connection.
Description of the illustration create-custom-backend-details.pngYou can create the backend first, then edit all server details after the backend is registered.
A new custom backend displays in the Backends tab on the Services pane. Click the newly created custom backend to view and edit its details. See Edit a Backend.
Create a Child Backend
You can create child backends to extend the functionality provided by the top-level Oracle Cloud Applications or custom backend registered in your application.
A child backend inherits the parent backend's definition, which you can override as required. Its server URL is derived from the top-level backend, with vb-catalog://backends/ as the base URL. Continuing the Oracle Cloud Applications example, the Sales and Service child backend adds to the top-level Oracle Cloud Applications backend and has vb-catalog://backends/fa/crmRestApi/resources as its server URL.
Child backends can be created only for the Oracle Cloud Applications backend and custom backends that use a OpenAPI/Swagger service specification.
- To create a child backend for the Oracle Cloud Applications backend:
- Click the + sign for the top-level Oracle Cloud Applications backend:
- Enter the instance URL for the child backend (for example, vb-catalog://backends/fa/applcoreApi/search/). The child backend's URL will usually start with
vb-catalog://backends/oracle-cloud-app-BackendId.Tip:
To see the complete URL that the backend resolves to, click Detach:
- Click the + sign for the top-level Oracle Cloud Applications backend:
- To create a child backend for a top-level custom backend:
- Click the + sign for a top-level custom backend:
- Click the + sign for a top-level custom backend:
Edit a Backend
If you want to modify an existing backend for a single application, you can override the backend's settings specified at the tenant level for your Visual Builder instance.
When you override a backend's settings in your application, you are essentially adding a backend with the same ID from the environment catalog to the application catalog and customizing some detail (for example, the authentication mechanism specified for a backend server) just for that particular application.
To edit and customize a backend service:
- Select the backend you want to modify, then click the Servers tab.
Tip:
Click the View Information icon (
) to view backend details, such as server and authentication inherited from your Visual Builder instance's tenant-level settings.
Add Server Variables for Backends
When creating or editing a backend, you can add server variables to the instance URL in the Servers tab.
When you enter a valid URI template expression, such as {version}, in an instance URL, a server variable will be created automatically and displayed in the Server editor's Server Variables section. You can also create, edit, or reorder a list of variables. A default value must be set for each server variable.
https://restcountries.com/v3.1/lang/german as an example:
- The server instance URL can be represented as
https://restcountries.com/{version}/lang.Here, there's just one server variable,
{version}, which has a default value of v3.1, as shown in the server of a backend called countryBackend:
Description of the illustration backend-edit-server.png - The endpoint is
/{language}.We define the service connection on the countryBackend by defining the endpoint and adding
/{language}to the URL path.
Here,languageis a path parameter, because it's a part of the endpoint path. It can't be a server variable, in this example, because it's outside the instance URL. Its default value isgermanand its type is string. - The full URL becomes
https://restcountries.com/{version}/lang/{language}.After substituting (v3.1 for the server variable
{version}and german for thelanguagepath parameter), this represents the instance URL we started with,https://restcountries.com/v3.1/lang/german.
- Click Edit
to the right of the server instance to which you want to add a new server variable (or modify an existing one) to the instance URL.The Edit Server dialog is displayed. - Enter a description in the Description field and set the default value in the Default field.Click Done if you are finished or click + Add Value to add another value. To create a list with multiple values, click Menu
and select Create Value List. Then, after adding values, use the 
or 
controls to set the default value or reorder the list of values. The default value will be the one at the top of the list. You can use Delete 
to discard values you don't need.
Edit a Backend Server's Authentication Details
After a backend is created, you can edit the server's authentication details from the Servers tab.
You might want to edit the authentication details when the authorization requirements of your app change, for example, if you you need to override the settings for the backend service. If you have multiple servers added to your backend, you may need to make changes in more than one server.
- Click the Edit icon beside the server instance you want to edit:
- (Optional) Select Allow anonymous access to the service connection infrastructure and select the authentication mechanism for anonymous users in the Authentication for anonymous users drop-down list.
Create a Service Connection
You can create service connections by selecting a service in your catalog, by providing a specification document for a service, or by providing the location of a service endpoint. After specifying the service you want to use, you can select which service endpoints you want to expose.
You can create service connections to REST services that support both the OpenAPI 3.0 and Swagger 2.0 specifications. If the service description that you use to create the service connection includes an error, Visual Builder displays it.
Your service connection can be derived from an existing backend (either predefined or custom) or you can register a backend when you create a service connection. To re-use existing backends, choose from a list of existing backends that is displayed based on what you enter in the URL, as shown here:
You'll see this list when you register service connections via a service specification document or an endpoint URL. For connections to services in a catalog, the backends list appears only when you choose custom backends registered by specifying a service specification document.
Note:
All URLs in backends and service connections should be HTTPS with a valid certificate.
Create a Service Connection from the Catalog
You create a connection from the catalog when you have access to at least one of the backends in the catalog, namely Oracle Cloud Applications, Oracle Integration, or a custom backend.
Creating a connection to a service from the catalog saves you time, as common configuration tasks like authentication, connection type, and headers are predefined for you, so you can browse through the various endpoints available in a particular backend service.
The catalog is automatically populated with a list of services and endpoints available to you from your associated Oracle Cloud Applications, Integrations, or other backend server instance. Custom backends are also listed, enabling you to create a service connection based on that backend either by providing a service specification or by specifying an endpoint URL. For details on how to create a custom backend, see Create a Custom Backend.
Note:
For App-Driven Orchestration integrations with Visual Builder, use integrations that have a published REST specification, Active status and a /metadata endpoint. You can also de-activate, then activate the integration, and it will be visible in the catalog.To access a service that isn't listed in your catalog, you can create the service connection by using a service specification (ADF BC REST, OpenAPI/Swagger) or by specifying an endpoint URL.
-
You have supplied all the details for a given backend service including base URL, required headers, authentication, and connection type. If you are connecting to an Oracle Cloud Applications or Integrations service instance, use the Backends tab in the Services pane to check the URL and authentication mechanism in the backend service.
-
You are authorized to access the service with your credentials. Contact the service's administrator to confirm that your credentials are authorized.
-
The service is currently available. Check the connection status of the service manually using a tool such as cURL or Postman.
To create a connection to a service in the catalog:
- Click Select from Catalog in the Select Source step of the Create Service Connection wizard:
- Click the tile for the service catalog you want to browse:
- Add a Service Name, and select the REST endpoints you want to add from the list of endpoints available for each resource provided by the service.
- If you want your endpoint definitions to be stored in your visual application's sources, select Copy full OpenAPI to the application in the Metadata Retrieval Option drop-down list, then select the endpoints that you require for your application. This way, you create a static service connection:
Description of the illustration service-connections-create-catalogendpoints.bmp
Tip:
You can select a top-level object to select all endpoints for that object, or select individual endpoints to improve performance. - If you want your endpoint definitions to always be dynamically retrieved from the service metadata, select Dynamically retrieve metadata in the Metadata Retrieval Option drop-down list, then select the top-level resource that you require for your application. This option changes the resource selection to include complete objects instead of individual endpoints:
Note:
For ADF Describe-based services, the recommended option for metadata retrieval is Copy minimal OpenAPI to the application (default). This option is a happy medium between copying the full OpenAPI endpoint definition to your application's sources and always retrieving the OpenAPI definition from the source URL. It copies a minimal OpenAPI definition for the endpoints you select and dynamically retrieves the request/response schema only when required. - If you want your endpoint definitions to be stored in your visual application's sources, select Copy full OpenAPI to the application in the Metadata Retrieval Option drop-down list, then select the endpoints that you require for your application. This way, you create a static service connection:
After a service connection is created, you can select it in the Navigator to open the connection in the editor and edit the endpoints associated with the service and other connection details.
Here's a view of endpoints in a static service connection:
Description of the illustration service-connections-editortabs.bmp
If you chose to automatically include lists of values, Visual Builder creates additional endpoints (as shown above) to provide access to the data that you may require in your web (or mobile) application for LOVs.
Here's a view of endpoints in a dynamic service connection:
Description of the illustration service-connections-editortabs-dynamic.bmp
The connection details are generated automatically. You should exercise caution when editing the connection details to avoid changing details that would cause the connection to fail.
Create a Service Connection from a Service Specification
You create a connection from a service specification when you know the URL of the OpenAPI/Swagger or Oracle ADF Describe file that describes the service. You can also upload the specification file from your local system.
To create a connection from a service specification:
- Click Define by Specification in the Select Source step of the Create Service Connection wizard:
- Enter a name for the connection in the Service Name field.
The name you specify will be the connection's display name in your application. - Select the location of the Service Specification document.
- If you're creating a service connection to an Oracle Cloud Applications REST API (for example, CRM, FSCM, HCM), select Web address, click the URL text box and select the appropriate backend to fill in the service description's URL.
Then type in the rest of the Describe URL to the resource using this format:<backend URL path>/<REST-API-version>/<resource-name>/describeFor example, for the HCM absences resource, you'd add
/11.13.08.05/absences/describeto the selected HCM URL in the text box, where 11.13.18.05 is the REST API version.
To ensure that the metadata is cached efficiently, specify the actual REST API version (for example, 11.13.18.05) instead of using “latest” for the version. To figure out the latest REST API version, consult the product's Oracle Cloud Applications REST API documentation.
Tip:
To specify multiple resources (for example, both contracts and expenses), you'll need to use a slightly different URL. Use this format if you're specifying the contracts and expenses resources:<backend URL path>/<REST-API-version>/describe?resources=contracts,expenses - If you have an external URL representing the service specification (for example, an OpenAPI3 URL), select Web address and enter the service descriptor's URL in the URL field.
If you're using an IP address instead of a proper DNS-based URL in a production environment, you're probably using self-signed certificates. Certificates based on IP addresses are less secure and more difficult to maintain than DNS-based ones. To avoid potential security issues, self-signed certificates should never be used in production environments. An audit warning will be displayed whenever you use an IP address-based service connection.
- If you have a document that contains the service specification, select Document, then either drag and drop the file that describes the service from your local system to the dialog or use the file browser to locate and select it on your system.
Note:
If the service specification URL does not match an existing backend, you will need to create a new backend. Instructions for creating a new backend from a service specification URL are covered in a later step. - If you're creating a service connection to an Oracle Cloud Applications REST API (for example, CRM, FSCM, HCM), select Web address, click the URL text box and select the appropriate backend to fill in the service description's URL.
- Select a Metadata Retrieval Option.
If you entered a web address, you can select Dynamically retrieve metadata to create a dynamic service connection that always pulls in the most up-to-date service definition for your application or you can select Copy full OpenAPI to the application to copy the complete service metadata during development and statically store it in your visual application's sources.
If your API type is ADF Describe, you may want to select Copy minimal OpenAPI to the application (recommended) to copy the minimal metadata for the endpoints you'll select in the next step and dynamically retrieve the request/response schema, when required.
- If you did not have a backend to match your service specification URL, add service connection details as needed, then create a backend:
- Update the Security and Connection Type settings as needed.
- Click Create Backend.
- In Backend URL, use the slider to specify which part of the URL you want to use for the backend.
- Add a name and optional description for the backend.
- Update the Security and Connection Type settings for the backend as needed.
- Click Next and select the resources and endpoints you want to add.The Select Endpoints pane displays a list of the endpoints and child objects available for each resource provided by the service.
- Select a top-level object to select all endpoints for that object or expand the top-level object node and select individual endpoints to improve performance.
- Select a top-level object to select all endpoints for that object or expand the top-level object node and select individual endpoints to improve performance.
After creating a service connection, you can select it in the Navigator to open the connection in the editor and edit the endpoints associated with the service and other connection details.
- From the Endpoints tab, select one of the resource's methods to test.
- Go to the Test tab and, under Response, enter an integer for a query parameter.
- Click Send Request.
- Check the Send Request status. A status of 200 indicates success.
Create a Service Connection from an Endpoint
You can create a connection from an endpoint when you know the base URI of a service and can provide the necessary parameters for connecting to the service, such as authentication details and an example of the Response body.
To create a service connection from an endpoint's URL:
- Click Define by Endpoint in the Select Source step of the Create Service Connection wizard.
- Select the HTTP method and enter the endpoint
URL.
Note:
If you're using an IP address instead of a proper DNS-based URL in a production environment, you're probably using self-signed certificates. You need to be aware that certificates based on IP addresses are less secure and more difficult to maintain than DNS-based ones and, to avoid potential security issues, self-signed certificates should never be used in production environments.An audit warning will be displayed whenever you use an IP address-based service connection.
If you know what type of action you want to perform, select it in the Action Hint drop-down list. For example, if you select a GET method, you can choose Get Many to retrieve multiple records.
Description of the illustration service-connections-create-specifyendpoint.bmpIf an existing backend match is found, the URL will fill the field automatically; otherwise, you will need to create a new backend. See the following step for more details.
When you're done, click Next.
- If you did not have a backend to match your service specification URL, click Create Backend.
- In Backend URL, use the slider to specify which part of the URL you want to use for the backend.
- Add a name and optional description for the backend.
- (Optional) Change the Security and Connection Type settings for the backend.
- Click Next.
- In Backend URL, use the slider to specify which part of the URL you want to use for the backend.
- Click the Request tab to add headers and URL parameters to the
request.
Depending on the endpoint, you might want to add custom headers or path or query parameters that are passed as part of the request.
- Click the Response tab and enter the response body for the endpoint.
The Response tab displays the media type's OpenAPI3 metadata artifacts that can be represented: the example and the schema. You paste in an example of the body of the response into the text area and then click the Save Example button to commit your input or click the Reset button to clear it and start over. These buttons will stay disabled until you add or edit the example text.
Description of the illustration vb-response-example.pngAfter you click the Save Example button, your new example content is saved, the schema is generated, and the Type Structure panel displays.
If you don't have an example to add, you can use the Test tab to send a request to the service, then save and use the response that is returned as your example (or edit it as needed) in the tab's text area.
Note:
The panels you see in the Response tab are determined by the presence or absence of the example and the schema:- If neither the schema nor the example exist, such as when you're creating a new service by using the Define by Endpoint flow in the wizard, the tab displays just the Example text area.
- If you arrive at a tab for an existing service whose endpoint already has the schema and example defined, the Type Structure panel and the Example text area are both displayed.
- You may also encounter cases where existing endpoints have a schema defined, but there is no example. In most of these cases, it's either undesirable or potentially detrimental to include the Example text field on the page, so a placeholder panel with a boilerplate message that says there is no example is displayed instead.
- Click the Test tab to test your request (based on the settings in the other tabs) and view the response from the endpoint.
Click Send Request to view the Response body and headers and confirm the data that you expect to receive.
You can experiment with different request parameters until you achieve the response you want. If your response returns an error, check the details of your connection, for example, ensure that you're using the correct credentials or that the service uses a valid SSL certificate.
Tip:
After you add an endpoint from the service, you can add more endpoints from the same service by clicking + Endpoints in the Endpoints tab of the connection. For example, defining a Get Many endpoint is enough if you only want to view records, but you'll need to create more endpoints to create, edit, or delete records.Edit a Service Connection
After you create a service connection, you can edit the service connection, for example, to add and remove endpoints, modify requests, and add functions for filtering and sorting responses.
For each of your service connections, you can use the following tabs in the connection editor to view and edit the connection’s details. What you see depends on whether your service connection is static or dynamic:
| Tab | Description |
|---|---|
| Overview |
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 |
If a service connection was created with an association to a backend, the backend is displayed. If a service connection was created without an association with a backend, this tab displays one or more servers 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:
Tip: In server dialogs, you can use the Show Full URL option to see what the URL resolved to for each profile. Each server entry shows the server description, the resolved URL (with query parameters, if any), and associated profiles. If the default profile is associated with a server, that server will be highlighted. |
| Headers |
Displays the headers written in the REST call to the service. You can add and edit headers in the tab. |
| Transforms |
Displays the
|
| Source |
Displays the OpenAPI 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. |
| Endpoints |
|
| Metadata | For a dynamic service connection, displays a read-only view of service metadata contained in the openapi3.json file, dynamically retrieved from the source URL.
|
Add a Server to a Service Connection
After you create a service connection, you can add more servers that host the same REST service to the service connection. Used in conjunction with application profiles, this can simplify the development, testing, and publication of apps that consume the REST service.
Note:
For service connections created after the 23.10 release, servers must be added from the backend associated with the service connection. For more information, see Edit a Backend.For example, you might add a development server that hosts an instance of the REST service where non-customer data is used, and an authentication mechanism like basic authentication is acceptable. This development server can be used to develop your application, but once you publish it to production, your apps need to connect to the REST service using a production server with more stringent authentication requirements and access to customer data.
- Open the Servers tab of the service connection where you want to add the server:
The first server in the List of Servers is the default server. It will be associated with all application profiles unless you configure the other servers in the list to use another application profile.
Edit Service Endpoints for a Static Service Connection
After you create a service connection and select the service endpoints, you can edit the endpoint settings, request parameters, and the response for each endpoint in the Endpoints tab. Endpoints can be edited only for static service connections (identified by the 
icon that appears in front of the service name).
If you edit an endpoint after you have created a type from it, you will need to manually edit the type to use any of the changes to the endpoint. A type created from an endpoint is not updated automatically when the endpoint is modified.
To edit a service endpoint:
- Open the Endpoints tab of a service connection.
Description of the illustration service-connections-editortabs.bmpTip:
You can use the Replace button to update the service definitions of all selected endpoints with the latest definitions from the service. The Replace button is available when the service connection is registered via the Catalog or a service specification document. This capability is available for both OpenAPI3 style services as well as ADF Describe services:
Description of the illustration service-connections-replace-endpoints.pngFor static Integrations service connections, using the Replace button lets you update all endpoint definitions without manually creating a new connection and deleting the old one. When you see the confirmation dialog, click Replace to proceed.
- Click the endpoint you want to edit.
For each endpoint, the editor provides tabs for editing the endpoint’s settings, the request sent to the endpoint, and the structure of the response.
Description of the illustration service-connections-edit-endpoints.pngIf your service connection was created from an OpenAPI3 specification that includes request and response examples specified in the example or examples keys, the examples will show up within the Request and Response tabs.
The examples key takes precedence over example and if multiple examples exist, only one will be shown. If you created an example where one didn't exist (say, if you used the Test tab to send a request to the service and saved the response as an example), that's the example you'll see; otherwise, you'll see the first example in the examples key list.
Retrieve Service Metadata for a Dynamic Service Connection
After a dynamic service connection is created, you can retrieve the service's most recent metadata for your application to use the latest service definition.
- Open the Overview tab of a dynamic service connection:
The Metadata Retrieval section defines the method and URL to be used to retrieve the OpenAPI document that describes the REST APIs for the dynamic service connection. In the example shown here, the GET method is used to fetch the most recent ADF Describe available on the
vb-catalog://backends/fa/crmRestApi/resources/latestserver.
Add Server Variables for Service Connections
After creating a service connection, you can go to the Servers tab and edit the server's instance URL and add server variables.
Note:
For service connections created after the 23.10 release, server variables must be updated from the backend associated with the service connection. For more information, see Add Server Variables for Backends.When you enter a valid URI template expression, such as
{version}, in an instance URL, a server variable will be
created automatically and displayed in the Server editor's Server
Variables section. You can also create, edit, or reorder a list of
variables. A default value must be set for each server variable.
https://restcountries.com/v3.1/lang/german as an example:
- The server instance URL can be represented as
https://restcountries.com/{version}/lang.Here, there's just one server variable,
{version}, which has a default value of v3.1, as shown:
Description of the illustration server-variable-example.png - The endpoint is
/{language}.Here,
languageis a path parameter, because it's a part of the endpoint path. It can't be a server variable, in this example, because it's outside the instance URL. Its default value is german and its type is string. - The full URL becomes
https://restcountries.com/{version}/lang/{language}.After substitution (v3.1 for the server variable
{version}and german for thelanguagepath parameter), this represents the instance URL we started with,https://restcountries.com/v3.1/lang/german.
- Click Edit
to the right of the server instance to which you want to add a new
server variable (or modify an existing one) to the instance URL.The Edit Server dialog is displayed.
- Enter a description in the Description field and set the
default value in the Default field.Click Done if you are finished or click + Add Value to add another value. To create a list with multiple values, click Menu and select Create Value List. Then, after adding
values, use the or controls to set the default value or reorder the list of values. The
default value will be the one at the top of the list. You can use
Delete
to discard values you don't need.
Tip:
There's a new Server Variables tab in the Endpoint editor's Test tab. You can use this tab to test the value of server variables when you're testing an endpoint. With a defined value list, you can effectively change the URL and test each version. The process for using this functionality is very similar to what was described here.Add More Endpoints to a Service Connection
After you create a service connection, you can add more endpoints. For a static service connection, you can add endpoints from the same source or add custom endpoints.
- To add endpoints to a static service connection:
- Open the Endpoints tab of a static service connection:
- Click + Endpoint. If your service connection was created for a service from the catalog, select Custom or From original_service in the drop-down list:
- Select or define the new endpoint in the Add Endpoint dialog box. Your options depend upon the type of service connection and if you choose Custom or From original_service.
For example, if your service connection was created for a service from the catalog and you choose to add an endpoint from the original service, you can choose from the list of endpoints available in that service.
If your service connection was created from an endpoint, you will need to specify details about the request and response to add a new endpoint from the same source, as shown here:
Description of the illustration service-connections-edit-addendpointdb.png
- To add endpoints to a dynamic service connection:
- Open the Endpoints tab of a dynamic service connection:
Edit a Server's Authentication Details
After a service connection is created, you can edit the server's authentication details from the Servers tab.
Note:
For service connections created after the 23.10 release, server authentication details must be updated from the backend associated with the service connection. For more information, see Edit a Backend Server's Authentication DetailsYou might want to edit the authentication details when the authorization requirements of your app change, for example, you need to allow anonymous access to the service or you need to override the settings for the backend service. If you have multiple servers added to your service connection, you may need to make changes in more than one server.
To edit a service's authentication settings:
- Click the Edit icon beside the server instance you want
to edit:
- (Optional) Select Allow anonymous access to the Service Connection Infrastructure and select the authentication mechanism for anonymous users in the Authentication for anonymous users drop-down list.
Add Transforms
Transforms are JavaScript functions that transform the format of data and parameters for REST requests and the format of data from REST responses. Request transforms are typically for sorting, filtering, and so on, while response transforms are typically for formatting data and retrieving paging metadata. Transforms can be defined at service connections, backends, and service connection endpoints. You can write custom JavaScript functions to interpret requests to and responses from the service.
- Filtering, which defines filter operations that specify the data to be returned and displayed in the REST client.
- Sorting, which specifies how to sort items that were returned from a collection resource.
- Pagination, which limits the number of records that are displayed on a page in the REST client.
Transforms can be used to modify the input to the server and, optionally, the output on a function-by-function basis. A service connection's transforms file can be inherited, or you could choose a different .js file to use as the service connection's transform, or you may want to create a new .js file, choosing the functions you want to override.
Note:
When you are working with Oracle Cloud Application endpoints, the built-in business object REST API transforms are set up automatically when you create the service connection, except when you define a service connection via an endpoint.If your service connection was defined through an endpoint, you'll need to edit the connection and add a transform function.
A transform can be:
- A require JS module, such as vb/BusinessObjectTransforms
- A file path that's relative to the service connection, such as
./transforms.js - A URL, such as
https://cdn.oracle.com/static/vb/businessobjecttransforms
Specific transform functions can be replaced on the Call REST action or the SDP.
Some types of backends, such as ADF Describe backends, have pre-defined transforms that are applied by default. Another example is vb/BusinessObjectTransforms, the default transform for an Oracle Cloud Applications backend.
- Service Level Transforms: Implemented for a backend, a service connection or a particular service connection endpoint.
- Instance Level Transforms: Implemented for a Service Data Provider (SDP) or a Call REST action. For details, see Transform within Call REST Action in the Oracle Visual Builder Page Model Reference.
For the sake of consolidation and simplification, it is recommended that only service level transforms are used.
For business objects, custom transforms are not required since Visual Builder’s out-of-the-box (OOTB) transforms are preconfigured with the service, but should they be, use instance level transforms. The remaining information here is in regard to service connections.
For service level transforms, they are typically defined in the backend (example: Visual Builder provides a set of standard transforms called BusinessObjectTransforms). However, if you need to differentiate between the REST resources or between the endpoints (GET vs POST) of a system, you can provide transforms for the service connection or for the service connection’s endpoints.
To see the provided template transform functions, click the Go to File link in the Transforms section of the Overview or Endpoints tab of a service connection.
Description of the illustration jsac-service-connection-transforms-file.png
Regarding the hierarchy of service level transforms, an endpoint is first checked for a transform file, then the service connection, and lastly, the backend. The first found transform file is used and any at upper levels are ignored.
Example of Creating Service Level Transforms
These steps show how to create a backend for service connections and how to create the file with the template transform functions for your new backend and its service connection endpoints:
- Open the Services panel, select the Backends tab, click the Add (+) icon and select Backend:
- In the Create Backend window, select Custom to create a custom backend.
- Provide a name for your custom backend, and optionally, enter its description.
- Enter the instance URL and any other required details. Later, when creating a service connection for the backend, this URL is used as the base for defining the endpoint. Click Create to create the backend.
- You can now create the file with the template transform functions for your new backend. On the Overview tab, in the Transforms section, click the Source field’s down-arrow and select Create:
- Provide the file name for the transforms file:
- For the Base transform dropdown, select the file to supply the base code for all of your transform functions. For ADF REST APIs, this file is always chosen for you.
- In the Override functions select the function(s) you want to add to the transforms file and click OK. Functions that you don't select won't be added to the transforms file.
- To open the transforms file, click Go to File under the Source field:
- Override the relevant transform functions as required. The provided built-in transform functions are: sort, filter, paginate, select, query (commonly used with GET collection endpoints), body (commonly used with POST and PATCH endpoints), and fetchByKeys.
The
transformsContextinput parameter is a context object that is passed to every transform function by the associated SDP, so that you can retrieve and store contextual information for the current REST call. SDP variables have a transformsContext property that is passed to the transform functions. For more about an SDP'stransformsContextproperty, see Oracle Visual Builder Page Model Reference - transformsContext SDP Property.Here's an example for the
body(result)transform function, which adds text to all of themassandheightfields:body(result) { let tr = {}; if (result.body) { tr = result.body.results; for (let i = 0; i < tr.length; i++) { tr[i].mass = tr[i].mass + " kilos (kg)"; tr[i].height = tr[i].height + " cm"; } } // return tr; }The created transforms file is inherited by its related service connections, which are created by using the + Service Connection button on the Overview tab. To view the related service connections, click the Load related service connections link:
Description of the illustration jsac-backend-related-services.jpgFor details about creating a service connection from an endpoint, including how to get an example of the body of the response, see Create a Service Connection from an Endpoint.
- To add a related service connection for your backend, click the + Service Connection button:
- Complete the URL for the service connection endpoint and provide the required details.
- To create a transform file for the endpoint, click the Source field’s down-arrow and select Create:
- To open the transforms file, click Go to File under the Source field.
Examples for Endpoints that Are Not from Oracle Cloud Applications
- Request
- A request transform function is called right before a request is made to the server/endpoint. It provides a chance for page authors to transform the options (filter, paginate, sort, and so on) and build the final request configuration. Here are some samples of how to write filter, paginate, and sort transform functions:
- filter
/** * Filter Transform Function Implementation * @param configuration * @param options the JSON payload that defines the filterCriterion * @param context an object to store/retrieve any contextual information for the * current request lifecycle * @returns {object} configuration object. the url looks like ?filter=foo eq 'bar' */ PageModule.prototype.filter = function (configuration, options, context) { const c = configuration; const filterCriterion = options; function jetFilterOpToScim(fop) { switch (fop) { case '$eq': return 'eq'; case '$ne': return 'ne'; case '$co': return 'co'; default: console.warn('unable to interpret the op ' + fop); return null; } } function isEmpty(val) { return (val === undefined || val === null || val === ''); } if (typeof filterCriterion === 'object' && Object.keys(filterCriterion).length > 0) { if (filterCriterion.op && filterCriterion.attribute && !isEmpty(filterCriterion.value)) { const atomicExpr = {}; atomicExpr.op = jetFilterOpToScim(filterCriterion.op); atomicExpr.attribute = filterCriterion.attribute; atomicExpr.value = filterCriterion.value; if (atomicExpr.op && atomicExpr.attribute) { c.url = URI(c.url).addQuery({ filter: `${atomicExpr.attribute} ${atomicExpr.op} ${atomicExpr.value}`, }).toString(); } } } return c; };- paginate
// paginate Transform Function // Transform function appends limit and offset parameters to the URL PageModule.prototype.paginate = function (configuration, options, context) { const c = configuration; let newUrl = c.url; newUrl = `${newUrl}&limit=${options.size}&offset=${options.offset}`; c.url = newUrl; return c; };- sort
/** * Sort Transform Function Implementation * @param configuration * @param options the JSON payload that defines the sortCriteria * @param context an object to store/retrieve any contextual information for the * current request lifecycle. * @returns {object} configuration object. the url looks like ?orderBy=foo:asc */ PageModule.prototype.sort = function (configuration, options, context) { const c = configuration; if (options && Array.isArray(options) && options.length > 0) { const firstItem = options[0]; if (firstItem.name) { const dir = firstItem.direction === 'descending' ? 'desc' : 'asc' let newUrl = c.url; newUrl = `${newUrl}&orderBy=${firstItem.attribute}:${dir}`; c.url = newUrl; } } return c; };
- Response
- A response transform function is called right after a request returns successfully. Here is a sample of how to write a paginate transform function:
// paginate() Response Transform Function PageModule.prototype.paginateResponse = function (result, context) { const ps = {}; const tr = {}; if (result.body) { const rb = result.body; if (rb.totalCount) { tr.totalSize = rb.totalCount; } if (rb.totalCount > 0) { tr.hasMore = !!rb.hasMore; } else { tr.hasMore = false; } } return tr; };
Convert a Service Connection (Static to Dynamic or Dynamic to Static)
You can convert an existing service connection, either from static to dynamic or dynamic to static, to suit your application's requirements that may change over the course of its lifecycle.
Typically, it's useful to create a dynamic service connection during an application's development stage, when endpoints defined in the service metadata are still evolving. A dynamic connection fetches the service's OpenAPI3 metadata from the source URL whenever the app is opened, enabling your application to get all the updates included in the current version of the metadata. When you deem the service metadata to be stable and your application ready for production, you might want to switch the dynamic service connection to static—because while dynamic connections provide the most recent updates, they may impact performance. A static connection, on the other hand, has better performance because the service metadata is part of your application's code.
Conversely, if your application's service metadata is changing and you want to include these updates as you work on your app, you can convert your static service connection to a dynamic one. In this case, the service metadata is copied from the source URL and saved to the application's sources.
For ADF Describe services, however, always choose the recommended option for optimal runtime performance. This option copies minimal service metadata for the endpoints you select from the source URL to the application and dynamically retrieves the request/response schema when required. It provides the benefits of a static and a dynamic service connection and is recommended for both static and dynamic ADF Describe-based service connections: 
- To convert your service connection to dynamic:
- Open the Overview tab of a static service connection, then click the dynamically retrieving metadata link.
- In the Edit Service Connection dialog box, notice the Dynamically retrieve metadata option that's selected. You'll also see a message about the number of endpoints that will be added to the connection. Remember that dynamic service connections always include whole resources, rather than individual endpoints.
If you want all LOVs for the selected objects/endpoints in an Oracle Cloud Applications catalog to be automatically included in the service metadata, select Automatically include list of values (LOV).
- To convert your service connection to static:
- Open the Overview tab of a dynamic service connection, then click the copying full OpenAPI link.
- In the Edit Object Selection dialog box, select the endpoints you want to use in your application.
Notice the Copy full OpenAPI to the application option that's selected and a message about the number of endpoints that will be removed from the connection.
Test Service Connection Responses
You can configure a POST/PATCH/PUT REST API with application/octet-stream or multipart/form-data format and test it from the service connection's endpoint's Test tab before proceeding with it. You can also use the form-data's schema when you call the REST endpoint.
You can access this functionality from two places, where you can use radio buttons to select the payload type to test:
- From the Body tab under the Endpoint editor's Request tab:
- From the Body panel under the Test tab:
In both screenshots, the Text payload option is selected. The body input area beneath the radio buttons looks and operates the same way it has in all prior releases.
Test Responses Using the Form Data Option
When you select the Form-Data payload option, the Media Type is automatically changed to multipart/form-data and you're presented with a form for defining input elements that provide the data values in a multipart request body:
Two types of input elements can be created:
- String, for providing a user-entered text value.
- File, for selectiing a file to provide a binary data value.
As elements are added to the form, corresponding properties will be added to the media type's schema in the OpenAPI metadata:
When the request is submitted from the Test tab, the names and values of the inputs are used to generate a FormData object that defines the multipart payload.
When form elements are created and displayed in the Request tab, the input elements themselves (that is, the text field or file picker) aren't rendered, because testing and submitting the form data can't be performed in this context:
Test Responses Using the Binary Option
When you select the Binary payload option, the media type defaults to application/octet-stream, although you could manually enter any binary content type you want:
After you click the Create Binary-Compatible Schema button, the corresponding schema will be generated.
After the schema has been created, you can use the file picker to select the file that'll be used as binary payload when the request is submitted:
The file picker for the Binary payload type isn't shown in the Request tab:
Instead, a message indicates that the schema has been created.
Service endpoints support downloading binary or text responses in the endpoint's Test tab. You can use the Download button to save the response body. If the response is non-text, you'll see a message that tells you that the response body contains binary data:
You can also use the Download button to download or save text responses:
Update Schema of the Request or Response
If there have been changes to the schema of the request or response, you can follow either of these three procedures to update it:
- Option 1: Open the Request or Response tab and supply a new example body representing the schema. A notification, near the bottom of the window, will notify you of the schema’s successful update.
- Option 2: Open the Source tab, which uses the openapi3 specification and JSON format, and edit the schema (or other details) directly.
- Option 3: Open the Test tab, and in the Request section, ensure the URL for the request is correct. If it isn't, update the request using the Request tab. Click the Send Request button to get the response. In the Response section, on the Body tab, click the Save as Example Response button to update the response schema. A notification, near the bottom of the window, will notify you of the schema’s successful update.
Configure Authentication and Connection Types for Service Connections and Backends
How you configure authentication for service connections and backends depends on the type of mechanism you want to use, as well as what the external service supports. Depending on the authentication you choose, an administrator might need to configure settings in Visual Builder, the external service, and Identity Cloud Service (IDCS).
Note:
For service connections created after the 23.10 release, server authentication types must be updated from the backend associated with the service connection.About Authentication and Connection Type
When you add a new server to or edit an existing server in a service connection or backend, you configure the authentication and connection type that your application uses with external services.
Note:
For service connections created after the 23.10 release, server authentication types must be updated from the backend associated with the service connection.The dialogs that allow you to add a server to a backend or edit an existing server in a service connection or backend, allow you to:
- Override authentication settings set at the tenant level
- Manage the credentials for accessing the service (if credentials are required)
- Manage identity propagation of the end user logged in to the web (or mobile) app (if the service supports the standard IDCS OAuth flows)
- Manage how your application connects to the service (via proxy or via Direct call)
- Manage how anonymous users can access the application
Note:
In some cases, an administrator might need to configure the Visual Builder tenant-level settings for backend services or the settings of the external service or identity provider before you can connect to the service.
Note:
Visual Builder does not support service connections that use the TLS 1.3 encryption protocol. You'll need to either configure the server to use TLS 1.2, or configure the server for CORS and use a direct connection from the browser to the service endpoint instead of using the proxy.
To connect to a service that is available on HTTPS, does not require authentication, and has no special CORS requirement, the default setting of None in the Authentication field is sufficient. In this case, any end user (anonymous or authenticated) of the web (or mobile) application will be able to access the service. Sending a request to a service that requires authentication will return an error if you do not provide the authentication details. The default connection type is Dynamic, the service supports CORS.
To connect to a service that requires authentication, you need to select the appropriate authentication option from the Authentication drop-down list.
Use additional application profile(s) to configure different authentication mechanisms to access a service during development, testing, and publication. If you use only the base configuration application, you’ll use the same authentication mechanism for all stages of your app development. Some mechanisms are better suited for app development, and in some cases you will want to change the authentication mechanism when you publish the app. You can select authentication mechanisms for logged in users (authenticated users) and non-logged in users (anonymous users). For a description of user roles, see Authentication Roles Versus User Roles.
The mechanism you select for authenticating communication with a service will depend on the type of authentication the service supports and the authentication mechanism you use in your web (or mobile) app. Additionally, whether your external service supports CORS or not can also affect the choice of authentication. The authentication mechanisms can be grouped into two types, grouped by whether the identity of the end user is passed on to the service (Identity Propagation) or not (Fixed Credentials).
How Does Authentication with Identity Propagation Work?
Authentication mechanisms that use identity propagation allow the identity of the end user that's signed in to the web (or mobile) app to be passed on to the service and used for authentication. These types of mechanisms cannot be used to authenticate anonymous access.
To use identity propagation, the service must be able to understand the IDCS identity token coming from Visual Builder and extract the user (or subject) from it. Visual Builder supports JWT tokens procured using OAuth 2.0 flows only.
Tokens are a way of encoding the calling user identity into a string according to different specifications like SAML or JWT format. If, for example, the user is John.Doe, the corresponding JWT token takes the format <header.body.signature> and looks like this:
Decoding the body of the token reveals details about the user identity and possibly the resources to which that user is allowed access. The signature part is encrypted by the authority that authenticated the user, and can be easily verified by using the authority's public key. A valid user's identity is encoded into the token so services (namely REST APIs) that receive this token can consider the user as authenticated. This token is usually passed to REST services by sending it as a bearer token. That's done by by passing "Bearer <token>" in the Authorization header.
These are authentication mechanisms that use identity propagation:
| Authentication Mechanism – Identity Propagation | Description |
|---|---|
|
Oracle Cloud Account |
Select this mechanism to communicate with Oracle Cloud
Applications services. When you select this mechanism, the user must
sign in with the credentials of a valid account in the Oracle
Identity Cloud Service (IDCS) that is associated with Visual
Builder. The user's identity is converted into a user assertion that
is then converted into an IDCS-issued JWT token for a scope that is
equivalent to the base URL of the service being called. For example,
if the service's URL is
|
|
OAuth 2.0 User Assertion |
Select this mechanism to call an external system's services that can be represented as a Resource app with a particular scope in Oracle Identity Cloud Service (IDCS). This also requires the user to sign with a valid Oracle Identity Cloud Service user account. As with Oracle Cloud Account authentication, the user's identity is first converted into an assertion, then into an IDCS-issued JWT token for the configured scope. The difference is that with this mechanism you can specify your own scope, rather than using the service's URL. For example, Connect to Oracle Content Management REST APIs Using Identity Propagation explains how to configure the connection to an external service (Oracle Content Management) and specify a scope of your choosing, based on what you need. |
|
Delegate Authentication |
This mechanism was previously called Propagate Current User Identity. With this mechanism, the service connection doesn't have its own authentication, but delegates the authentication to the web (or mobile) app that is calling it. The following apply:
Since the actual authentication used at runtime depends on the calling web app's security settings, it is only recommended for use with web apps that use OAuth-based implicit grant authentication. |
How Does Authentication with Fixed Credentials Work?
An authentication mechanism that uses fixed credentials passes a fixed identity to the service, ignoring the signed-in end user's identity or credentials. All requests sent from the app to the service use the same app id for authentication.
These are the authentication mechanisms that use fixed credentials:
| Authentication Mechanism — Fixed Credentials | Description |
|---|---|
|
None |
Select this for services that don't need authentication and don't accept Authorization headers. |
|
Basic |
Select this for services that require a fixed username and password for authentication. The signed-in user's credentials aren't used for authentication. This option uses the Visual Builder authentication proxy irrespective of the connection type you choose. Note: Basic authentication is not supported in US government realms.Due to the limitations of basic authentication, we recommend using this mechanism during development only. Here's why. Let's say that you set basic authentication with a particular username and password, and later need to revoke the basic authentication for one specific application, your only option is to revoke that particular user, affecting all applications that use basic authentication. OAuth-based methods use scopes (with the client identifier and client secret) to limit these scopes to offer you better control to manage your credentials. |
|
Client Credentials OAuth 2.0 |
This mechanism is the recommended option if you want to use a Fixed Credentials mechanism and the service supports OAuth 2.0. This mechanism is part of the OAuth 2.0 grant types that are used when you don’t need a specific user’s credentials to connect to the service. Consult the service’s OAuth 2.0 documentation for the values for the Client Id, Client Secret and token URL fields. If no values are supplied, they will be interpreted as the visual application’s client id and secret, and the token URL will be interpreted as IDCS’s token URL. |
|
Resource Owner OAuth 2.0 |
This mechanism is part of the OAuth 2.0 grant types and used when you need a specific user’s credentials to connect to the service. Consult the service’s OAuth 2.0 documentation for the values for the Client Id, Client Secret and token URL fields. If no values are supplied, they will be interpreted as the visual application’s client id and secret, and the token URL will be interpreted as IDCS’s token URL. |
| Oracle Cloud Infrastructure API Signature 1.0 |
This mechanism uses a signature method to create an Application ID flow using a single Oracle Cloud Infrastructure (OCI) user to connect to OCI endpoints. All requests go through a proxy because of the requirement to sign the outgoing message. To use this authentication in Visual Builder, you'll need the following OCI user details from the OCI Console:
Once you have the details of the OCI user you want to use to connect to OCI endpoints, set up authentication in Visual Builder as follows:
|
).
What is CORS?
CORS (Cross-origin request sharing) is a mechanism that restricts a web page on one domain calling APIs hosted on another domain from browser-based JavaScript.
To allow such calls, the server hosting the APIs has to allow the domain of the web page to call by enabling CORS for the web page domain. The rules for CORS are built within the browser and are used to secure the user from arbitrary hosted scripts calling any APIs. See this blog for more details. If the API server has not enabled CORS for the web page, then calling the API via Fetch or AJAX from the browser results in a JavaScript error.
Use an Appropriate Connection Type to Handle CORS for REST Services
Web (or mobile) apps can call external REST services directly or through the Visual Builder proxy. The value you choose for the connection type and your choice of authentication method when you create or modify a service connection determines which option your app uses.
Direct calls
- Oracle Cloud Account
- Delegate Authentication
- OAuth 2.0 (all types)
- None
Calls via proxy
The Visual Builder proxy is a trusted server-side component that calls external REST services hosted on external domains on behalf of your app. One benefit is that you, or a system administrator, don't need to configure CORS settings for the external REST service. However, you incur the cost of an extra network call, as each request and response must first go through the Visual Builder proxy.
All authentication types can be used with the Visual Builder proxy. When you use some authentication types, such as Basic authentication and OCI Signature, authentication will always be routed through the Visual Builder proxy. (Note that the proxy will time out if the REST API doesn’t respond within 234 seconds.)
Connection type options
- Dynamic, the service supports CORS: Visual Builder decides the best route to connect to the external REST service assuming that the external REST service has enabled CORS for the Visual Builder domain. If the authentication supports direct calls (None, Oracle Cloud Account, Delegate Authentication, OAuth 2.0), then the external REST service will be called directly from the app.
- Dynamic, the service does not support CORS: Visual Builder decides the best route to connect to the external REST service assuming that the external REST service has not enabled CORS for the Visual Builder domain. All calls are routed through the Visual Builder proxy.
- Always use proxy, irrespective of CORS support: REST service calls from your apps always go through the Visual Builder proxy.
| Application type | Authentication type | Connection type | Result |
|---|---|---|---|
| Any | Any | Always use Proxy | Through Visual Builder proxy |
| Visual Builder Design time environment | Any | Dynamic – Service doesn’t support CORS | Through Visual Builder proxy |
| Web app running on browser | Any | Dynamic – Service doesn’t support CORS | Through Visual Builder proxy |
| Progressive Web App | Any | Dynamic – Service doesn’t support CORS | Through Visual Builder proxy |
| Any | All except basic authentication and OCI Infrastructure API Signature 1.0 | Dynamic – Service supports CORS | Direct |
| Any | Basic authentication or OCI Infrastructure API Signature 1.0 | Dynamic – Service supports CORS | Through Visual Builder proxy |
Here's an example of how different choices work when your application calls Sales and Service (CRM) REST APIs from an Oracle Cloud Applications instance. For this scenario, let's say your Visual Builder instance is hosted on vb.oracle.com and the crmRestApi is hosted on fa.oraclecloud.com.
If you chose Dynamic, the service supports CORS and the selected Authentication Type supports direct calls, the direct call goes like this: vb.oracle.com (browser) → fa.oraclecloud.com.
If you chose Dynamic, the service does not support CORS or Always use the Proxy, the call is routed through the proxy and goes like this: vb.oracle.com (browser) → vb.oracle.com proxy → fa.oraclecloud.com.
It's recommended that you use the Dynamic options, where Visual Builder Visual Builder decides the best route based on whether the external service supports CORS or not for this particular domain. However, you have the flexibility of choosing Always use the Proxy to route all requests via the proxy.
If you don't want to use the Visual Builder proxy, you must enable CORS in Oracle Cloud Applications for your particular domain (vb.oracle.com in our example) by adding the Access-Control-Allow-Origin CORS header for the CORS profile option. To view the profile option, go to the Setup and Maintenance work area and use the Manage Applications Core Administrator Profile Values task in the Application Extensions functional area. See Configure Cross-Origin Resource Sharing in REST API for Common
Features in Oracle Fusion Cloud Applications.
Work with HTTP-based Endpoints
Visual Builder uses HTTPS for its applications, and we recommend also using HTTPS for all service connections to external endpoints.
If you use an HTTP-based URL to create a service connection for development purposes, it will always be routed via the VB Proxy irrespective of the connection type and then to the actual HTTP service. This is because visual applications run on HTTPS and are not allowed to call an HTTP endpoint directly, that is using browser JavaScript. From the VB Proxy to the HTTP endpoint, the call is routed through HTTP. You will get a warning in the Server tab (shown below) when you provide an instance URL that uses HTTP.
Description of the illustration visual-app-httpwarning.png
Use of HTTP is discouraged because the credentials that access the HTTP service are visible over the network. These credentials are not encrypted, as in case of HTTPS). This makes HTTP services vulnerable.
Allow Anonymous Access to the Service Data
Select the Allow anonymous access to the Service Connection Infrastructure checkbox in the Edit Server dialog if you want to allow anonymous users access to the data from services.
If you allow anonymous access to the service data, you must also allow anonymous users access to the app. You enable anonymous access to the app in the Security tab of the app’s Settings editor. See Allow Anonymous Access.
Connect to Oracle Cloud Applications APIs
You can connect to Oracle Cloud Applications APIs using either identity propagation or fixed credentials.
Connect to Oracle Cloud Applications APIs With User Propagation for Authenticated Flows
To connect to Oracle Cloud Applications APIs using user propagation, the identity provider used by Oracle Cloud Applications and the IDCS used by Visual Builder must be federated.
Oracle Cloud Applications use their own identity provider (IdP), whereas Visual Builder uses IDCS only as its identity provider. The identity providers used by each service must be federated to establish a trust relationship. The list of users can be maintained in either identity provider, but not in both, but it is recommended that you use the Oracle Cloud Applications IdP, which can use SAML to provide additional integration with other identity providers.
In most cases, your Oracle Cloud Applications instance will already be federated to an IDCS instance, which also applies to the Visual Builder instance. If this isn't the case, an administrator will need to set up federation between the Oracle Cloud Applications and Identity Cloud Service instances by following the steps in this document: https://docs.oracle.com/en/cloud/paas/identity-cloud/idcsc/oraclefusionapplicationsrelease13.html.
If the federation has already been done, an administrator needs to go to the Services tab in the Tenant Settings page in the Visual Builder instance, and create an Oracle Cloud Applications backend service. See Add a Connection to Oracle Cloud Applications. The instance URL used for creating the backend service is the same as the Oracle Cloud Applications Base URL.
When creating the service connection, you use the following authentication mechanism:
| Authentication mechanism | Details |
|---|---|
| Oracle Cloud Account |
The default authentication and connection type for the service connection is determined by the backend service settings from which the service was added from the catalog. For example, if the service was chosen from the Oracle Cloud Applications > Sales and Service catalog, then the settings will be inherited from the backend representing Sales and Service. Typically, your service administrator will define the backend service settings in Tenant Settings. These settings can be overridden at the application level (with Application Backend Settings). You can choose to override these inherited settings by navigating to Services in the Navigator, then clicking Backends. You can:
|
To connect to Oracle Cloud Applications APIs with user propagation:
- Open Services in the Navigator, click the + sign, and select Service Connection.
- Click Select from Catalog in the Create Service Connection wizard.
- Click Oracle Cloud Applications and select an endpoint. Click Create.
- Test the service connection.
- Optional: If you want to make the service connection accessible to the application's anonymous users, click Override security, then select the Allow anonymous access to the Service Connection Infrastructure check box in the Edit Server dialog that you invoke from the Servers tab. Use the Authentication for anonymous users drop-down list to configure an authentication type for anonymous users.
Connect to Oracle Cloud Applications APIs Not in the Catalog Using Fixed Credentials
To connect to a service in an Oracle Cloud Applications instance that is not associated with your Visual Builder instance, you can create a connection using the credentials of a fixed user registered in the Oracle Cloud Applications instance.
To create the connection, you need to have the credentials of a fixed Oracle Cloud Applications user of the instance, or an administrator will need to create the Oracle Cloud Applications user with the necessary privileges for you. When you use this user to create the connection, all requests to the Oracle Cloud Applications REST APIs will use the fixed user's credentials. The credentials of the logged-in user are not used when communicating with the service.
Oracle Cloud Applications instances are usually associated with your Visual Builder instance in the Tenant Settings. If your instance is already associated with an Oracle Cloud Applications instance and you want to connect to a different instance in your visual application using the Service Catalog, you can open your visual application's Settings editor and override the Tenant Settings to edit the application's Oracle Cloud Applications instance settings. When you override the default instance settings, your application will not be able to access any services provided by the default instance because a visual application can only have one default Oracle Cloud Applications instance to populate the Service Catalog.
If you do not want to change the default Oracle Cloud Applications instance for your application, you can create a service connection by selecting the Define by Endpoint option in the Create Service Connection wizard.
When creating the service connection, you can use the following authentication mechanism for the service connection:
| Authentication mechanism | Details |
|---|---|
| Basic |
To use this option you need to provide the following details:
|
To connect to an Oracle Cloud Applications service that is not in your catalog:
Connect to Oracle Integration APIs
You can connect to Oracle Integration APIs using identity propagation or fixed credentials.
Connect to Oracle Integration APIs Using Identity Propagation
To connect to Oracle Integration using identity propagation, the Oracle Integration and Visual Builder instances should be in the same domain. If Visual Builder was provisioned with Oracle Integration, both services are accessible from the Oracle Integration home page and menu.
An administrator will need to confirm that the Oracle Integration URL is correct in the Visual Builder Tenant Settings. The Oracle Integration URL in the Tenant Settings should be similar to https://<Integration Cloud Instance full URL>:443 and the authentication mechanism should be Oracle Cloud Account. This will appear as the default URL and authentication mechanism in the visual application's Backends editor from the Navigator's Services tab. Using the Oracle Cloud Account authentication mechanism provides identity propagation from Visual Builder to Oracle Integration without any additional configuration.
When creating the service connection, you use the following authentication mechanism:
| Authentication mechanism | Details |
|---|---|
| Oracle Cloud Account |
The default authentication for the connection is determined by the authentication set in the Backends editor and in the Tenant Settings. You can view the connection details in the Backends editor that you access from the Navigator's Services tab. You can choose to override these inherited settings:
|
To connect to Oracle Integration APIs using identity propagation:
Connect to Oracle Integration APIs Using Fixed Credentials
To connect to Oracle Integration APIs using fixed credentials, you can choose to use either Basic Auth or OAuth 2.0 Resource Owner Password as the authentication mechanism.
To access the Oracle Integration APIs using fixed credentials, the Oracle Integration and Visual Builder instances do not need to be located in the same domain or governed by the same IDCS instance. Configuration is the same in both cases.
When you create the service connection in the Create Service Connection wizard, you choose the service by either selecting it in the Service Catalog or by defining its endpoint or specification. If you want to select a service from the catalog, you will first need to open the Backends tab from the Navigator's Services tab and override the tenant-level settings for Integrations and select the authentication mechanism you want to use instead of the default Oracle Cloud Account mechanism.
You do not need to override the tenant-level settings if you are defining the service connection by endpoint or specification in the Create Service Connection wizard. The authentication mechanisms are the same in both cases.
If you want to use OAuth 2.0 Resource Owner Password as the authentication mechanism, a service administrator needs to perform the following steps in the IDCS instance governing the Oracle Integration instance to get its Client ID, Client Secret, and Scope. These details are not needed when using Basic authentication.
- Open Applications in IDCS and locate the Oracle Integration application which frontends the Integration instance.
- Open the application and copy the Client ID and Client Secret in the General Information panel of the Configuration tab.
- Expand the Resources panel of the Configuration tab and copy the Primary Audience and the scope that corresponds to the REST APIs. These are combined to give the full scope, and might be similar to
https://<primary-audience-unique-id>.integration.ocp.oraclecloud.com:443/ic/api.
When creating the service connection, you can use either of the following authentication mechanisms:
| Authentication mechanism | Details |
|---|---|
| Basic |
To use this option you need to provide the following details:
|
| OAuth 2.0 Resource Owner Password |
To use this option you need to provide the following details:
|
If you do not have access to IDCS, you will need to request the connection details from an administrator if you want to use the OAuth 2.0 Resource Owner Password authentication mechanism.
To connect to Oracle Integration APIs using fixed credentials:
Connect to Process Cloud APIs
You can connect to Process Cloud APIs using identity propagation or fixed credentials.
Connect to Process APIs Using Identity Propagation
To connect to Process APIs using identity propagation, the Process and Visual Builder instances must be located in the same domain and use the same IDCS instance for authentication.
Using "Oracle Cloud Account" authentication provides identity propagation from Visual Builder to Process without the need for any additional configuration. No CORS configuration is required because the instances are in the same domain.
To connect to Process APIs using identity propagation:
Connect to Process APIs Using Fixed Credentials
To connect to Process APIs using fixed credentials, you can choose to use Basic Auth, OAuth 2.0 Client Credentials or OAuth 2.0 Resource Owner Password as the authentication mechanism.
For access to Process APIs using fixed credentials, the Process and Visual Builder instances do not need not be located in the same domain or governed by the same IDCS instance. The steps are the same if they use the same IDCS instance. When creating the service connection, you can use one of the following authentication mechanism for the service connection:
| Authentication mechanism | Details |
|---|---|
| Basic |
To use this option you need to provide the following details:
|
| OAuth 2.0 Client Credentials |
To use this option you need to provide the following details:
|
| OAuth 2.0 Resource Owner Password |
To use this option you need to provide the following details:
|
If you do not have access to IDCS, you will need to request the authentication details from an administrator if you want to use the OAuth 2.0 Client Credentials or OAuth 2.0 Resource Owner Password authentication mechanisms.
To connect to Process APIs using fixed credentials:
Connect to Oracle Content Management REST APIs
You can connect to Oracle Content Management REST APIs using identity propagation or fixed credentials.
Connect to Oracle Content Management REST APIs Using Identity Propagation
Oracle Content Management and Visual Builder are not provisioned together sothe service administrator needs to perform the following steps in IDCS to add Oracle Content Management as a resource of the Visual Builder application.
This adds Oracle Content Management as a resource to a specific application, so the administrator would need to perform these steps again for each new Visual Builder application, as well as for each new version of an application and duplicate of an application that connects to Oracle Content Management using identity propagation.
- In the Configuration tab for the Visual Builder application in IDCS, expand the Client Configuration panel, and click Add Scope in the Token Issuance Policy section.
- In the Select Scope dialog box, choose the scope corresponding to the Oracle Content
Management instance "/documents" endpoint and save the
application. The added scope should now be visible in the
Application in the Resources list.
If other Oracle Content Management functionality (for example, Social) is required, the corresponding scope will need to be added.
After the administrator has added the resource in IDCS, you can create a connection to Oracle Content Management with identity propagation. If you don't have access to IDCS, the administrator will need to provide you with the Oracle Content Management scope that you need to enter in the Authentication tab.
When creating the service connection, you use the following authentication mechanism for the service connection:
| Authentication mechanism | Details |
|---|---|
| OAuth 2.0 User Assertion |
To use this option you need to provide the following details:
|
To connect to Oracle Content Management:
Connect to Oracle Content Management REST APIs Using Fixed Credentials
To connect to Oracle Content Management using fixed credentials, the Oracle Content Management and Visual Builder instances do not need to be located in the same domain or governed by the same IDCS instance. You can use Basic or OAuth 2.0 Resource Owner Password authentication for the service connection.
If you want to use Basic authentication for the connection to Oracle Content Management, you need to provide a user name and password that are valid in IDCS.
If you want to use OAuth flows for authenticating your connection to Oracle Content Management, you need to retrieve details about the Client Secret, Client Id, and the URL associated with the scope that you want to access. Typically, the scope you will want to access will be "/documents", but if you want to access other Oracle Content Management functionality (for example, Social), you'll need the URL that corresponds to its scope. If you don't have access to the IDCS instance used by Oracle Content Management, you'll need to request the details from a user with access to the instance.
To retrieve the details of the Oracle Content Management application from IDCS:
- In the Configuration tab for the Oracle Content Management application in IDCS that
represents the Oracle Content Management instance,
expand the General Information panel and note the
Client Id and Client Secret.
The name of the Oracle Content Management application will usually be similar to
CECSXXX_<instance name>. - Expand the Resources panel in the Configuration tab and note the URL for the scope
you want, typically the scope corresponding to the
Oracle Content Management instance "/documents"
endpoint. The URL will be similar to
https://<primary audience url>/documents.If other Oracle Content Management functionality (for example, Social) is required, you'll need to note the URL for the corresponding scope.
When creating the service connection, you can use one of the following authentication mechanisms for the service connection:
| Authentication mechanism | Details |
|---|---|
| Basic |
To use this option you need to provide the following details:
|
| OAuth 2.0 Resource Owner Password |
To use this option you need to provide the following details:
|
If you don't have access to IDCS, get the Oracle Content Management application details from an administrator.
To connect to Oracle Content Management using fixed credentials:
Connect to ORDS APIs Using Fixed Credentials
To connect to Oracle REST Data Services (ORDS) using fixed credentials, you can use OAuth 2.0 Client Credentials for authentication.
Before creating a connection to ORDS, a role and privilege to protect your REST service need to be created and the OAuth client needs to be registered in the ORDS service. The following steps briefly describe this process. See Protecting and Accessing Resources.
When creating the service connection, you can use the following authentication mechanism for the service connection:
| Authentication mechanism | Details |
|---|---|
| OAuth 2.0 Client Credentials |
This is the recommended authentication option. To use this option you need to provide the following details:
|
- Create a role and privilege to protect your REST service in ORDS:
begin ords.create_role('HR Administrator'); ords.create_privilege( p_name => 'example.employees', p_role_name => 'HR Administrator', p_label => 'Employee Data', p_description => 'Provide access to employee HR data'); commit;end; - Associate the privilege with resources (i.e. your ORDS REST APIs):
begin ords.create_privilege_mapping( p_privilege_name => 'example.employees', p_pattern => '/examples/employees/*'); commit;end;Accessing the /example/employees REST resource should now result in a 401 unauthorized as shown here:
curl -i https://example.com/ords/ordstest/examples/employees/ HTTP/1.1 401 Unauthorized Content-Type: text/html Transfer-Encoding: chunked <!DOCTYPE html> <html> ... </html> - Register the OAuth client with grant type Client Credentials:
begin oauth.create_client( p_name => 'Client Credentials Example', p_grant_type => 'client_credentials', p_privilege_names => 'example.employees', p_support_email => 'support@example.com'); commit;end; - Grant this newly created client the required role:
begin oauth.grant_client_role( p_client_name => 'Client Credentials Example', p_role_name => 'HR Administrator' ); commit; end; - Check the registered client id and secret:
select client_id,client_secret from user_ords_clients where name = 'Client Credentials Example';
To create a connection to ORDS using fixed credentials:
- Open Services in the Navigator, click the + sign, and select Service Connection.
- Click Define by Endpoint in the Select Source step of the Create Service Connection wizard.
- Select the HTTP method and type the URL of the endpoint in ORDS.
- In the Authentication section of the Server tab, select OAuth 2.0 Client Credentials as the authentication mechanism.
- Provide the details for the Client Id, Secret, and Token URL fields based on your ORDS configuration.
- Test the service connection.