Upload Parent and Child Changes in the Same Payload

Some services require that parent and child row changes be uploaded using the same REST request payload. If your service requires this, you can configure your integrated workbook to upload all changes in a single, "nested" upload.

This feature is only available for Oracle ADF REST Resource services and should only be enabled if the service requires that parent and child changes be included in a single request. For example, your REST service may include logic that requires you to create at least one child (for example, a "Line" item) when you create a parent item (for example, a "Supplier Negotiations" item). In this case, the REST service enforces this by requiring the POST request that includes a new Supplier Negotiations item to also include at least one new Line item.

Likewise for updates. The target REST service may include back-end logic that requires operating on all changed child items at once and so all changes must be included in a single request.

If the service doesn't have this requirement, it is strongly recommended that you use the standard upload logic. See either Upload Changes from a Form-Over-Table Layout or Upload Changes from a Table Layout.

When enabled on a Form-over-Table layout, Oracle Visual Builder Add-in for Excel includes changes to parent (form fields) and child (table rows) in the payload of a single REST request.

You can also enable this for a set of dependent layouts. When you do this, all descendant rows ("children", "grandchildren", "great-grandchildren", and so on) of a parent are included in a single REST request. See Use Multiple Layouts for Multi-level Business Objects.

Note:

Read-only table layouts (and any descendant layouts) are skipped.

Before you continue, please review Notes and Limitations of Single Payload Uploads to determine if you should enable this feature.

To configure your workbook to use nested upload:

Open the worksheet with the top-level layout for the parent and child business objects that need to be uploaded together.
This could be a standalone Form-over-Table or the primary (Form-over-Table or Table) layout of a set of dependent layouts.
In the Oracle Visual Builder tab, click Designer to open the Layout Designer in the Excel Task Pane.
From the Advanced tab of the Layout Designer, expand Upload Options, then select Send Descendant Rows in Parent Payload.
When you select this check box, the add-in deselects these options for the table layout as well as any descendant table layouts:
- Send Only Changed Data for Updates
- Delete Enabled
- Custom Actions Enabled
Description of the illustration nested-upload.png
If you use this feature for a set of dependent layouts, add primary key columns in the child and descendant table layouts to support updates.
As with other dependent layouts, add ancestor (direct parent) columns to support creates. See Create a Table Layout in an Excel Workbook and Add a Parent Column to Support Row Creation.

When a business user performs an upload, the add-in sends parent and child changes in a single REST request and then reports the success or failure of the upload operation. If there are read-only table layouts, these layouts and their descendants are skipped.

If the upload was a success, the add-in makes these updates for each changed row:

The Change column in the table is cleared.
The Status column displays an appropriate success status message, such as "Create Succeeded" or "Update Succeeded".
The Status Viewer displays notification messages for the successful form and table operations.

Note:

Uploaded child and grandchild table rows are not refreshed automatically after the upload. The Status Viewer indicates this with a message: "This row may not contain the latest information from the service. Download to refresh the information for this row.". The business user will need to download data again to see the latest complete row data.

If the upload fails for any row at any level in a hierarchy, all associated rows in the hierarchy—starting at the top-level parent row and cascading down to its child rows, grandchild rows, and so on—are marked as failed.

In this scenario:

The Change column in the table is left as is for all failed rows, either because the row itself failed or was part of a row hierarchy that included a failure.
The Status column displays an appropriate failure status message for each failed row, such as "Created Failed" or "Update Failed".
The Status Viewer displays the same notification messages for failed rows. The messages contain any parent failure messages along with the failure messages for descendant rows.

Note:

Each row from the primary table is treated separately, so a failure in one does not affect the success or failure of another. If there are other top-level parent rows with nested changes, these are re-sent following the failure and should succeed.

When an error occurs, the business user may have to visit each layout and scan the rows to find which row caused the failure.

Notes and Limitations of Single Payload Uploads

Single payload uploads (also referred to as "nested" uploads) are only supported for Oracle ADF REST Resource services. They can be enabled on standalone Form-over-Table layouts or on the primary layout (Form-over-Table or Table layout) for a set of dependent layouts. Review this section to see if the feature is suitable for your integrated workbook.

Note:

If your service doesn't require that parent and child changes are included in a single request, it is strongly recommended that you use the standard upload logic described in Upload Changes from a Table Layout or Upload Changes from a Form-Over-Table Layout.

Requirements

The service must support request payload structures that include child and descendant rows included with the parent fields. Rows for child business objects are included as array-typed members as peers of the parent's fields. These child rows in turn include the child fields along with arrays of grandchild rows, and so on.
The business object must support the use of Upsert mode when uploading both new and changed rows in the same upload request.
This requirement refers to the service itself. Oracle Visual Builder Add-in for Excel does not have to be configured to use Upsert mode for the business object to support this feature.

Form and Table Capabilities

Form rows marked for deletion or custom action are not affected by this feature. These changes are sent in separate DELETE and POST requests and are not included in a "nested" upload request.

Some Table capabilities are incompatible with the nested upload feature. When this feature is enabled, these capabilities are disabled for the table in a Form-over-Table layout, the Table layout used as the primary layout in a set of dependent layouts, and any descendant table layouts:

Send Only Changed Data for Updates
Delete Enabled
Custom Actions Enabled

Tables for attachment business objects are not supported as part of a nested upload.

Scalability

Be aware that this feature will not scale to handle large, enterprise-level volumes. If you enable this feature for your workbook, you are responsible for any scalability issues that arise. Make sure to test your workbook to verify that all required use cases will succeed in all customer environments and scenarios.

Potential scalability issues include:

Complex business logic or the processing of large numbers of nested items could push the request duration beyond what some load balancers and other network components, such as Akamai, support. This could result in the request failing due to a timeout.
Large request payload sizes will likely consume large amounts of memory and CPU. This could potentially affect other clients working against the same endpoint, virtual machine, or container.
For example, consider a set of dependent layouts with a Table as a primary layout that has a large number of changes. If all parent rows and associated descendant rows are sent in a single request, the payload size and processing time for the request may be significantly larger than if you sent each parent row and associated descendant rows separately.
Large request payload sizes could exceed the maximum supported by the endpoint.

Data Consistency and Conflict Detection

When this feature is enabled, requests with parent and child changes in the payload may result in changes previously uploaded by another user being overwritten without notification. This can occur when multiple users are acting on the same business object rows using different workbooks.

Consider a scenario where two users, user A and user B, both download data at the same time. If user A uploads their changes to child or descendant rows and then later user B uploads their changes to the same rows, user B's changes will overwrite user A's changes.

Also note that the "Upsert" scenario, where an existing parent item is uploaded with new child rows, does not currently support conflict detection.

Child and Descendant Primary Keys Included in Tables

Additional configuration may be needed by the workbook developer to support cases where descendant rows are updated. To ensure that updates succeed, you must include primary/alternate key fields as columns in child and other descendant Table layouts.

The child items' key values must appear in the payload, in the array of child items. The service must be able to locate the existing child item in order to update it.

REST Request Headers

Sending configured REST request headers is only supported for the primary table rows during nested upload. Rows from child and descendant tables will not include such headers, even if configured. See REST Request Headers and EffectiveOf Headers in Multi-Row Requests.