This chapter covers the following topics:

Introduction to Model References

To reduce the time and effort required to create and maintain configuration models, a Model may contain one or more References to other Models. References allow a Model to be used as a subassembly within other Models. For example, your organization sells many different styles of trucks and automobiles, but some of them use the same 200 horsepower, V6 engine. You can create and maintain one Model for this engine in Oracle Configurator Developer, and then simply create a Reference to that Model from all other Models (automobiles) that use it. When the referenced Model is modified, the changes automatically propagate to all Models that refer to it.

Within the structure of a Model, a Reference node functions like a Component node. Like a Component, you can modify a Reference node’s name and effectivity, and specify how many instances of the referenced Model are available and can be created in a configuration. (Instantiability is explained in Introduction to Instantiation.)

When you work in a Model that contains a Reference, the structure of the referenced Model appears as a subtree of the parent Model. All of the referenced Model’s settings, structure, rules, and UIs are read-only when viewed from the parent Model.

At runtime, each instance contains the entire structure of the referenced Model and is subject to all the rules defined in that Model. Note that a Reference node functions differently in an imported BOM Model. For details, see References and BOM Models.

References and Rules

Like Model structure, the rules in a referenced Model are read-only when you are working in the parent Model. However, you can use referenced Model nodes when defining configuration rules for the parent Model. All rules defined this way, even those whose participant nodes are all part of the referenced Model’s structure, belong to and reside with the parent Model (that is, they do not belong to the referenced Model). You can create new rules for the parent Model, but all of the referenced Model’s rules are read-only when viewed from the parent Model.

Note: Use caution when using nodes within a referenced Model as participants in the parent Model’s configuration rules. If a node in the referenced Model is modified or deleted, the rule in the parent Model becomes invalid and Configurator Developer displays an error message when you generate logic for the parent.

If a Reference node can have multiple or variable instances, you can define a Numeric Rule that changes how many instances of the referenced Model can be created at runtime based on other end-user selections. This type of Numeric Rule is explained in Using Properties when Defining a Numeric Rule. Instantiability is explained in Introduction to Instantiation .

References and Effectivity

If you are unfamiliar with effectivity, please review Introduction to Effectivity before reading this section.

The root node of a Model is always effective. When a non-BOM Model is referenced by another Model, you can specify effective dates or assign an Effectivity Set, and specify one or more Usages to the Reference node. For References to BOM Models, you can modify only the Usage(s) assigned to the Reference node. To modify the effective dates of a "nested" referenced Model (that is, a Reference within a Reference), you must open its parent for editing. For example, Model 1 references Model 2, and Model 2 references Model 3. To modify the effective dates of Model 3, you must open Model 2 for editing in the Structure area of the Workbench. See Introduction to the Structure Area of the Workbench.

References and User Interfaces

At runtime, a UI is either invoked directly, when it is the UI for the item being configured, or it is invoked by reference, when it is the UI for a referenced Model. When you generate a UI, Configurator Developer selects the most recently generated or modified UI definition for each referenced Model. If a referenced Model has no UI, Configurator Developer generates a UI for it, then generates the parent Model’s UI.

When a Model references other Models, the parent Model’s UI provides controls to create and manage instances of each referenced Model (for example, a drilldown control for navigating to Pages within the referenced UI, controls for selecting options, and so on). For example, Model A references Model B. Model B is required and can have multiple instances at runtime. In the runtime UI, an end user can click a button to create, configure, or delete instances of Model B. The UI Master Template settings that control what types of controls are generated for referenced Models are described in UI Master Template Information and Settings.

When a Model references another Model, the parent Model’s UI also references the child Model’s UI. If a referenced Model has multiple UIs, you can specify which one you want to use after generating the parent Model’s UI. This procedure is explained in Modifying the User Interface Definition.

Integrating Referenced User Interfaces

When configuring a referenced Model, the primary navigation style and images used to indicate selection state may be different than the parent Model’s UI. For background, see Runtime Navigation.

This section describes how parent and child (referenced) UIs with different primary navigation styles are integrated when you generate a UI, and what occurs at runtime when the end user transitions between parent and child UIs during a configuration session.

