Publishing Configuration Models

This chapter explains the database processes for publishing configuration models to make them available to host applications.

This chapter covers the following topics:

Overview

This chapter presents information about:

Planning Publications

Publishing is a process that creates a copy of a configuration model on a specific database and makes it available to host applications for testing or production use. The copied data is called a publication, and it includes the Model’s structure, rules, User Interface, and Global User Interface Templates. The publishing process is explained in the Oracle Configurator Developer User’s Guide.

Publishing configuration models requires careful planning, based on a thorough understanding of the process by which publications of configuration models are defined and made available to host applications.

As part of your planning, consider the following:

Once you have determined how the publication functionality applies to your situation, identify the necessary tasks in Oracle Applications and Oracle Configurator Developer .

Creating configuration models and publication requests is explained in the Oracle Configurator Developer User’s Guide .

Designing A Project

Your project design should account for how you use host applications, Usages, effective date ranges, languages, publication modes, and database instances.

Consider the following:

Preventing Publication Access Errors

To prevent end users from receiving errors, you should plan for and try to create publications for all circumstances in which host applications access your configuration models. Applications that can host a runtime Oracle Configurator can access different publications for a single configuration model. A publication corresponds to only one configuration model and one User Interface. A configuration model can have multiple User Interfaces and you can create many publications for the same Model.

How Host Applications Select a Published Model

All applications that can host a runtime Oracle Configurator select a specific Model publication to view by sending an initialization message to the Oracle Configurator Servlet. If a publication’s applicability parameters match the parameters in this message, then the corresponding configuration model and UI appear in the Configurator window. If no matching publication is found but the Model was created from an imported BOM Model, then Oracle Configurator displays the BOM Model in the Generic Configurator UI. If no matching publication is found and the Model was created in Oracle Configurator, then Oracle Configurator displays an error.

For example, in your business you know that two different host applications, Oracle Order Management (OM) and Oracle iStore, will be used to configure Model M1. You define two unique UIs in Configurator Developer and create two publications for this Model. You set the Applications applicability parameter to Oracle Order Management for the first publication, and Oracle iStore for the second. An Oracle Applications user whose responsibility is assigned to Oracle Order Management selects Model M1 in the Sales Orders window, and clicks Configure.

Using the information in the initialization message, the OC Servlet selects the only publication in the database that:

The OC Servlet then displays the configuration model and UI that you defined specifically for orders placed from Order Management in the Configurator window.

For detailed information about the initialization message, see Session Initialization.

For information about entering applicability parameters when creating a publication, see the Oracle Configurator Developer User’s Guide.

Example: How a Usage Affects Model Structure, Rules, and Model Publications at Runtime

Your company makes and sells cars and has two types of Oracle Order Management users: experienced users, who are very familiar with each vehicle, and new users, who are either still in training or have worked for the company for only a short time.

The US Environmental Protection Agency (EPA) requires that cars sold in California meet more rigorous emissions standards than other states in the U.S. Therefore, cars that are sold in California must have different engine and exhaust components than cars sold elsewhere. Your experienced users need to be able to quickly configure orders and do not require much information except the state in which the customer lives. However, your less experienced users require more detailed information and guidance to consistently create valid, orderable configurations.

When defining the configuration model, you create additional Model structure, rules, and a UI to guide inexperienced users. The additional Model structure and rules provide the guided buying and selling questions to ensure that inexperienced users correctly configure each vehicle based on the state in which the customer lives. You then create a Usage called "Experienced User" and select this Usage for the guided buying or selling structure and rules in your Model.

Your System Administrator sets the profile option CZ: Publication Usage at the User level for each Oracle Configurator end user. For the experienced users, the System Administrator sets this profile option to "Experienced User". For inexperienced users, the System Administrator accepts the profile option’s default value, which is "Any Usage."

You create two publications for the Model. One publication is intended for experienced users, so you select the appropriate UI and the Experienced User Usage when defining the publication’s applicability parameters. The other publication is intended for inexperienced users, so you select the UI that has additional controls and information for configuring the car, but do not select a Usage (that is, you accept the default value, which is Any Usage).

