Use Polymorphic Business Objects and Fields

Oracle Visual Builder Add-in for Excel supports using polymorphic business objects from ADF REST services in Table and Form-over-Table layouts you create for an integrated workbook.

Where and how a polymorphic business object can be used in a layout depends on its relationship with other business objects in the service.

If a polymorphic business object is a top-level business object or is a child business object with a "one-to-many" relationship with its parent, it can be used directly in a layout.

In this case, you create a layout for polymorphic business objects as you do for any other business objects. See Create a Table Layout in an Excel Workbook and Create a Form-over-Table Layout in an Excel Workbook.

If a child polymorphic business is in a "one-to-one" relationship with its parent, descriptive flexfields from the child can be added as fields to a layout bound to its parent business object during layout creation. See Create a Layout Using Descriptive Flexfields.

You can also add descriptive flexfields to an existing layout as described in Add Descriptive Flexfields to a Layout.

To determine the relationship of a child business object to its parent, see Check the Cardinality of Child Polymorphic Business Objects.

About Polymorphic Business Objects

A polymorphic business object is a business object where the set of fields for a particular record differs based on the value of a discriminator field (also known as a context segment). In addition, a polymorphic business object includes a number of fields representing global or context-sensitive segments. Global segments are available for all values of the discriminator field, while context-sensitive segments are dynamic based on the value of the discriminator field. Descriptive flexfields (DFFs) are a type of polymorphic business object.

For example, an "Employees" business object may include a child polymorphic "Regional Information" business object that defines region-specific information for employee records. The Regional Information business object contains a "Region" field that acts as a discriminator field. It also contains global segments for all records, such as "Site" and "Time Zone", as well as context-sensitive segments such as a "Postal Code/Zip Code" for employees in the North American region.

Check the Cardinality of Child Polymorphic Business Objects

You can determine if a child business object is in a "one-to-one" or "one-to-many" relationship with its parent by checking the "cardinality" setting for a child business object.

Child polymorphic business objects with a "one-to-many" relationship can be used directly in a layout. For those child business objects in a "one-to-one" relationship, you can add descriptive flexfields from the child to the parent business object layout.

To check the cardinality setting for a child business object, open the Business Object Editor for the parent business object, then click the Children tab.

Description of the illustration child-polymorphic-settings.png

Cardinality options are "One", "Many", or "Unknown". Child business objects with a cardinality of "Many" (one-to-many relationship) can be used directly in a layout. Those with a cardinality of "One" can be added as fields to the parent business object layout. See Create a Layout Using Descriptive Flexfields.

Note:

For workbooks created before Oracle Visual Builder Add-in for Excel version 3.2, the cardinality is set to "Unknown". This value behaves identically to a value of "One" for polymorphic business objects. The cardinality value does not impact the behavior of non-polymorphic business objects.

Create a Layout Using Descriptive Flexfields

When you create a Table or Form-over-Table layout, you can add descriptive flexfields (DFF) from a child business object to the parent layout if the child is in a "one-to-one" relationship with the parent. DFFs are indicated in the New Layout Setup wizard by an Information icon ().

Top-level polymorphic business objects as well as child business objects with a "one-to-many" relationship with their parent can also be added to the layout as you would any other business object. See Create a Table Layout in an Excel Workbook and Create a Form-over-Table Layout in an Excel Workbook.

To determine the relationship of a child business object to its parent, check its Cardinality setting. See Check the Cardinality of Child Polymorphic Business Objects.

To create a layout with DFFs:

1. Create a new worksheet for your Table or Form-over-Table layout and click Designer to launch the New Layout Setup wizard.
2. Follow the instructions in the wizard, selecting the DFF's ancestor business object when prompted in the second screen.
   
   

   
   Description of the illustration bo_hierarchy_poly.png

   
   

   In this example, the Employees business object is selected for the parent layout.

3. When prompted, select either Table Layout or Form-over-Table.
4. When you reach the fourth screen of the wizard, you are prompted to select descendant business objects for your layout or layouts.

   In this example, both Direct Reports and EmployeesDFF are selected. EmployeesDFF represents a DFF that is in a one-to-one relationship with Employees, as indicated by the Information icon ().

   
   

   
   Description of the illustration bo_hierarchy_dff.png

   
   

   If you select EmployeesDFF, the add-in adds the flexfields to the parent layout, Employees.

   If you choose to create a Form-over-Table layout, the add-in creates a layout with Employees in the form and Direct Reports in the table. If you instead choose Table layout, the add-in creates a dependent Table layout for Direct Reports.

5. When you reach the final screen in the wizard, review the details of the new layout, then click Finish.
   
   

   
   Description of the illustration layout_review_dff.png

   
   

In this example, the add-in creates a Form-over-Table layout with Employees in the form and Direct Reports in the table as shown in this image:

Description of the illustration fot_layout_polymorphic.png

The add-in also adds the Region flexfields from EmployeesDFF to the form (bordered in red). The flexfields include a "discriminator" field ("Region"), two global segments ("Site" and "Time Zone"), and two context-sensitive segments ("Zip Code" and "State"). The context-sensitive segments are dependent on the value of the Region field (in this case, "United States").

If the required flexfields do not appear in the layout by default, you can add them to your form or table from the Layout Designer. See Add Descriptive Flexfields to a Layout.