Non-Instantiable Child Model

When a child Model is not instantiable, its UI can be integrated with its parent UI in one of the following ways:

If the parent UI specifies Model Tree navigation and the child UI does not, the parent Model Tree contains a link to the initial page of the child UI. The internal structure of the child Model does not appear in the parent Model Tree. When the end user navigates to the child Model’s initial page at runtime, its specified navigation mechanism will replace the Model Tree. When the end user navigates back to the parent Model, the Model Tree reappears.

If both the parent and child UIs specify Model Tree navigation, the parent Model Tree includes the entire Model Tree of the child at the appropriate location.

Integration of static navigation mechanisms, such as the single or multiple-level side Menus, occurs when you generate or refresh the parent Model’s UI, rather than being integrated at runtime. This means you can edit the integrated contents of the side menu in the parent UI. (This integration only occurs for non-instantiable Model References.)

Instantiable Child Model

When the child Model is instantiable, the instances are always created and accessed via a UI element that provides access to instances at runtime (either an Instance Management Table or Single Instance Control Region, depending on the maximum number of instances permitted). In most cases, the child UI’s primary navigation style becomes active, replacing the parent’s navigation style.

If the parent UI specifies Model Tree navigation and the child UI does not, the parent Model Tree does not contain any child content. In this case, the end user navigates using the aforementioned instance control UI elements.

If both the parent and child UIs specify Model Tree navigation, the parent Model Tree will include the Model Tree of each existing child instance at the appropriate location.

Child instances must be created via instance control elements, UI Actions, or Configurator Extensions; the Model Tree does not provide another method of creating instances.

The integration of parent and child Model Tree structures occurs at runtime and the integration points are specified in the parent Model Tree. Configurator Developer sets the integration points when you generate or refresh the parent Model’s UI, and bases them on the location of the Reference in the Model structure. You can modify the integration points when editing the contents of the parent Model Tree. (This is the same whether the referenced Model is instantiable or not.)

Modifying a Referenced User Interface

Configurator Developer stores a referenced Model’s UI definition in the referenced Model, not in the parent Model. Therefore, a referenced Model’s UI is read-only when viewed from its parent. To modify a referenced UI, you must first open the Model to which it belongs in the User Interface area of the Workbench.

You do not need to refresh the parent Model’s UI after making changes to a referenced Model. Because the UI for a referenced Model is linked to the parent Model’s UI, any changes to the referenced UI are reflected in the parent Model’s UI automatically.

Configurator Developer prevents you from deleting a UI that is referenced by another Model, since doing so would cause pages to be missing from the parent Model’s UI.

A referenced Model may have more than one UI. When modifying the parent Model’s UI definition, you can select a different UI for any of its referenced Models. For details, see Modifying the User Interface Definition.

Publishing and Referenced User Interfaces

If a UI Reference link is broken or missing, Configurator Developer displays a "consistency check" error when you publish the Model or update an existing publication. When this occurs, regenerate the parent Model’s UI to recreate the links, and then republish the Model.

For details about republishing, see Republishing.

References and BOM Models

One important use of References is to represent the relationship between a BOM Model that contains other BOM Models when you populate the CZ schema with BOM Model data. When you import a BOM Model that contains other BOM Models, Configurator Developer creates a Reference node for each child Model in the parent’s structure. You can assign one or more Usages to a BOM Model Reference node and modify its instantiability settings, but all settings that are defined in Oracle Bills of Material are read-only in Configurator Developer (for example, the node’s BOM Item Type, its Minimum, Maximum, and Default Quantity, and so on).

When a BOM Model is a child of (referenced by) several other BOM Models, it is not imported into Configurator Developer multiple times. The import procedure populates the CZ schema with the child BOM Model only once, and then creates References to it from each parent BOM Model. This allows the rules and UI for the referenced Model to be maintained in one place and ensures that no duplicate BOM Models exist in the database. For an example, see the Oracle Configurator Implementation Guide.

References and Optional BOM Models

A referenced BOM Model is not required to create a valid configuration if the Optional check box is selected for that Model in Oracle Bills of Material. If an optional BOM Model contains a Feature that is required, unintended results may occur at runtime. A required Feature is any Option Feature that has a Minimum greater than 0 (zero), or a Text Feature that has the Required check box selected in Configurator Developer.

