Use Polymorphic Business Objects and Fields

Oracle Visual Builder Add-in for Excel supports using polymorphic business objects 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 object is in a "one-to-one" relationship with its parent, it may be a descriptive flexfield or extensible flexfield. Descriptive flexfield segments 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.

Unlike descriptive flexfields, extensible flexfields are used directly in a separate table layout. See Create a Layout for Extensible Flexfields.

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) and extensible flexfields (EFFs) are types of polymorphic business objects.

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.

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 icon () 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

Create a Layout for Extensible Flexfields

You can create a standalone table layout that uses an extensible flexfield (EFF) business object as the primary business object. You can also choose a descendant EFF business object for a dependent layout.

Like descriptive flexfields (DFF), EFF business objects have a one-to-one relationship with their parent business object. However, EFFs define additional extended attributes on child business objects. The extended attributes defined on any one-to-one children of the EFF business object are automatically expanded into the EFF layout. For more information about EFFs, see Overview of Extensible Flexfields.

Before you proceed, refer to Notes on Extensible Flexfields for information on feature interactions and limitations.

To create a layout with EFFs:

1. Create a new worksheet for your layout and click Designer to launch the New Layout Setup wizard.
2. Follow the instructions in the wizard, selecting a business object as the primary business object when prompted in the second screen..

   If you want the layout to use an EFF business object, select it here. If you want to add the EFF to a dependent layout, you'll do this in the fourth screen.

   
   

   
   Description of the illustration new-layout-eff.png

   
   

   In this example, the Additional Information business object is selected for the layout.

3. When prompted, select 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.

   If you want to add the EFF as a dependent layout, select it here. In this example, Lines as well as the EFF, Additional Information, are selected.

   
   

   
   Description of the illustration new-layout-eff-descendant.png

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

When you add an EFF to a layout, the EFF expands to include all global segments and the discriminator field defined on the base EFF business object as well as all the context-sensitive fields (extended attributes) defined on one-to-one children of the EFF business object.

Notes on Extensible Flexfields

Review this section for technical notes on extensible flexfields.

• Do not configure the expand and fields parameters for the layout in the Layout Designer. The EFF layout may not function as expected on download. EFF layouts use the expand parameter with a value of "all" to retrieve EFF records and child (extended attribute) records in a single request on download.
• Do not enable Retrieve Descendant Rows in Single Payload from the Advanced tab of the Layout Designer. EFF download is not compatible with this feature because of the layout's use of the expand parameter.
• An EFF business object must be bound to its own separate layout. It cannot be denormalized into its parent layout as descriptive flexfields (DFF) are.
• It is not possible to limit the EFF contexts (child business objects). All contexts will be denormalized in the EFF layout.
• The relationship between the EFF business object and the child extended attribute business objects must be one to one. One-to-many children will be ignored by the add-in.
• If your workbook was created using an earlier version of the add-in, refresh the metadata to retrieve the full set required to work with EFF business objects. See Refresh Polymorphic Business Object Metadata.

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

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.

Cardinality information is only determined automatically for ADF REST services. For polymorphic business objects from other services, you must set the cardinality value manually to ensure appropriate behavior in layouts.

Note:

A value of "Unknown" behaves like a value of "One" for polymorphic business objects. The cardinality value does not impact the behavior of non-polymorphic business objects.

To check or set the cardinality setting for a child business object:

1. 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" may be descriptive flexfields or extensible 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.
2. If the business object is not part of an ADF REST service, select the appropriate cardinality value for each child polymorphic business object to ensure they behave as expected in the layouts.

Check the Primary Keys of Child Polymorphic Business Objects

Once you have created a layout for polymorphic business objects, like descriptive flexfields (DFFs) and extensible flexfields (EFFs), confirm the business object's primary key field is configured in the Business Object Field Editor for inclusion in update requests.

Primary key fields are hidden fields the add-in uses to uniquely identify business object records. Omission of the primary key field in an update request can result in an unexpected failure, such as a 404 (Row Not Found) error.

If a polymorphic business object field is marked as a primary key, its value will be cached on download and included in subsequent update requests even if the metadata indicates the field should be hidden.

To confirm that primary key fields are configured to avoid errors on upload:

1. Open the Business Object Field Editor for the primary key field.
   • For DFFs, navigate to the editor for the discriminator field (context segment), then click the Polymorphic Information tab.

     From the Fields tab, select the primary key field in the list of fields, then launch the Business Object Field Editor.

   • For EFFs, open the Business Object Editor for the EFF business object, then click the Children tab.

     For each child business object, open the Business Object Editor, then click the Fields tab. Select the primary key field, then launch the Business Object Field Editor.

2. Click the Constraints tab, then confirm the Primary Key check box is selected.
   
   

   
   Description of the illustration primary-key-constraints-field-editor.png

   
   

Refresh Polymorphic Business Object Metadata

You can refresh polymorphic metadata in your workbook to ensure it has the latest metadata. Because polymorphic business object segments are configurable by customers and subject to change, metadata stored in the workbook may become stale.

Oracle Visual Builder Add-in for Excel also automatically refreshes the polymorphic business object metadata during the first download operation performed after you open a saved or published workbook.

To clear polymorphic metadata, navigate to the discriminator field's Business Object Field Editor, then open the Polymorphic Information tab. From this tab, click Refresh polymorphic field segments.

You can also refresh this metadata by performing a catalog refresh. See Refresh a Business Object Catalog.

Note:

It is also recommended that you clear polymorphic metadata when you publish a workbook so that your business users get the latest metadata. 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:

• Extensible flexfields (EFFs) 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.
• When a layout contains a polymorphic business object, the "fields" and "expand" query parameters should not be manually configured in the Download Parameters area of the Layout Designer's Download tab.
• 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.

  Note:

  Primary key fields are an exception to this. These are hidden fields that are cached in the workbook on download and always sent on update. The add-in identifies primary key fields and marks them as such in the Business Object Field Editor. To ensure update requests succeed, check the primary key setting as described in Check the Primary Keys of Child Polymorphic Business Objects.