Managing Configurations

This chapter describes the data structures produced by Oracle Configurator during a configuration session, and how to manage the life cycle of a configuration.

This chapter covers the following topics:


This chapter explains the data structures produced by Oracle Configurator during a configuration session and how to manage the lifecycle of saved configurations. It includes the following topics:

For general information, see Configurator Architecture. For related information about configuration models and rules, and about the behavior of the runtime Oracle Configurator, see the Oracle Configurator Developer User’s Guide.

About Configurations

A configuration is the record of a configuration session. It is the output produced by the runtime Oracle Configurator, as a product of processing an end-user’s selections, which cause configuration rules to be applied against a configuration model. Oracle Configurator validates the selections, resulting in a configuration.

Once a configuration has been saved during a configuration session, it is identified by a configuration header ID, which is stored in the CZ schema as CZ_CONFIG_HDRS.CONFIG_HDR_ID.

When a configurable item is successfully configured, the config_hdr_id and config_rev_nbr that is returned in the XML termination message should be stored in the application entity that is associated with the configured item. For example, in Oracle Order Management, this is stored on the order line. In Oracle Order Capture, it is stored on a quote line.

A configuration can be:

Saving a Configuration

At any time during a configuration session the configuration can be saved, thus recording the selections made against the nodes of the Model structure, which are called configuration inputs. A configuration does not have to be valid or complete in order to be saved. You can save any configuration, even if it is invalid and incomplete. The saved configuration should be stored in the host application entity even if its status indicates that the configuration is invalid or incomplete.

If a configuration has been saved, then later it can be restored for further selections and validation. When a configuration is restored, it is not the final saved state of the Model that is restored, but only the configuration inputs to the Model. The restored inputs are reasserted against the Model to produce a configuration. See Configuration Identity for more information.

If the configuration model or rules have changed since the configuration was saved, then validation failures may occur as a result of inputs that no longer match the Model.

Because restoring a configuration reasserts all the configuration inputs to the Model, restoring a configuration programmatically with the CIO is normally not faster than restoring a configuration interactively, and under some circumstances can be slower.

A configuration can also be canceled during a configuration session, by terminating the runtime Oracle Configurator without saving the configuration. In this case, the configuration inputs are discarded.

Restoring Saved Configurations

Modifying previously saved configurations are validated against a comparable Model. After a configuration is saved, the original Model's structure, rules or UI may change or be migrated to a new instance. When a Model is migrated to a new instance, the synchronization creates a comparable Model that allows the previously saved configuration to be restored and validated against.

See Synchronizing Migrated Model Data for more information of synchronization criteria.

The following illustration shows what happens when a saved configuration is restored against a Model that has been migrated to and changed in another instance after the configuration was saved.

Restoring Saved Configurations Created from a Migrated Model

the picture is described in the document text

Model A1 is migrated to another instance as Model B1. Configurations are made against Model B1. A copy of Model A1 is made on the source instance (Model A2). At a later time Model A2 is migrated to the same target instance (Model B2). When the saved configurations are restored, they are restored against Model B2 (the most recent version of the Model).

Usually, Model node names are unique within an individual tree level and can be used when restoring configurations. Occasionally, the node name matching may fail. If you want to restore configurations that were saved against a Model that has been migrated, you must run either the Add Model Node Names to Configurations by Model Items or the Add Model Node Names to Configurations by Product Key concurrent program.

Configuration Identity

Configurations commonly consist of a single instance of your configuration model and a set of configuration inputs.

When a configuration is restored and changed, the changes are saved as a revision to that configuration. Each saved revision is identified by a Configuration Revision Number, which is stored as CZ_CONFIG_HDRS.CONFIG_REV_NBR. The combination of Header ID and Revision Number identifies a unique configuration record. The identity of each item in the configuration is recorded by a Configuration Item ID (stored as CZ_CONFIG_ITEMS.CONFIG_ITEM_ID). For detailed information about these and other tables, see the CZ eTRM, onMetaLink, Oracle’s technical support Web site.

Host Applications and Oracle Configurator

Oracle Configurator does not provide a UI to manage saved configurations. Oracle Configurator is an embedded component of other applications referred to as host applications. It is the responsibility of the host application to manage saved configurations. The host application has the following responsibilities in its relationship with Oracle Configurator:

Batch Validation of a Configured Item

Batch validation allows a host application to perform tasks such as:

A host application calls batch validation through the CZ_CF_API.VALIDATE PL/SQL procedure. For more information on batch validation, see Batch Validation.

If batch validation is unsuccessful (CZ_CF_API.VALIDATE returns validation_status>0), then the original config_hdr_id and config_rev_nbr, if any, should be preserved in the host application’s entity.

If batch validation is successful (CZ_CF_API.VALIDATE returns validation_status=0), then the host application must decide whether to store the returned config_hdr_id and config_rev_nbr in the host application’s entity. Consider the following when storing the returned config_hdr_id and config_rev_nbr:

The key requirement is that the host application must delete whichever saved configuration that is not retained in the host application’s entity.

Reconfiguring a Configured Item

The host application’s action following the reconfiguration of a configured item depends on the value of the termination message’s exit element.

Copying a Host Application’s Entity

When a host application creates a copy of a configuration that holds a reference to a saved configuration it should copy the saved configuration with CZ_CF_API.COPY_CONFIGURATION. The new config_hdr_id and config_rev_nbr that are returned from should be stored with the copy of the host application entity. The original saved configuration should not be deleted.

This same logic applies when the host application creates a new revision of its configuration that holds a reference to a saved configuration.

If the copied configuration must be revalidated at the time of copying, the best approach is to use CZ_CF_API.VALIDATE to create the copied configuration. Pass the parameter save_config_behavior=new_config in the initialization message, and store the config_hdr_id and config_rev_nbr to identify the copied configuration. The host application that uses this approach must be prepared to handle validation failures that may occur during the copying of a configuration.

For more information on the initialization message, see Session Initialization. For more information on the procedures and functions in CZ_CF_API, see Programmatic Tools for Development.

Passing a Saved Configuration to Another Host Application

When a saved configuration is handed off from one host application to another as part of the business flow, the saved configuration should be copied. See Copying a Host Application’s Entity.

Assuming that the entity is still accessible in the original host application, the original host application entity should retain its reference (config_hdr_id and config_rev_nbr) to the original saved configuration. The corresponding entity in the second host application should store a reference to the copied configuration. In this case, the original saved configuration should not be deleted. An example of this flow is the transition from Oracle Order Capture to Oracle Order Management when a quote is submitted as an order.

Deleting a Host Application Entity

When a host application deletes, purges, or otherwise makes an entity inaccessible that holds a reference to a saved configuration, the host application should delete the configuration using the procedure CZ_CF_API.DELETE_CONFIGURATION.