Streamlining Service Connections to use Backends

From the 23.10 release, Visual Builder mandatorily needs a Backend to create a Service Connection. Prior to 23.10, a developer could create Service Connections independently without creating a Backend, and this resulted in some customers configuring duplicate credentials to the same system scattered across Service Connections. Using Backends ensures that things like URL, credentials are consolidated in one backend, and can be changed in one place (rather than changing in each individual Service Connection) and referred in multiple Service Connections

For backward compatibility, you can still edit URL and credentials of existing independent Service Connections, although it is recommended that you move the URL/credentials to a proper backend. For new Service Connections, a backend is mandatory. The wizard flows to create Service Connections (By Endpoint or by Specification) have been modified to automatically create a Backend if one is not already created.

Recap – Backends and Service Connections

Backends represent external REST-based systems, and therefore are characterized by the URL and authentication (collectively called a Server in Open API) needed to connect to this system. Application profiles in visual apps can allow different Servers for different application profiles (test, prod) for the same Backend.

Service Connections are one or more REST-based resources (e.g. /accounts, /contacts) of the system and their associated schema, endpoints etc represented by an openapi document

Identifying Service Connections that dont use a Backend

Service Connections that dont use a Backend can be identified by having an HTTPS based URL and/or an authentication block. From 23.10 you can still modify the URL and authentication, but you will not be able to add a new Server to the Service Connection.

Service Connections based on backend will have a URL based on the VB catalog namespace like vb-catalog://backends/<name of backend> . They dont have any facility to add Credentials or a URL or multiple Servers (corresponding to application profiles). These things are to be done at the Backend rather than the Service Connection.

It is recommended to change independent Service Conections to use a Backend.  Once you have identified all the Service Connections you want to streamline, follow the below steps for each such Service Connection.  

How to change the configuration of a Service Connection to use a Backend

Step 1 – Create a Backend for the Service Connection (if not present)

Check if there is already a backend defined in the visual application that you should make use of. This can be found out from the catalog.json file – look for a backend that matches the base URL of the Service Connection. If not, proceed to create a new Custom backend with the base URL and authentication None (for time being). Typically the backend only contains the base URL of the system e.g. https://abc-pod.somecloud.com whereas the Service Connection URL might be the full URL of the system e.g. https://abc-pod.somecloud.com/api/endpoints/v1/rest

At the end of this step, you should have a Backend representing the REST system in question. Note down the name of this backend (myBackend in the above example)

Optional – Here, you can also consider Tenant level backends. In this blog for simplicity, we only consider application-level backends. You might also want to use out-of-the-box backends like "ics" for Oracle Integration Cloud and "fa" for Oracle Fusion Cloud Applications.  More on this is discussed in the Additional pointers section

Step 2 – Copy the servers block from the Service Connection

To avoid any potential mismatches, we will copy the relevant part of the Servers in the Service Connection to the Backend. Navigate to the source tab of the Service Connection in question, and copy the entire servers block to notepad or some other text editor.  Remove the URL parts after the base URL as indicated by green shade in the below figure.  This is because we will be creating backends with only the base URL and the other parts of the URL will remain in the Service Connection.

Step 3 – Replace the servers block of the Backend

Paste this edited JSON block onto the servers block of the Backend of step 1. By doing this, you have replaced the Backend’s credentials, URL and other details with those from the Service Connection. Check if the Backend editor displays correctly and there is no error in the copied JSON

Step 4 – Modify the Service Connection to use the Backend

Next step is to make the Service Connection point to the Backend. To do this, navigate to the Service Connection → Source tab and then navigate to the servers block. Replace the entire servers block with the following :

"servers": [
{
"url": "vb-catalog://backends/<backend_name>/<rest_of_the_path>"
}
]

In the example shown above the <backend_name> is myBackend and the <rest_of_the_path> is /api/endpoints/v1/rest (the part that we didnt copy to the backend).  

Check if the Service editor displays correctly and there is no error in the copied JSON

Try testing the Service Connection via the test tab and the designer preview.

Repeat for other Service Connections.  You can club Service Connections with the same kind of server information i.e. same application profiles, base URL, authentication, and other attributes under the same Backend.  In the below example both srvcCountry and srvcEcho are Service Connections to the same system with the same auth, and other details.  Hence they can be combined under one Backend.

Additional pointers

• If the Service Connection that you wish to streamline has just one server, you might want to use a custom Tenant Backend.  The procedure remains the same, however you copy the servers block to a backend in the Tenant Settings rather than a backend at the Application level.  Tenant level Backends are available to all visual apps to use.  However Tenant Backends dont support multiple servers or application profiles, so if you have those, then Tenant Backends cant be leveraged.
• There are also some special backends available in VB which facilitate the discovery of applicable REST endpoints via a catalog – these are "Integration Applications" for OIC and "Oracle Cloud Applications" for Oracle Fusion Cloud Applications.  If your Service Connection is to these systems, consider using these specific backends rather than using a Custom backend.  Once you setup these backends, you can take advantage of creating a Service Connection from the catalog.  
• In some cases, there might have been Service Connections based on a Backend, but the credentials of the Backend have been overridden in the Service Connection for some reason.  In such cases, examine whether you might want the credentials to be updated in the Backend.  In case you do need multiple sets of credentials to the same system, consider creating a child Backend of the original Backend but with the overridden credentials, and use the child backend's reference in the Service Connection.

This completes the blog on how to manually use backends for your Service Connections and reduce the risk of same credentials in multiple places.