Upload Changes Using Multi-Row Requests
By default, Oracle Visual Builder Add-in for Excel uses multi-row requests to upload changes from a table layout to an ADF REST service.
During an upload operation, the add-in sends multiple rows per request using a batch API. Rows marked for Update, Create, Delete, and custom actions are included in the multi-row requests.
If required, you can adjust multi-row processing settings to improve performance. See Configure Multi-Row Uploads. You can also disable multi-row requests if your service requires a separate request per row. See Disable Multi-Row Requests for Upload.
If your ADF REST service includes date effective objects, you can add the Effective-Of header for each of the required REST operations. See EffectiveOf Headers in Multi-Row Requests.
Multi-row requests are only supported on ADF REST services. For other REST service types, the add-in sends just one row per request. See Upload Table Changes Using Separate Requests for Each Row.
About Multi-Row Processing
Oracle Visual Builder Add-in for Excel uses an algorithm to determine the optimal size of the payload (number of rows) for a multi-row request as the upload operation proceeds. This is done to optimize performance and avoid timeouts.
The add-in's adaptive multi-row upload algorithm for table layouts use two configurable settings: "Target Response Time" and "Initial Row Count". The default target response time is 10 seconds. The default initial row count is 10 rows. For more information about these settings, see Configure Multi-Row Uploads.
Based on these values, the upload algorithm dynamically adapts to the REST service's request-processing performance by sending more or fewer rows for each multi-row request. It works like this:
- The add-in sends an initial set of multi-row requests using the initial row count.
- The add-in measures the response times for those initial requests and calculates the approximate number of rows that can be processed in the target response time.
- Using the new value for number of rows per request, the add-in sends one or more multi-row requests to the service.
- After receiving the responses from each set of requests to the service, the add-in recalculates of the number of rows, and sends another set of requests until all rows have been processed.
Note:
The target response time is not guaranteed, since actual response times vary depending on the REST service business logic, server load, network latency, and so on.If a multi-row request contains one or more errors, no changes are made by the service. In that case, a second multi-row request containing only the rows that succeeded during the first request is sent. If the second request fails, the add-in falls back to sending one row per request. For more information, see Making Batch Requests in Developing Fusion Web Applications with Oracle Application Development Framework.
If a set of changes includes custom actions and those actions have multi-row requests enabled, the changes are included in a multi-row request. However, if one or more rows is marked for a custom action that has multi-row requests disabled, the add-in reverts to sending the changes row by row. (See also Multi-Row Mode for Custom Actions.)
If you configure the add-in for parallel requests, it sends up to four multi-row requests in parallel. See Enable Parallel Requests During Upload.
If you configure the add-in to send descendant rows in the parent payload, then multi-row requests are not used when a Form-over-Table layout is the primary layout. See Upload Parent and Child Changes in the Same Payload.
Configure Multi-Row Uploads
If required, you can configure how Oracle Visual Builder Add-in for Excel uploads multiple rows of data for an Oracle ADF REST Resource business object.
You can access multi-row processing settings from the Upload tab of the business object's Business Object Editor. This tab includes a check box, Supports Multi-Row Requests, to enable and disable multi-row requests. This check box is selected by default for ADF REST business objects.
The tab also includes two fields for configuring multi-row processing: Initial Row Count and Target Response Time.
By default, the add-in's adaptive multi-row upload algorithm uses a target response time of 10 seconds and an initial row count of 10 rows. It is strongly recommended that you do not change the default values for these properties. They should provide good functionality, UI responsiveness, and overall good performance. See About Multi-Row Processing.
However, there may be scenarios where you would want to adjust these properties. For example, your REST service may require that all of a small number of rows be included in a single multi-row request. In this scenario, you could increase the initial row count value something like 100, then instruct your business users to limit changes to sets of 100 at a time.
Another example might be a slow REST endpoint where a row-processing KPI needs to be achieved. In this scenario, you may want to tune these properties to balance UI responsiveness and the ability to process a targeted number of rows in a certain time.
WARNING:
Modifying these properties may negatively affect performance and UI responsiveness. Performance may degrade if there are too many smaller requests, or timeouts may occur with fewer, very large requests.
You should thoroughly test the affect of your changes in a realistic environment before distributing the integrated workbook.
To configure multi-row processing:
- Open the Business Object Editor for the target business object. then click the Upload tab.
This image shows the Upload tab for an Employees business object with the Supports Multi-Row Requests check box as well as the Initial Row Count and Target Response Time fields.
You'll also find check boxes for parallel requests and upsert mode. For information about these features, see Enable Parallel Requests During Upload and Upload Changes Using Upsert Mode.
When enabled, the add-in sends multiple rows per request during an upload. For information about multi-row processing behavior, see About Multi-Row Processing.
Disable Multi-Row Requests for Upload
If your business object doesn't require separate REST requests, it is strongly recommended that you use the default multi-row request behavior as described in Upload Changes Using Multi-Row Requests.
To disable multi-row requests for a business object, deselect the Supports Multi-Row Requests check box from the business object's Business Object Editor as shown here:
This check box is selected by default for Oracle ADF REST Resource business objects. This check box is not present for other REST service types.
When you disable multi-row requests for a business object, the add-in uploads each changed row using a single request as it does for other service types. See Upload Table Changes Using Separate Requests for Each Row.
Specifically, the add-in sends:
- A row marked for Update using a PATCH request.
- A pending Create row using a POST request.
- A row marked for DELETE using a single DELETE request.
- A row marked for a custom action using a single POST request even if the Supports Multi-Row Requests check box is selected for the custom action. See Multi-Row Mode for Custom Actions.
Depending on network characteristics and REST service overhead and performance, disabling multi-row requests may result in a negative effect on performance, such as adding significant wait time for the business user.
When multi-row requests are enabled, the add-in can adjust the number of rows in the multi-row request based on the REST service's responsiveness. When disabled, each changed row is instead sent using a separate REST request, resulting in many more REST requests per upload operation.
Workbook owners are responsible for any performance issues that arise. Make sure to test that your use cases will succeed in all customer environments and scenarios, if multi-row requests are disabled.
EffectiveOf Headers in Multi-Row Requests
If your ADF REST service includes date effective objects, you can add the Effective-Of header for each of the required REST operations. Oracle Visual Builder Add-in for Excel evaluates these headers when preparing each part of a multi-row request.
The add-in does not add the defined extra request headers to the header during a multi-row upload. Instead, the add-in checks for the Effective-Of header and, if defined, it adds it to the multi-row part using the effectiveOf member.
To support date effective objects when uploading using multi-row requests, define Effective-Of headers for the different REST operations configured for a business object. See REST Request Headers.
For more information on these objects, refer to Manage Date Effective Objects.