5 Edit Service Descriptions and Business Objects

The Excel add-in provides editors where you can modify the service description that the workbook uses.

Using these service description editors, you can change the URL for the service host that provides access to the REST service your workbook uses, or you can add or remove fields that the business object exposed by the REST service supports. For the latter task, note that any changes that you make to a business object must be supported by the REST 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 REST service does not support this field, errors occur when the workbook connects to the REST 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 where a field is editable
• Adjust the field data types (Advanced)

Using the service description editors, you can improve the service description in a variety of ways to enhance the overall user experience.

The add-in displays the editors progressively. That is, you access the editor to edit the REST service from the Manage Services button and you can then access the subsequent editors for the business objects and business objects fields that the service provides access to. You can also open the editor(s) for business objects and business object fields from the Layout Designer. Both options, using the Manage Services button and the Layout Designer, are illustrated in the following image.

When you click the Manage Services button in a blank Excel workbook that has not been integrated with a REST service using the Oracle Visual Builder add-in, the add-in prepares the workbook and displays a Manages Service window from where you can open a Services Editor to import the service description document.

Description of the illustration excel-add-service.png

After you import a service description document into the Excel workbook, consider editing it in the Services Editor so that the service has a descriptive name. Very often, the title that the add-in displays for the service in the Excel workbook is the name of one of the business objects that the service exposes. For example, the following image shows a service where the default value for the Title property is Employees. This service exposes an Employees business object, so to avoid confusion the user changes the title that the service uses in the Excel workbook to REST Service for Employees.
Description of the illustration excel-change-service-name.png

After making changes in the Service 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

You can create an OpenAPI-compliant service description in Oracle 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 an Oracle 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 Builder visual application.

Configure Pagination for a Business Object

The add-in supports downloading pages of rows if the REST service supports pagination.

Imagine that 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 time out. 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.

Notes

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.