When an end user wants to configure a car, Oracle Configurator checks how the CZ: Publication Usage profile option is set for that user, and applies this value to the configuration session. If the Usage specified is "Any Usage," then Oracle Configurator displays the publication and UI intended for the inexperienced user. This publication has additional UI controls, rules, and guided buying or selling questions to guide the user’s selections.

If the Usage specified is "Experienced User," then Oracle Configurator displays the publication and UI intended for the experienced user. This publication has fewer rules and a very basic UI that enables the end user to select options and create a valid configuration very quickly.

Defining a Publication

This section explains:

Source and Remote Publications

Defining a publication in Oracle Configurator Developer creates a source publication with a unique publication ID in the CZ_MODEL_PUBLICATIONS table in the development database instance. When the publication and Model data is exported to the target database instance (by running a concurrent program), a record of the publication is created on the target database: this is called a remote publication. Each value in a source publication record corresponds to a value in the remote publication record. For details, see Data created when a configuration model is published. For details on creating a publication in Oracle Configurator Developer, see Configuration Model Publication Concurrent Programs.

Do not confuse the term "remote publication" with the process of publishing a Model to a remote database instance. Creating a remote publication means creating a publication on an instance other than the one on which Configurator Developer is running. For more information, see Target Database Instance.

If a publication target instance is converted to a development instance, the source publication records are modified accordingly (see the Convert Publication Target Instance to Development Instance concurrent program for details). The publications on the source instance are marked as OBSOLETE, and the only action allowed on these publications is Delete.

When you define a publication record, Oracle Configurator Developer checks the source publication’s attributes and applicability parameters to be sure they do not overlap with other source publications.

Warning: Configurator Developer does not compare the source publication to any remote publications, even if the target database is the same database on which Configurator Developer is running. In other words, the publishing process does not prevent users from publishing Models from multiple development instances to the same target instance. You can only be sure that you are not creating publications with overlapping applicability parameters in the same database (and possibly causing data synchronization errors) if you publish from a single development instance. For this reason, be sure that users publish configuration models from only one source database.

Tables Used in Publishing

The following database tables are used during the publishing process:

For detailed information about the publishing tables (or any other tables in the CZ schema), see the CZ eTRM on MetaLink, Oracle’s technical support Web site.

Publication Details

Access to a publication is determined in part by a publication’s details and applicability parameters. When you create a new publication or edit an existing publication, these details are found in the Publications area of the Repository in Configurator Developer. A publication’s details define the runtime circumstances and environment in which the published configuration model (that is, the publication) is available.

This section contains information about how the publication’s details are used internally by the runtime Oracle Configurator. The publication details described are:

For general information about the publication attributes, including how to specify them when creating the publication record, see the Oracle Configurator Developer User’s Guide.

Model

The Product ID column in the Publications area of the Workbench corresponds to the MODEL_KEY field in the CZ_MODEL_PUBLICATIONS table. This MODEL_KEY is the CZ_DEVL_PROJECTS.DEVL_PROJECT_ID that displays the CZ_DEVL_PROJECTS.NAME. This is the Model name that appears in the General areas of the Workbench in Configurator Developer.

Product ID

Product ID is a designation relevant when publishing in Oracle Configurator Developer. There is no corresponding Product node in a configuration model’s structure.

The Product ID field in the Publications area of the Workbench displays different information depending on whether the specified Model is an imported BOM Model or a Oracle Configurator (non-BOM) Model.

If the configuration model is based on an imported BOM Model, the Product ID consists of the organization ID and Oracle Inventory Item ID, which are derived from Oracle Inventory (for example, 101 : 214738). This value is stored as the PRODUCT_KEY in CZ_MODEL_PUBLICATIONS, CZ_DEVL_PROJECTS, and CZ_IMP_DEVL_PROJECTS. In this case, the Product ID is read-only.

If the publication is based on a non-BOM Model that does not reference an imported BOM Model, and the PRODUCT_KEY field in CZ_DEVL_PROJECTS is not null, then that value is used in the publication record and is read-only. If the value is null, then the user enters a value.

