5 Edit Service Descriptions and Business Objects

The Oracle Visual Builder Add-in for Excel provides editors where you can modify a workbook's service description, including its definition for one or more business objects. A service description that contains multiple business objects is sometimes known as a Catalog.

Using the Catalog editors, you can change the URL of the host that provides access to the REST service your workbook uses. You can also add or remove fields that the business object exposed by the service supports; note that any changes that you make to a business object must be supported by the service that the workbook uses. If, for example, you add a field to a business object in the service description that the workbook uses, and the service does not support this field, errors occur when the workbook connects to the service.

Other examples of tasks that you can accomplish using these editors include:

• Edit field titles
• Configure the list of values for a field
• Change when a field is editable
• Configure pagination
• Adjust the field data types (Advanced)

While you can provide the service description document when you create a layout, using the Catalog editors lets you improve the service description in a variety of ways to enhance the overall user experience.

Note:

When you edit the service description in your workbook, you're only telling the add-in how the service operates, you are not telling the service what it should do. Service behavior cannot be changed from the workbook, so any changes you make to the service description in the workbook must be compatible with the service.

When you click Manage Catalogs in the main Oracle Visual Builder tab, the Catalog editors show progressively. That is, you first access the editor to edit the catalog. You then access subsequent editors for business objects and business object fields that the catalog provides access to. You can also open the business object and business object field editors from the Layout Designer. Both options (using Manage Catalogs and the Layout Designer) are shown here.

To import a service description document, you have two options:

• If you want to create a new catalog, particularly if the OpenAPI document has multiple business objects, use Manage Catalogs.
  Description of the illustration excel-add-service.png
• To add a business object to an existing catalog (with the understanding that the new business object will be located at the same host/base path as the other business objects in that catalog), use the Catalog Editor (see Add a Business Object to an Existing Catalog). This option is particularly useful when configuring a list of values.
  
  
  Description of the illustration excel_add_bo_to_catalog.png
  
  

After you import a service description document into the Excel workbook, consider editing it in the Business Object Catalog Editor, so that the catalog has a descriptive name. Very often, the title that the add-in displays for the catalog in the Excel workbook is the name of one of the business objects that the service exposes. For example, the following image shows a catalog where the default value for the Title property is Employees. This catalog exposes an Employees business object, so to avoid confusion, you can change the title that the catalog uses in the Excel workbook to Human Resources Services.

Description of the illustration excel-change-service-name.png

After making changes in the Business Object Catalog Editor, such as changing the service host or details of a business object, click Redraw Layout in the Oracle Visual Builder tab to see your changes reflected in the worksheet.

Create a Service Description in Oracle Visual Builder

If your target service does not provide an OpenAPI-compliant service description, you can create an OpenAPI-compliant service description in Visual Builder.

1. Sign in to your Visual Builder account in the Oracle Cloud.
2. Create a new visual application or open an existing visual application.
3. Create a service connection from an endpoint. See Create a Service Connection from an Endpoint.
4. Configure the service with the details that you will need in the Excel workbook integration.
5. In a Visual Builder web application, test the service connection by creating a sample page and table that retrieves data from the service.
6. In the source view of the visual application, locate and download the service.json file to your computer.

   The service.json file contains the OpenAPI service description for the REST service that you connected to from your visual application.

Add a Business Object to an Existing Catalog

If your service definition is missing a business object, you can add a new business object description to an existing service description:

1. Click Manage Catalogs.
2. In the Manage Business Object Catalogs window, select your existing catalog and click the Edit Business Object Catalog icon.
3. In the Business Object Catalog Editor, click Business Objects, then click the Import a Business Object from a Service Description icon.
4. Provide the URL or a file that contains the OpenAPI description of the new business object and click OK.
5. Click Done first in the Business Object Catalog Editor, then in the Manage Business Object Catalogs window.

Override a Business Object's Base Path

Typically, a Business Object Catalog holds business objects that share a base path (say, /abcRestApi-context-root/resources/v1). But if your list of values' operationRef points to another business object (say, /123RestApi-context-root/resources/v1), you can configure the business object to use the different base path. The add-in will then use this base path when making REST requests for the business object.

To configure a business object to use a base path different from the one shared by business objects in the Catalog:

1. Add a business object to your Business Object Catalog. See Add a Business Object to an Existing Catalog.
2. Use the newly created business object as the Referenced Business Object for your list of values. See Configure a List of Values for a Business Object Field.
3. Click the General tab in the Business Object Editor, enter the different base path in Base Path Override to override the base path used by all business objects in the Catalog, and click Done.
   
   
   Description of the illustration base_path_override.png
   
   

The add-in assumes that no extra authentication is required by business objects with a base path override.

Configure Pagination for a Business Object

If the REST service supports pagination, you can download pages of rows.

Imagine you need to download 10,000 rows of data. Downloading one row at a time is too slow. Attempting to download all 10,000 rows in one request might result in a timeout error. So, the solution is to download one page at a time where the page contains, for example, 500 rows.

You can configure the pagination behavior using the Download tab in the Business Object Editor.

Description of the illustration vb-excel-download-prop.png

The following list describes a number of the properties that the Download tab allows you configure values for:

• Offset Parameter Name: Controls where to start the next page. When fetching the first page, the add-in uses a value of zero. When fetching the second page, the add-in uses a value of 500, assuming the limit value is 499.
• Limit Parameter Name: Controls how many rows to fetch for each page.
• Limit Parameter Value: Controls the page size (number of rows that the add-in downloads).

For other service types, pagination may or may not be supported. If supported, the service may use parameter names like offset and limit or it may use other parameter names for the same purpose.

Consult the service API documentation to determine which parameters to use.

Note:

Certain OpenAPI document properties, such as Description, can contain formatting hints. The add-in displays the description text as is with no interpretation of such hints.