X

The Visual Builder Cloud Service Blog

Consuming Fusion Applications REST APIs in Visual Builder Cloud Service Applications

John Jullion-Ceccarelli
Product Manager

This blog is part of the series Visual Builder Cloud Service Learning Path. In this lesson we will look at consuming Fusion Applications REST services in a VBCS mobile application.

In order to work with a REST API, VBCS needs to understand basic information about that REST service, such as:

  • The service endpoints and verbs
  • The required query parameters and headers
  • The authentication method used to connect
  • The transformation patterns for creating URLs for pagination, sorting, and filtering

Fusion Applications like Oracle CX, HCM, and ERP clouds expose REST APIs that VBCS knows how to consume right out of the box. 

There are three ways you hook up to register a REST connection:

  • Select from Catalog - The Service Catalog shows all of the REST APIs for a registered Fusion instance. VBCS understands FA REST services out-of-the-box. See Authenticating Against FA below to see the requirements for Service Catalog
  • Define by Specification - Enter the location of a Swagger or ADF-Describe document for a REST API. Use this to set up an App ID connection to any FA server, regardless of whether it meets the requirements in Authenticating Against FA.
  • Define by Endpoint - Use this wizard to manually specify the required information about a REST endpoint. We will use this to register a Twitter API in a later lesson.

Creating the Project and the Mobile Application

In this lesson we will build the following UI over the FA Contacts REST endpoint:

To do this we will access three endpoints:

  • The GET ONE and GET MANY endpoints for /contacts
  • The finder method that retrieves all of the country names, country codes, and other information

Creating the Mobile App

  1. Create a new project called FAContactList
  2. In the Mobile Apps panel, click Create New Mobile App. Name the app Contacts and select None for the Navigation Style. Click Finish.

Registering the Contacts REST API

  1. Click the Service Connections panel and click Add Service Connection.
    • If you have a registered Service Catalog, click Select from Catalog. 
    • If you do not have a registered Service Catalog, click Define by Specification. Switch the API Type to ADF Describe. Enter https://pathToYourCRM/crmRestApi/resources/latest/contacts/describe in the Service Specification field. Set the Service ID to contacts. Enable Basic Authentication and enter a set of valid credentials that has permission to call the REST API. Then click Next.
  2. Expand the /contacts node and select all of the following:
  • GET /contacts
  • GET /contacts/{contacts_Id}
  • GET /fndTerritories;for=contacts-CountriesLOV

Creating the List

  1. Select the main-start page in the Page Designer.
  2. Drop a List View onto the page.
  3. Select the List View in the Page Designer. (If you have just dropped it in, it will be selected already.) Then open the Property Inspector and select the Quickstarts page.
  4. Under crmRestApi, select contacts.
  5. Select the first template and click Next
  6. Add the following fields:
    • Field 2: ContactName
    • Field 3: AccountName
    • Field 4: Country
  7. Click Next and then click Finish.

Creating the Details Page

  1. Select the List View in the Page Designer.
  2. In the QuickStart tab of the Property Inspector, click Add Details Page.
  3. In the Select Endpoint page, select contacts and click Next.
  4. Add these fields:
    • AccountName
    • ContactName
    • FormattedHomePhoneNumber
    • FormattedMobileNumber
    • PrimaryAddress > item[i] > FormattedAddress
  5. Click Finish.
  6. Open the ContactDetails page in the Page Designer
  7. Select the Form Layout and in the Property Inspector change the Label Edge variable to Top. All of the display labels move to above the input fields.
  8. Fix the display label text and reorder the fields so the page looks like this:

Displaying LOV Labels in Collections and Details Pages

As you can see, the list of Contacts is showing the country code instead of the full country name. This is because there is no one REST API that you can use to retrieve both the country codes and the display labels in the same call. Instead, we have to cache all of the country display labels in an application-scope variable when the application is first accessed. Then we will use a custom Javascript function to swap out the country codes for the display labels when the list is rendered.

Adding the getLOVMeaningValue Function

  1. Open the application editor by opening the Mobile Apps panel and clicking the top-level Contacts node.
  2. Open the JavaScript panel of the application editor by clicking the JS button
  3. Add the getLOVMeaningValue function as shown in lines 6-22 below:
	define([], function() {
		'use strict';
	  
		var AppModule = function AppModule() {};
	  
		AppModule.prototype.getLOVMeaningValue = function(key, lovs) {
	  
		  if (!lovs || !lovs[0]) {
			return;
		  }
		  var res;
		  var keyProperty = Object.keys(lovs[0])[0];
		  lovs.forEach(function(record) {
			if (record[keyProperty] === key) {
			  res = record;
			}
		  });
	  
		  if (res) {
			return res[Object.keys(res)[1]];
		  }
		};
	  
		return AppModule;
	  });

Creating the Type and Variable for the Status Code Options

  1. Still in the application settings editor, open the Variables editor, then click the Types tab.
  2. Create a new Type from Endpoint based on the /fndTerritories;for=contacts-CountriesLOV endpoint.
  3. Change the name of the type to countryCodeOptions. Add TerritoryCode and TerritoryShortName to the Type and click Finish.
  4. Switch to the Variables tab.
  5. Create a new variable called countryCodes of type countryCodeOptions.

Creating an Action to Populate Account Type Options

  1. Still in the application settings editor, open the Actions page.
  2. Create a new Action Chain called populateCountryCodes.
  3. Drag a Call REST Endpoint action from the left panel to underneath the Start node.
  4. In the Property Inspector, click Select Endpoint and select contacts > contacts  > /fndTerritories;for=contacts-CountriesLOV
  5. By default the REST call only returns the first 25 entries, but we want to cache all of the country names in our variable. So we will set a high limit for the REST call. In the property inspector, click limit under Input Parameters. Map the variable to 500, leaving it set as Static Content, and click OK.
  6. Add an Assign Variables action that maps the body returned by the Call REST action to the statusCodes flow variable.
  7. Return to the application editor and open the Events panel
  8. Create a new event:
    • Event: vbEnter
    • Action Chain: populateStatusCode

Updating the List to Call the getLOVMeaningValue Function

  1. Open the Page Designer for main-start.
  2. Select any row in the list
  3. In the General tab of the Property Inspector, change the Value1 to:
    [[ $application.functions.getLOVMeaningValue($current.data.Country,$application.variables.countryCodes.items)]]

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.