The Visual Builder Cloud Service Blog
-
REST Backends
March 30, 2020
Visual Builder - Understanding Backends and Servers
Visual Builder 19.4.3 introduces the concepts of backends and servers to segregate information about types of resources and the actual server details the resource point to. In this blog post, we look at the basics of backends, servers and how to configure them at the Tenant level.
A "backend" is a representation of a known resource like Integration Cloud, that Visual Builder understands. A backend contains a list of "servers" to help connect to this backend. Each server can be thought to encapsulate the details needed to connect to this type of resource like authentication, URL, etc.
Why do I need a different artifact to store this information rather than the Service Connection metadata? If your purpose was to connect to REST APIs from the out-of-the-box Service Catalog, and avoid the hassle of settings URLs, authentication and all of that every time you create a new Visual application, a backend helps you to do just that. Note that you can also create a Service Connection from endpoint or from specification where you dont strictly need a backend. Simply speaking, backends are the way to reuse external REST Resource configuration across all applications.
OK, so why do I need multiple servers for a backend? Sometimes, you want the same application to connect to different URLs of resources to get data. A common example would be you want the same application to connect to a development OIC (Oracle Integration Cloud) server while in development, but testers might want the application to be connected to a test OIC server while testing. The segregation made between the logical backend (OIC) and the actual servers that consist of the connection details make this possible.
The Service Catalog is represented by an OpenAPI3 compliant file called the catalog.json, that contain all the backend and server information. We can define backends and servers at the Tenant (or Instance) level as well as at the application level. So there is a catalog.json file at the Tenant level and one at each Visual App level. When you create a "Service Connection From Catalog", the catalog.json files are consulted to get a particular backend type's REST APIs. A simple flowchart showing this in practice is shown below
We can access the tenant backends by going to Tenant level Settings -> Services which shows the Backend Editor as shown below. (Note you will need to be an administrator to access the Tenant level Settings)
Here, the right hand side shows the details of a backend called "Oracle Cloud Applications" which has one server called "Default Server".
On clicking the pencil icon to edit the server, we can see more details about the server like below
The full catalog.json file is available by clicking the source editor icon on the right most side. The pre-defined backends available in VB are : Oracle Cloud Applications (Fusion Apps), Integrations Cloud and Process Cloud. Oracle Cloud Applications have the further sub types - Sales and Service, Enterprise Resource Planning and Supply Chain, and Human Capital Management. These pre-defined backends are known by the following names in catalog.json
|
Backend |
Backend name |
ServiceType |
|
Oracle Integration Cloud (a.k.a OIC) |
ics |
ics |
|
Oracle Process Cloud (a.k.a Process) |
vbprocess |
vbprocess |
|
Oracle Cloud Applications (a.k.a Fusion Apps/FA) |
fa |
fa-base |
|
Enterprise Resource Planning and Supply Chain |
fscmRestApi |
fa |
|
Sales and Service |
crmRestApi |
fa |
|
Human Capital Management |
hcmRestApi |
fa |
Here is a structure of a catalog.json, where a backend called "ics" is defined with two servers. The first server in the list is the default server. Each Server has a URL, authentication, connection type. The second server also has an extra block called "profiles" which point to which application profiles (see more here) this server is attached to. This enables us to configure a server for say, development activities, and another server, for testing activities separately.
Note that though the catalog.json contains information about what kind of authentication is used (e.g. Basic), any credentials are safely externalized away from the catalog.json.
Tenant backends have some restrictions
- There can be only one server for each backend at the tenant level. There are no application profiles at Tenant too.
- Limited authentication options are available for Tenant servers, namely None and Oracle Cloud Account/Propagate Current User Identity, which require that you either have a non-authenticated instance, or an instance with identity propagation configured between VB and the target instance (like co-hosted VB and Oracle Integration Cloud). If you dont have a server that satisfies this, you can circumvent this limitation by defining backends at the application level, where all authentication options are available
Let us now see the VB catalog in action with the following cases
CASE 1 - No tenant backends
Navigate to VB Tenant Settings and click on the Services tab. If none of the backends are defined, you should see an empty list as below
The corresponding catalog.json would have no backend entries
Note - you might have pre-configured backends if you have a co-hosted Visual Builder+Oracle Integration Cloud combination or if you have configured the Oracle Cloud Applications catalog before.
CASE 2 - Creating a tenant backend (if there are no backends of the type)
You can only use an Integrations backend at the Tenant if you have a Oracle Integrations Cloud provisioned with Visual Builder. In normal cases, this backend would have been auto-created during provisioning itself, and you are recommended not to change the settings
Click on the + Backend button and proceed to create an Integrations Application backend. Add the following details
- Instance URL
- Authentication for logged in users - typically Oracle Cloud Account
- Connection type - This tells whether the call from VB to the actual service should go via a proxy or directly. More about Connection type can be read here
- All other settings are optional
Click on Save. The new Integrations Application backend should be created as below
We can see that along with the backend ("ics"), the server that houses all the details for the backend is created as well and is now visible in the server list. Note that you can only create one server for any given backend at the tenant level, so no options to add server is available. If needed you can navigate to the headers tab and define applicable headers for this newly created backend.
There is only one backend of the given type. On clicking + backend again, you will be shown a message that the backend already exists.
You can see the catalog.json representation of the newly created backend by clicking the Source Editor icon
Once a backend is configured, you can proceed to create Service Connections of this type from the Service Catalog.
CASE 3 - Creating an Oracle Cloud Applications backend (if there are no backends of the type)
Unlike the Integrations backend, this will not be auto-created, and you will need to configure this once you have federation setup with an Oracle Cloud Applications (Fusion Apps) instance (More details to achieve federation here)
Click on the + backend button and proceed to add an Oracle Cloud Applications (Fusion Apps) backend. When prompted to add server details, provide the following
- Instance URL - You need to have a valid Oracle Cloud Applications (Fusion Apps) URL for this
- Authentication for logged in users - typically Oracle Cloud Account
- Connection type - This tells whether the call from VB to the actual service should go via a proxy or directly. More about Connection type can be read here
- All other settings are optional
While creating this backend, there is some background processing done by VB. First VB fetches the interfaceCatalogs URL ( i.e. <Oracle cloud apps base URL>/helpPortalApi/otherResources/latest/interfaceCatalogs ) for the particular instance and discovers information about the sub-pillars of this instance like CRM, ERP and HCM and then proceeds to fetch the minimal describe URL for the instance. Based on the information retrieved, the sub pillars or sub-backends for CRM, ERP, HCM will be automatically created as well.
Navigate through the backend tree to browse the sub-backend of "Sales and Service". These sub-backends have a derived URL from the main backend in the form of vb-catalog://backends/fa/<sub pillar type>/resources
Navigate to the "headers" tab. You should be able to see the Rest-Framework-version header also automatically setup for the newly created backend. This header is based on the allowed version of REST framework for the Oracle Cloud Applications instance that was provided
CASE 4 - Overridding a sub-backend at the Tenant
Let's peek into the Server details of "Sales and Service" sub-backend created in the previous case.
We can see the following things dependent on the main (Oracle Cloud Applications) backend:
- The URL pointing to vb-catalog://backends/fa/crmRestApi/resources - this tells VB to look in the current catalog.json for a backend called "fa" and append "/crmRestApi/resources" to it.
- REST-Framework-version header which appears as an inherited non-editable header
- Authentication and Connection type information - (which is not shown at all) in the right hand side
To override the Sales And Service backend to point to some other URL for all the applications, we edit the value to the URL to point to an absolute (HTTPS based) URL. This dissociates the link between the Sales and Service backend and the parent Oracle cloud applications backend.
Alternatively, we can choose to override parts of the server like the header values and the Authentication and Connection type information
- For overridding the header we simply define another header with the same name and give it the desired value
- For overridding the Authentication and Connection type information, we tick the checkbox marked "Override configuration inherited from the backend"
Below, the header is overridden to have a value of 3 and the authentication and connection type information is also changed from what is defined at the parent backend.
CASE 5 - Process Backends
Process backends are automatically created at the Tenant level when you provision the Enterprise edition of Oracle Integration, which includes the Processes and Oracle Visual Builder features. In normal cases, you will not need to update this information. These are not used to define Service Connections, but are used when you access Process related tasks in Visual Builder, To know more about Processes, and how to leverage them in Visual Builder, refer to this documentation
That's it for this post. Next time, we dive into more detail and take a look at Backends at application level.