If the publication is based on a non-BOM Model and does contain a Reference to a BOM Model, the Product ID consists of the imported BOM Model’s Oracle Inventory Item ID and Organization ID. In this case, the Product ID is read-only.

Note: If the Model you specified is a non-BOM Model, then the default Product ID is the name of the root Model node. For imported BOM Models, this value consists of the BOM Model’s Item ID and Organization ID (defined in Oracle Inventory). You can change the Product ID when publishing a non-BOM Model; otherwise, it is read-only.

The PRODUCT_KEY and the product_id parameter specified by the host application’s session initialization message are the same. For more information about the session initialization message, see Session Initialization.

User Interface

If the configuration model specified by the publication has multiple User Interfaces, then the list of available User Interfaces on the Publications Repository page comes from the CZ_UI_DEFS table. The available User Interfaces are determined by the selected configuration model.

Target Database Instance

The list of values for this parameter includes all databases listed in the CZ_SERVERS table. This parameter indicates the database to which the publication and Model data are copied when you run one of the Configuration Model Publication Concurrent Programs. The database you specify can be the same instance on which Configurator Developer is running, or a different one (that is, a remote database instance). However, Oracle strongly recommends that all source and target instances which participate in publishing be located on the same local area network. When publishing over a wide area network, performance can be degraded by network factors.

Before you can publish to a remote database instance, it must be defined and enabled. For details, see the Server Administration Concurrent Programs. Note that the first time you create a publication on a remote database instance, the instance changes to a publication target, and Configurator Developer can no longer be accessed on that instance. To change it back to a development instance, run the Convert Publication Target Instance to Development Instance concurrent program.

Mode

Values for this parameter include Test, Production, or Disabled. For information about the publication_mode parameter in the session initialization message, see Initialization Parameter Descriptions. See the Oracle Configurator Installation Guide for information on the Oracle Applications profile option CZ: Publication Lookup Mode.

Publication Applicability Parameters

Applicability parameters determine the availability of a publication to host applications. This section describes how the publication applicability parameters are used internally by the runtime Oracle Configurator. The applicability parameters are:

For general information about applicability parameters, including how to specify them when publishing, see the Oracle Configurator Developer User’s Guide. For more information about how a host application interacts with these parameters to select a publication, see Model Publication Identification Parameters.

Applications

When creating a publication, the entries in the CZ_EXT_APPLICATIONS table appear in Applications list of values on the Publications page. These entries are host applications that support Oracle Configurator as well as any application that an Oracle Configurator Administrator has added to the CZ_EXT_APPLICATIONS table.

If an application does not appear in the Applications list, and you want to make publications available to that application, then the Oracle Configurator Administrator can add it to the list by running the Add Application to Publication Applicability List concurrent program. For more information about the CZ_EXT_APPLICATIONS table, see the CZ eTRM on MetaLink, Oracle’s technical support Web site.

When you save a publication, the specified applications and publication ID are stored in the CZ_PB_CLIENT_APPS table.

Languages

The Languages applicability parameter is stored in the LANGUAGE column in CZ_MODEL_APPLICABILITIES_V. The Language list of values is retrieved from the FND_LANGUAGES table.

For information about Multiple Language Support (MLS), see Multiple Language Support.

Usages

The Usages defined in Oracle Configurator Developer are stored in the following tables:

The Usage Names are displayed in the list of values when assigning Usages to a publication on the Model Publication page. The Usages assigned to a publication are stored in CZ_PUBLICATION_USAGES.

For an example of how Usages are used by a host application at runtime, see Example: How a Usage Affects Model Structure, Rules, and Model Publications at Runtime.

For general information about Usages and how to define them in Configurator Developer, see the Oracle Configurator Developer User’s Guide.

Date Range

A publication’s effective dates are stored in the columns APPLICABLE_FROM and APPLICABLE_UNTIL in the CZ_MODEL_PUBLICATIONS table.

Publishing a Configuration Model

After defining a source publication in Oracle Configurator Developer, the configuration model data must be copied to the target database by doing one of the following:

Each of these tasks create a remote publication on the target database. When the publication completes successfully, the remote publication can be accessed by host applications such as Oracle Order Management or iStore. The CZ_MODEL_PUBLICATIONS table stores the high level information about the publication. A new entry is entered into the CZ_DEVL_PROJECT table. For table details see the CZ eTRM on MetaLink, Oracle’s technical support Web site.

Data created when a configuration model is published shows some of the data that is created when a configuration model is published.

Data created when a configuration model is published

Illustration of a Publication Record Mapping illustrates how the source and target publication records have corresponding values in the database. This correspondence allows source and target publications to be matched when updating or synchronizing the publication data.

Illustration of a Publication Record Mapping illustrates how PUBLICATION_ID 5721 in the source publication corresponds to REMOTE_PUBLICATION_ID 5721 in the target publication. The illustration also shows that REMOTE_PUBLICATION_ID 5760 in the source publication corresponds to PUBLICATION_ID 5760 in the target publication. The source publication’s SERVER_ID is 5, which corresponds to the SERVER_ID entry in the CZ_SERVERS table (whose value is also 5).

Illustration of a Publication Record Mapping

the picture is described in the document text

In the source database instance, the SERVER_ID column in the CZ_SERVERS table identifies the target’s SERVER_ID. This same column and table on the target database instance is the target’s SERVER_ID (not the source’s SERVER_ID).

For more information about defining publications, examples of overlapping publications, and UI Templates, see the Oracle Configurator Developer User’s Guide.

For more information, see Configuration Model Publication Concurrent Programs.

Publication Profile Options

If a Usage or publication mode is not specified in the session initialization message, then the following profile options provide default values for these parameters:

Publishing and Model References

If you are publishing a configuration model that has References to other Models, then all of the referenced Models are also copied to the target database and are part of the publication. If a referenced Model itself is not published, then it can only be configured as part of its parent (the published Model). In other words, an end user can configure only Models that have been published.

The availability of referenced Models is controlled by the Usages and Date Range applicability parameters. See the Oracle Configurator Developer User’s Guide for more information on the Usages and Date Range applicability parameters.

Copying User Interface Data

The runtime Oracle Configurator UI supports the use of UI Templates and generated User Interfaces. Publishing a configuration model copies the following UI-specific data:

Copying Model Rules

By default, the publishing process copies all configuration model data to the target database. You can control whether rules defined in Configurator Developer are copied using the PublishingCopyRules setting in the CZ_DB_SETTINGS table. This setting does not affect Configurator Extension Rules; all Configurator Extension Rules are always copied when you publish or republish a configuration model.

For more information about the PublishingCopyRules setting, see PublishingCopyRules.

Checking BOM Model and Configuration Model Similarity

When you are publishing to a remote server, the publication concurrent programs call the Model synchronization concurrent programs. If there are key discrepancies between the source BOM Model and the configuration model to be published, such as the Items on both Models are not the same, then an error message is logged by the publication concurrent program and the configuration model is not published.

Publishing Error when Checking BOM Model and Configuration Model illustrates an error found in CZ_DB_LOGS file when attempting to publish a configuration model (publication ID = 28261).

Publishing Error when Checking BOM Model and Configuration Model

Unable to proceed with publishing because the configuration model 'SOURCE MODEL1-Pub Synch(204 501069)' does not match the corresponding bill on the target server. The model has not been published.
     28261     36638
BOM Synchronization, version 115.29, started 2002/12/18/16:27:41, session run ID: 36639
     28261     36638
Maximum quantity does not match for item 'ATO OC6' with parent 'ATO Model4' in configuration model '
SOURCE MODEL1=>PTO Model2=>ATO Model3=>ATO Model4'
     28261     36638
Process terminated for publication_id: 28261
     28261     36638

For more synchronization information, see The BOM Model Synchronization Process.

Maintaining Publications

Typically, a configuration model may undergo many iterations of testing and updates before it is made available to customers in a production environment. Publishing gives you complete control over each step in a configuration model’s lifecycle, enabling you to maintain and update Models that are under development while making approved versions available in your production environment.