This can occur at runtime when an optional BOM Model has a required Feature:

Example: Model A references Model B and Model C, which are both optional BOM Models. Model B and C are variations of the same component, and a valid configuration may contain one and only one of these components. Both Models contain a required Feature, and reference a Model that contains a required Feature (this structure is shown in Optional BOM Models with Required Features).

At runtime, the end user selects and configures Model B, satisfying the configuration requirement for that component. However, a selection from Model C is still required because it contains a required Feature. In this situation, the end user will be able to save a valid configuration of Model A, since only Model B or Model C is allowed. However, the configuration will still be incomplete.

To avoid this situation, do the following:

Optional BOM Models with Required Features

the picture is described in the document text

Creating Model References in Configurator Developer

You can create a Reference from a non-imported Model to one BOM Model and multiple non-imported Models. However, you cannot create a Reference from a BOM Model to another BOM Model. Although an imported BOM Model can contain one or more other ATO or PTO Models, this type of structure can be created and maintained only in Oracle Bills of Material. This is because all imported BOM Models must retain their structure as defined in Oracle Bills of Material. If a BOM Model’s structure could be modified in Configurator Developer (by referencing another BOM Model, for example), the resulting Model would not be orderable from Oracle Order Management.

Additionally, you cannot create a Reference in a BOM Model to a non-imported Model that references a BOM Model. For example, a non-imported Model called M1 references BOM Model B1. You cannot create a Reference from another BOM Model to M1, since this would create Model structure in which a BOM Model references another BOM Model. As mentioned above, this type of structure can only be created in Oracle Bills of Material.

Creating a Model Reference is explained in Creating a Model Reference.

Note: Running the Refresh All Configuration Models concurrent program may cause additional Models and References to be created if, for example, new structure has been added to the root BOM Model in Oracle Bills of Material.

Updating Referenced Models

When a Model is the target of a Reference and you make any changes to the structure of the referenced Model, you may need to update the parent Model. Updating may include generating logic, refreshing UIs, and republishing the parent and child Models (if they were previously published). This is because:

The logic generated for Property-based Compatibility Rules in the parent Model that refer to Features in the child Model may change when you modify Properties in the child (referenced) Model. Property-based Compatibility Rules are described in Property-based Compatibilities.

Configurator Developer does not automatically update the parent Model when you modify the structure of a referenced Model. You may be able to resolve any potential problems with the configuration model simply by regenerating logic for the parent Model. When you generate logic for a Model, Configurator Developer generates logic for any referenced Models whose logic is not up to date. When you refresh a UI, Configurator Developer also updates any referenced UIs that need to be refreshed. See Refreshing a User Interface.

Not all changes that you make to a Model that is referenced require you to update its parent Model(s). For example, modifications to the configuration rules or UI definitions of a referenced Model do not require changes within the parent, except perhaps for retesting.

You cannot delete a Model if it is referenced by another Model.

For information about limitations that exist when refreshing a BOM Model that contains other BOM Models, see the Oracle Configurator Implementation Guide.

Copying Models with References

When copying a Model that contains References, you can either create a new copy of each referenced Model, or maintain the existing Model References. This is an important consideration because changes to a Model affect every other Model that references it.

Select one of the following when copying a Model with References:

Warning: Copying an imported BOM Model and selecting Copy Entire Reference Chain can cause an error when you publish one of the copied Models. Configurator Developer displays a warning message when you publish a copy of a BOM Model if any of the following are true:

You can view a Model’s Product Key in the General area of the Workbench.

Note: You can also copy a Model and all of its child (referenced) Models programmatically using the PL/SQL package CZ_modelOperations_pub. This package contains a set of APIs that automate many of the tasks required to maintain configuration models. For more information, see the Oracle Configurator Implementation Guide.

Editing a Model Reference Node

You can perform the following operations on a Reference node in Configurator Developer:

When editing a Model that contains one or more References to other Models, you cannot modify or delete the referenced Model’s structure, rules or User Interface(s).