6 Manage Data for Multi-Level Business Objects

Sometimes business objects exist in a multi-level hierarchy. For example, a purchase order (PO) might contain a header and a set of lines. Each of these lines may contain one or more schedules and so on. For these hierarchies, Oracle Visual Builder Add-in for Excel supports operations across all "dependent" layouts.

In this example, purchaseOrders is referred to as the "parent" business object, lines is the "child", and schedules is the "grandchild". A workbook based on this hierarchy might use a Form-over-Table layout or a Table layout as the top-level, or "primary", layout.

If the workbook uses a Form-over-Table as the primary layout, the form displays the parent business object and the table, the child business object. If the workbook uses a Table as the primary layout, the table displays the parent business object.

In this diagram, a Form-over-Table layout on Sheet 1 displays the details of a purchase order in the form and all associated lines for this purchase order in the table. An additional dependent Table layout on Sheet 2 displays all the schedules associated with the PO's lines.

If, instead, the workbook uses a Table layout as the primary layout, then each level in the hierarchy has its own Table layout on a separate worksheet. In this diagram, Sheet 1 includes a Table layout for the parent business object showing the details for three purchase orders. Sheet 2 and Sheet 3 includes dependent Table layouts for the child and grandchild business objects, respectively.

Each of these dependent layouts is linked to its direct parent layout. Check the Status Viewer for a given Table layout's parent.

When you click Download Data, Upload Changes, or Clear for a layout in a dependent hierarchy, the operation takes effect on all layouts in the hierarchy, starting with the primary layout, progressing to the next layout in the hierarchy, and continuing down until the last level in the hierarchy. When the operation is complete on all layouts in the hierarchy, the worksheet with the primary layout is made active again.

Download Data for a Set of Dependent Layouts

During a download operation, the add-in downloads matching items for each layout in the hierarchy, starting with the primary layout, progressing to the next layout in the hierarchy, and continuing down until the last level in the hierarchy.

Take the scenario where there are four layouts: a primary Form-over-Table layout for purchaseOrders (parent) and Lines (child), and three dependent Table layouts for Schedules (grandchild), Attachments (grandchild), and Distributions (great-grandchild). Following a download, you would see that the first worksheet with the primary layout displays the purchase order in the form that matches the query and all associated child lines (say, three Lines) that match a configured query (if applicable) in the table.

The second worksheet displays all child schedules associated with the downloaded lines again based on any configured query. If each of the three Lines had three matching child Schedules, the Schedules table would download 9 schedules. And so on for the other worksheets. You can then update all of these lines, schedules, distributions, and attachments and upload all the changes together.

Once the download is complete, the Status Viewer displays any notifications including how many rows were downloaded at each level, as shown in this example:

Description of the illustration dependentlayout_download.png

Following a download, edit data much as you would in a Table or a Form-over-Table layout.

Note:

If you do not see all of the expected rows in your dependent layouts, check with your workbook developer. These layouts may have been configured with a search parameter that limits the rows that are downloaded.

Create New Rows for a Set of Dependent Layouts

You can create new rows for the primary layout as well as the dependent layouts in a set of dependent layouts.

You create new rows for the primary layout as you would for any Form-over-Table layout or Table layout. See Create a Parent Row in a Form-over-Table Layout and Create New Rows to Upload to the Web Application.

For dependent layouts below the primary layout, start from the parent table and launch the Create Child Rows wizard. The wizard steps you through the process of creating new child rows in a child layout for the parent rows selected in the parent layout.

Let's suppose you have an Expenses parent business object in the primary layout and Expense Distributions and Expense Itemizations child business objects in two child layouts. When you select a row from the parent layout, the wizard prompts you to choose which child layouts you want for the new child rows.

1. Select one or more parent row you want to create child rows for. Use the SHIFT key to select multiple rows.

   Note:

   The parent rows you select must be next to each other in the table. If there is a hidden row in a selected region, the add-in can't skip child row creation for this row.
2. Select Create Child Rows from the Table Row Changes menu to open the Create Child Rows wizard.
   
   

   
   Description of the illustration child-row-wizard1.png

   
   

   Note:

   The wizard only shows child layouts that have create enabled.
3. From the first page of the wizard, select the child layouts where you want to create new child rows, then click Next.
4. From the second page, enter the number of child rows you want to add to each child layout, then click Finish.

   The add-in activates the first child layout, appends the new child rows to the bottom of the table, and automatically populates all ancestor cells with appropriate values.

   Note:

   If necessary, you can enter values and overwrite auto-populated values for grandparent and higher columns.

   
   

   
   Description of the illustration new-rows-child-layout.png

   
   
5. Select or type appropriate values for the new rows as required.

Upload Data from a Set of Dependent Layouts

When your changes are ready to be uploaded, the upload operation submits all pending changes across the hierarchy of layouts. Pending changes may include creation of new items, deletion and updating of existing items, and invocation of actions on items, depending on how the layouts are configured and what capabilities are supported by the business objects.

You can view details of the operation in the primary layout's Status Viewer, which shows results for the primary layout as well as a summary for each layout in the dependent hierarchy, as shown in this example:

Description of the illustration dependentlayout_upload.png

Click each dependent layout to view additional details of the operation.

In some cases, your workbook may be configured to upload all changes to a parent row and its descendent rows (child rows, grandchild rows, and so on) in a single request. If this is the case for your workbook, then the add-in can only successfully upload your changes if there are no errors in any of the rows.

If there are one or more errors in the set of changed rows, all the rows are marked as failed. To troubleshoot the error, review the errors in the Status Viewer for each form, table, and descendant table in your workbook. Once you've fixed the errors in the pending changes, you can retry the upload operation.

Note:

You may have to fix and retry the upload more than once before it succeeds. The REST service may not report all errors that occur during a single upload operation.