The following illustration shows an overview of the publication process, in which a user creates a new publication from Configurator Developer on the Development database, tests the Publication, updates the Model in Configurator Developer, and republishes the Model. Once the publication has been tested thoroughly, a Developer user changes the Mode applicability parameter to Production, or creates a new publication and selects the Production database as its target.

Example of the Publication Process

the picture is described in the document text

Publication Status

The operations you can perform on an existing publication depend on its current status. You can view detailed information about publications, including their status, on the Model Publication page in Configurator Developer.

The table Publication Status and Valid Operations lists each status and the corresponding tasks you can perform.

Publication Status and Valid Operations
Status New or
New Copy		 Edit Republish Delete Disabled Edit UI
Complete Y Y Y Y Y N
Pending Y Y N Y Y N
Update Pending Y N N N N N
Processing Y N N N N N
Error Y N N Y N N
Obsolete Y N N Y N N

Configurator Developer updates the status of all publications whenever you navigate to the Publication Repository page or click the Browser Refresh. The Status column may change, for example, when one of the publication concurrent programs completes successfully.

Following is a description of each publication status:

Editing Publications

When an Oracle Configurator Developer user edits a publication, the changes are automatically propagated to the remote publication in the CZ_MODEL_PUBLICATIONS table (in the target database).

Depending on the changes made in Oracle Configurator Developer, editing the publication may involve adding or deleting records in the CZ_PB_CLIENT_APPS or CZ_PUBLICATION_USAGES tables, or changing the publication’s mode or valid date range.

For information on how to edit a publication, see the Oracle Configurator Developer User’s Guide.

Note: If you publish a new version of the Model and there are previous published versions in memory because you are still running on the same Apache JServ, users could get out of memory errors if the max heap size can't accommodate all of the published Models in memory. You can increase the maximum heap size (which could degrade performance) or bounce Apache to clear the previous publication out of memory. Oracle Applications Java Caching Framework provides the ability to manage the caching and decaching of Model and UI data, which optimizes both runtime performance and memory management. For more information, see the Oracle Configurator Performance Guide.

Disabling, Deleting, and Re-enabling Publications

You can make a publication unavailable to host applications by disabling it in the Publication Repository. When a publication is disabled, it remains listed in the Publication Repository, its status does not change, but the publication’s Disabled column notes that the publication has been disabled. When a publication is disabled you can modify its applicability parameters or re-enable it.

You can also delete a publication. When you delete a publication, it no longer appears in the Publication Repository page in Oracle Configurator Developer, and it cannot be recovered. However, the publication record still exists in the CZ schema until the Purge Configurator Tables concurrent program is run. For more information on the Purge Configurator Tables concurrent program, see Purge Configurator Tables.

See the Oracle Configurator Developer User’s Guide for more information on disabling, deleting and re-enabling publications.

Republishing

This section describes the database tables that are updated when you republish a configuration model. For information about how to republish a configuration model in Configurator Developer, see the Oracle Configurator Developer User’s Guide.

When an Oracle Configurator Developer user republishes a configuration model, the following occurs:

  1. The status of the original publication changes to PUP (Pending Update) in the Publication Repository, and STATUS is PUP in the CZ_PB_MODEL_EXPORTS table. The publication status does not change until one of the publication concurrent programs completes successfully.

  2. A new publication record is created in the CZ_MODEL_PUBLICATIONS, CZ_PB_CLIENT_APPS, and CZ_PUBLICATION_USAGES tables of the publication source development instance. This publication record has the same applicability parameters as the original publication.

Note: If you set the profile option CZ: Populate Decimal Quantity Flags to Yes and then reimport or refresh your BOM Models, you must republish existing Model publications to ensure that they use the new setting. Decimal quantities are explained in Importing Decimal or Integer Quantities.

Note: If a new language has been added to Oracle Applications, then you must republish your Models in order for the User Interface labels to be displayed in the new foreign language. For more information on MLS, see Multiple Language Support.

Determining Publishing Information

Knowing the UI_DEF_ID can be helpful when you want to look up information about a publication using SQL*Plus. Using the Publication ID from Oracle Configurator Developer’s Publication Repository in a simple SQL*Plus query returns the UI_DEF_ID. The UI_DEF_ID can then be used in queries on the CZ_CONFIG_HDRS, CZ_MODEL_PUBLICATIONS, CZ_UI_DEFS, CZ_UI_NODES, CZ_UI_NODE_PROPS, CZ_UI_PROPERTIES.