You can also show or hide context-sensitive segments based on the discriminator value. For example, you could choose to show the context-sensitive segments for Canada ("Postal Code" and "Province"), rather than the U.S. segments, ("Zip Code" and "State"). See Show or Hide Context-Sensitive Columns in a Table Layout.

Add Descriptive Flexfields to a Layout

You can add descriptive flexfields (DFF) to forms and tables using the Form Field Manager or Table Column Manager and place them anywhere in the form or table.Descriptive flexfields are a type of polymorphic business object that has a one-to-one relationship with its parent. See Overview of Descriptive Flexfields for more information on DFFs.

Note:

For polymorphic business objects in a one-to-many relationship, refer to Create a Layout Using Descriptive Flexfields instead.

1. Open the worksheet with the layout that you want to modify.
2. Click either the Form or Columns tab in the Layout Designer as needed.
3. Click the Manage Form Fields or Manage Columns button () to add your DFF.

   Available DFFs are identified by the title of the discriminator field (in this case, "Region") and appear at the bottom of the list of available fields. The field ID is the discriminator field ID ("__FLEX_Context").

4. Select the DFF from the Available Fields list.
   
   
   Description of the illustration add-dff-field.png
   
   

   You can also change the order of fields in the form or table by dragging and dropping fields in the Selected Fields list.

5. Click Done.

   The associated segments appear in the layout in the following order: global segments, the discriminator, and context-sensitive segments.

Context-sensitive columns for all possible discriminator values are included in the table. However, only those cells in a row that are relevant to the value in the discriminator field are editable. All other context-sensitive cells are read-only (grayed out).

Description of the illustration dff-table.png

In a form, the context-sensitive form fields relevant to the current discriminator value appear after the discriminator field. Context-sensitive fields that are not relevant are not included in the form. If you change the value in the discriminator field, the form automatically updates to include the relevant context-sensitive field for that value.

Description of the illustration dff-form.png

Show or Hide Context-Sensitive Columns in a Table Layout

You can select which context-sensitive columns you want to display for a polymorphic business object, using the Polymorphic Information tab of the Business Object Field Editor.

All context-sensitive columns are shown by default. You may want to use this task to hide columns in a layout. For example, in the case of a Region polymorphic business object, you may choose to show regional information only for U.S. employees and hide it for all others.

To show or hide context-sensitive columns:

1. Open the worksheet with the layout that you want to modify.
2. From the Layout Designer, click the Edit icon () next to the Business Object field.
3. From the Business Object Editor, click the Fields tab and then select the business object's field.
4. Click the Edit icon () in the Business Object Editor to open the Business Object Field Editor.
5. From the Polymorphic Information tab, select Limit discriminator values.
6. To ensure you see all available discriminator values, click the Refresh icon () to fetch the latest polymorphic metadata from the service.
   This icon may be disabled if a refresh has already been performed during the current session.
7. From the Discriminator Values list, select the discriminator values for the context-sensitive segment columns that you want to display. For example, to show zip code and state columns in your Table layout, select the United States check box and deselect all others.
   
   

   
   Description of the illustration polymorphic-info-selected.png

   
   
8. After you select or deselect discriminator values, close the open editors.

The layout displays the context-sensitive segment columns you selected.

Description of the illustration diff-table-hidden.png

Refresh Polymorphic Business Object Metadata

Clear polymorphic metadata when you publish a workbook to ensure the workbook gets the latest metadata. Oracle Visual Builder Add-in for Excel refreshes the polymorphic business object metadata during the first download operation performed after you open the published workbook.

Because polymorphic business object segments are configurable by customers and subject to change, metadata stored in the workbook may become stale.

To clear metadata when publishing a workbook, select Clear all layouts from the Publish Workbook window. See Publish an Integrated Excel Workbook.

Polymorphic Support Limitations

Before creating layouts for polymorphic business objects or adding descriptive flexfields to a layout, review the limitations here:

• Polymorphic business objects are only supported for ADF REST services.
• A polymorphic business object is assumed to only contain a single discriminator field. Multiple discriminators are not supported.
• The discriminator field must be a string.
• When a polymorphic column or form field expands, the order is global segments, the discriminator, and then context-sensitive segments. Note that:
  • Changing the order of the global segments or context-sensitive segments is not supported.
  • Hiding specific global or context-sensitive segments is not supported.
• In order to bind a polymorphic business object to a layout, it must expose polymorphic business object metadata. In an OpenAPI metadata document, this means that it must contain a "discriminator" and "oneOf" syntax in the schema for the business object. The "anyOf" polymorphic business object syntax is not supported.
• Hierarchical polymorphic business objects are not supported. All polymorphic segments must be defined directly on the polymorphic business object in the OpenAPI metadata document.
• Extensible Flexfields (EFFs) that define polymorphic segments on array-based subfields are not supported.
• When a layout contains a polymorphic business object, the "fields" and "expand" query parameters should not be manually configured in the "Search Parameters" in the "Query" tab of the designer.
• The case where a child business object's fields are determined by a parent business object's discriminator value is not yet supported.
• Limiting discriminator values for a polymorphic business object displayed in a Table layout does not limit:
  • The set of values that can be chosen in a list of values (LOV) for a discriminator field
  • The values users can provide for a discriminator field
• Polymorphic segments with a DISPLAYHINT value of Hide in the metadata are not displayed in the layout. If hidden segments are required, upload may fail.