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:

• Overview
• About Configurations
• Configuration Identity
• Host Applications and Oracle Configurator
• Batch Validation of a Configured Item
• Reconfiguring a Configured Item
• Copying a Host Application’s Entity
• Passing a Saved Configuration to Another Host Application
• Deleting a Host Application Entity

Overview

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:

• About Configurations

• Configuration Identity

• Host Applications and Oracle Configurator

• Batch Validation of a Configured Item

• Reconfiguring a Configured Item

• Copying a Host Application’s Entity

• Passing a Saved Configuration to Another Host Application

• Deleting a Host Application Entity

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:

• Valid or invalid

  A valid configuration contains no contradictions to the rules, whereas an invalid configuration contains contradictions.

• Complete or incomplete

  A complete configuration includes all the required selections. An incomplete configuration lacks some required selections; in other words, some of the configuration rules are unsatisfied.

• New, saved, restored, or cancelled

  A new configuration is one in which the user has not made any selections, and the logic state of many elements is Unknown.

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

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:

• Maintain an index of configuration product keys that can be used to launch the runtime Oracle Configurator UI or batch validation. The product key usually consists of the Inventory Item ID followed by its Inventory Organization ID. For example, 452:1534. The product key could also be any name that identifies a configurable object in the host application’s domain.

• Implement the runtime Oracle Configurator UI or batch validation by providing a product key or the ID of a saved configuration. To launch a saved configuration you must know the configuration’s header ID (config_header_id) and revision number (config_rev_number). For more information about the configuration’s identity, see Configuration Identity.

• Keep track of the saved configurations returned by the runtime Oracle Configurator by storing the config_header_id and the config_rev_number with an entity in the host application.

  Note: Oracle Configurator creates saved configurations at the end of an interactive or batch configuration session when the initialization message includes instructions to do so and the session terminates normally. For more information on the initialization message, see Session Initialization.

• Delete saved configurations by using CZ_CF_API.DELETE_CONFIGURATION when configurations are no longer associated with any host application entity.

Batch Validation of a Configured Item

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

• Validating a BOM-based configuration in the background

• Determining a configuration quantity

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:

• If the validation is for an item that was not previously configured, then the returned config_hdr_id and config_rev_nbr should always be stored, because this is the original configuration of the item.

• If the validated configuration is complete and valid, then the new config_hdr_id and config_rev_nbr should be stored, replacing the previous values. The previously saved configuration should be deleted by CZ_CF_API.DELETE_CONFIGURATION.

• If the validated configuration is incomplete or invalid, then there are two different approaches that the host application may adopt. The host application may:

  • Choose to present the validation messages to the user and roll back whatever change in the configuration or status is being validated. In this case, the new saved configuration that is returned by batch validation should be deleted with CZ_CF_API.DELETE_CONFIGURATION. This is the approach that is adopted by Oracle Order Management.

  • Choose to accept any changes to the configuration, replace the previously saved configuration with the new configuration, present the validation messages to the user and roll back any proposed change in status. In this case, the previously saved configuration should be deleted with CZ_CF_API.DELETE_CONFIGURATION.

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.

• If the exit value is save, then the termination message also contains new values for config_hdr_id and config_rev_nbr. These new values should be stored in the host application’s entity that is associated with the configured item. The previously saved configuration should be deleted by calling CZ_CF_API.DELETE_CONFIGURATION and passing the values of config_hdr_id and config_rev_nbr that were previously stored with the host application’s entity.

  Note: This assumes that the reconfigured item replaces the previous configuration on the same host application entity. If the reconfiguration is performed in the process of creating a new copy or revision of the entity, then the new values of config_hdr_id and config_rev_nbr should be stored with the new copy or revision, and the original values should remain associated with the original entity.

  In this case the previously saved configuration should not be deleted, because it is accessible through the original host application entity.

  This behavior is independent of whether the newly saved configuration is valid or complete. The user chose to save the configuration knowing its status (valid or complete), so it should be stored with the host application’s entity.

• If the exit value is cancel, error, or processed, then the previously stored values of config_hdr_id and config_rev_nbr should be retained in the host application’s entity.

  Note: Changing the Instantiability settings for a Model or Component node within a published Model may change the number of instances that exist when an end user restores a saved configuration. For example, decreasing the Initial Minimum in Configurator Developer and then republishing the Model may cause some instances of the component to be lost when the configuration is restored. (In this case, Oracle Configurator displays a message indicating that a validation failure occurred.) Similarly, increasing the Initial Minimum value may create additional instances in a restored configuration.

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.