Query for UI_DEF_ID

select ui_def_id
from cz_model_publications
where publication_id=publication number ;
  UI_DEF_ID
     2760

UI_DEF_ID can also be found in CZ_UI_DEFS, or by calling the PL/SQL function cz_cf_api.ui_for_item. For more information about this function, see Reference for the CZ_CF_API and the CZ_CONFIG_API_PUB Packages.

Retrieving Orders from Previously Published Models

A situation may develop where you want to retrieve prior orders that were placed against a previously published Model, rather than the more recent Model that has new structure and new rules. For example, when the first Model was published the From and To Date Range applicability parameters were not specified.

To retrieve orders for the previously published Model, you must:

  1. Edit the first published Model’s Date Range applicability parameter to have an end date.

  2. Republish the Model.

  3. Publish the newer Model with the From Date Range applicability parameter equal to the To Date Range of the first published Model.

Note: If a previously published configuration model is modified in Configurator Developer and is then republished, then end users can restore any saved configurations that were created using the original publication. However, if the Model’s structure or rules have changed, the end user may need to make additional selections to create a valid and complete configuration.

See the Oracle Configurator Developer User’s Guide to learn how to perform these tasks.

Synchronizing Publication Data

Publication data must be synchronized whenever you:

For more information, see Synchronizing Data.

Example of Maintaining Publications

This section provides an example of how a business may develop configuration models and maintain publications in a development environment. An organization has a laptop computer called M1A that is currently in production. However, a new version of M1A is under development and this computer, M1B, will replace M1A by the end of the year. The new Model must replace the older version in the production environment and there can be no period of time when neither is available to customers.

Maintaining Publications provides an overview of how this organization plans to develop, test, and release M1B into production. It is a time line that lists the typical activities involved in maintaining a Model publication. Details of each step and a description of the table are provided in the text following the table.

Maintaining Publications

the picture is described in the document text

Details

The following steps correspond to the ID column in the project schedule shown in Maintaining Publications.

  1. Using Configurator Developer, the development team creates a new configuration model (M1B) to reflect the new product’s features and enhancements. The Model is unit tested periodically in Oracle Configurator Developer, but it is not yet made available for system testing.

  2. The new configuration model is complete and ready for system testing.

  3. Developers create publication P1 and sets its publication Mode to Test. The publication is effective immediately and no end date is required because it can be modified at any time. The Applications and Usages parameters specify which host applications and end users can access the Model.

  4. The quality assurance (QA) group accesses and tests the configuration model for product M1B and reports any problems to the development group. The host application that the testers use selects the configuration model to display based on the applicability parameters defined for publication P1.

  5. The first round of testing configuration model M1B is complete.

  6. Developers incorporate comments from testers by updating the configuration model in Configurator Developer. This may include building new Model structure, creating or modifying rules, or updating the User Interface.

  7. When changes to the Model are complete, developers republish the Model. Republishing copies any new or modified data to the specified database so that the QA group can begin a second round of testing. Republishing does not change any of the original applicability parameters, so publication P1 is available to the same host applications and users as in the first round of testing.

  8. The QA group performs a second round of testing Model M1B.

  9. The second round of testing is complete and additional comments are reported to the development group.

  10. Developers update the configuration model in Configurator Developer.

  11. Company management and the development group agree that the configuration model is ready for production. In this enterprise, the development and production environments exist on the same database, so a developer makes the product available to customers by modifying the applicability parameters of the existing publications as follows:

    1. Change the publication Mode P1 from Test to Production

    2. Change the To Effectivity Date of the now obsolete publication for Model M1A to 12:00:00 a.m. on 01/01/01

    3. Specify a From Effectivity Date for publication P1 of 12:00:00 a.m. on 01/01/01

    This modification ensures that there is no gap in the availability of the old and new products because M1A becomes obsolete at the same time M1B becomes available in production.

See the Oracle Configurator Developer User’s Guide for more information.