6 Manage Data for Layouts in a Dependent Hierarchy

Sometimes business objects exist in a multi-level hierarchy. For example, a purchase order might contain a header and a set of lines. Each of these lines may contain one or more schedules each with one or more distributions. For such multi-level hierarchies, the add-in supports coordinated operations across multiple "dependent" layouts.

In a hierarchy of dependent layouts, the primary layout is always a Form-over-Table, one that's based on the parent business object (in the form) and a child business object (in the table). In our example, the form displays the details of a purchase order and the table lists the associated lines for this purchase order.

Additional Table layouts, on separate worksheets, are based on descendant business objects, relative to the parent business object. For example, the first Table layout displays the grandchild business object (schedules, in our example), the next one displays the great-grandchild business object (distributions), and so on.

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

Description of the illustration status-viewer-parent.png

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

During a download operation, all items for all rows from the parent layout are downloaded at each level. (Any search specifications, if configured, apply only to the primary Form-over-Table layout.) For example, when Sheet 1 in your workbook contains Purchase Orders as the parent and Lines as the child (containing, say, 10 Lines) and Sheet 2 contains Schedules as the grandchild, the Schedules table is populated with all Schedule items for all Lines. If each of the 10 Lines had two Schedules, the Schedules table would download 20 Lines. With this download, you can update all Schedules and upload all the changes together.

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

Create New Items

Create top-level (purchase orders) and second-level (lines) items as you would for a Form-over-Table layout. See Create a Parent Row in a Form-over-Table Layout and Create New Rows to Upload to the Web Application.

For the third level and below in your hierarchy, you need to associate new items with the appropriate parent when you create them. For example, you'll need to specify the correct line ID for a new schedule and the correct line and schedule IDs for a new distribution. To ensure you can properly associate new items with the correct parent, the layout can include one or more columns from the parent layout. In our example, the distribution layout may contain columns for both Line and Schedule IDs from the schedule layout.

For example, let's say the Distribution table in Sheet 3 includes a Line column and a Schedule column that comes from the Schedules table in Sheet 2. By typing the correct Line and Schedule ID in the Distributions table for a new create row, the new distribution will be properly associated with the correct line and schedule.

You must enter non-empty values that uniquely specify an item in the parent table. If, during upload, the entered line and schedule values don't match an existing schedule, creation of the item fails.

Upload Data

When updates 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 Form-over-Table 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 for a download operation:

Description of the illustration dependentlayout_download.png

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