Pricing and ATP in Oracle Configurator

This chapter provides an overview of how pricing works in a runtime Oracle Configurator.

This chapter covers the following topics:

• Overview
• Introduction
• Runtime Oracle Configurator Pricing Architecture
• Runtime Pricing Behavior
• Integration of Pricing and ATP with Oracle Configurator
• Controlling Pricing and ATP in a Runtime Oracle Configurator

Overview

This chapter describes the integration of pricing and ATP with Oracle Configurator. It includes:

• Runtime Oracle Configurator Pricing Architecture

• Runtime Pricing Behavior

• Integration of Pricing and ATP with Oracle Configurator

• Controlling Pricing and ATP in a Runtime Oracle Configurator

Note: If your host application is part of Oracle Applications, then the integration with pricing and ATP is already defined. You only need to implement pricing and ATP for custom host applications. The CZ_PRICING_STRUCTURES and CZ_ATP_REQUESTS tables must be populated for custom host applications to integrate with pricing and ATP.

Introduction

How Oracle Configurator handles pricing and ATP (Available To Promise) data depends on the type of runtime Oracle Configurator you choose to use. A runtime Oracle Configurator can be called from a variety of different applications and requires an interface between the runtime Oracle Configurator and the host application’s pricing mechanism. For more information on advanced pricing, see Oracle Advanced Pricing User’s Guide.

Runtime Oracle Configurator Pricing Architecture

When the host application is part of Oracle Applications, such as Order Management, pricing data comes from Oracle Advanced Pricing (QP). The QP interface is highly configurable. Depending on how it is configured, it may be necessary that appropriate data records are defined in the host application to determine pricing parameters. The host application must implement the Oracle Configurator pricing interface package, as described in Pricing Callback Interface. Likewise, when the host application is not an Oracle Applications product, it must implement the Oracle Configurator pricing interface package, so that the runtime Oracle Configurator knows how to determine prices.

Therefore, the host application must provide an interface PL/SQL package that interacts whenever pricing is requested between the runtime Oracle Configurator and the host application's pricing engine. The runtime Oracle Configurator is displayed when the user clicks the Configure button in the host application. The runtime Oracle Configurator calls the pricing interface package to get:

• List prices for all selectable options in the configuration

• Selling prices for all selectable options in the configuration

• Total price for the entire configuration

The browser presents either list prices for all selectable options, or selling prices for all selected options, and enables you to add a total price.

For more information about the Pricing Callback Interface, see Pricing Callback Interface .

Pricing Callback Interface Package

The host application sends an initialization message to the runtime Oracle Configurator with the interface package and procedure name. The runtime Oracle Configurator calls this interface package to get current pricing information for a single item or a list of items.

The interface package determines the full context in which to call the target pricing engine. The interface package then calls the pricing engine and captures all of the results, storing these results in tables (or some other Oracle session-insensitive place) for future reference when the runtime Oracle Configurator session exits. The runtime Oracle Configurator does not reference the contents of these tables.

The interface package temporarily writes the list and/or selling prices for the configuration components in the temporary CZ_PRICING_STRUCTURES table so that they can be presented to the end user.

The CZ_PRICING_STRUCTURES table does not support pricing rules based on the fact that items belong to the same instance. Pricing is done per component instance.

The runtime Oracle Configurator saves the configuration information in the appropriate CZ tables. The runtime Oracle Configurator does not save list or selling prices. It is up to the host application to save configuration data, list prices, and selling prices in its own tables. For example, Order Management stores the configuration in OE_ORDER_LINES_ALL, and stores the pricing data in OE_PRICE_ADJUSTMENTS. The host application decides whether it is necessary to recalculate prices depending on the value of the prices_calculated_flag in the runtime Oracle Configurator termination message.

When the host application calls the runtime Oracle Configurator to edit an existing configuration, the runtime Oracle Configurator asks the interface package for the current list and selling prices of the currently selected components.

Runtime Oracle Configurator Pricing Architecture, illustrates this architecture. Illustrated steps 2 through 5 can be repeated many times. Note that in Runtime Oracle Configurator Pricing Architecture, all of the database symbols refer to the same instance of the CZ schema.

Runtime Oracle Configurator Pricing Architecture

See the Pricing Callback Interface for details about the pricing interface package, and see Session Initialization and Session Termination for details about the initialization and termination messages for a runtime Oracle Configurator session.

Pricing Callback Interface

The pricing callback interface package provides interfaces for these distinct procedures:

• Price Multiple Items

• Price Multiple Items for MLS

The Price Multiple Items procedure returns price information for a group of items. The Price Multiple Items Procedure Parameters table describes the parameters for this procedure.

Price Multiple Items Procedure Parameters

Parameter	In/Out	Type	Required	Note
configurator_session_key	In	Varchar2	Required	Limit of 50 characters
price_type	In	Varchar2	Required	Values are: LIST, SELLING, or BOTH
config_total_price	Out	Number nocopy	n/a

The Price Multiple Items MLS procedure returns price information for a group of items. The Price Multiple Items MLS Procedure Parameters table describes the parameters for this procedure.

Price Multiple Items MLS Procedure Parameters

Parameter	In/Out	Type	Required	Note
configurator_session_key	In	Varchar2(50)	Required	Limit of 50 characters
price_type	In	Varchar2	Required	Values are: LIST, SELLING or BOTH
config_total_price	Out	Number nocopy	n/a
currency_code	Out	Varchar2 nocopy	n/a

The parameters of the interface are passed by positional notation, so you can name the parameters as wanted, as long as you retain the positionality specified in Price Multiple Items Procedure Parameters and Price Multiple Items MLS Procedure Parameters.

Use of the Database in the Price Multiple Items Procedures

When you specify the Price Multiple Items procedures, Oracle Configurator stores the list of items to be priced in the database table CZ_PRICING_STRUCTURES. This columns in this table are described in CZ_PRICING_STRUCTURES Interface Table.

CZ_PRICING_STRUCTURES Interface Table

Column Name	Data Type	Null?	Description
CONFIGURATOR_SESSION_KEY	Varchar2	Not Null	Limit of 50 characters. Primary key. Identifies a configurator session. Only one configuration can be handled in the session.
SEQ_NBR	Number	Not Null	Primary key. Sequence number of the item in the list of items.
PS_NODE_ID	Number		Limit of 9 digits. PS_NODE_ID is a foreign key reference into the CZ_PS_NODES table, which defines the "configuration" identity of the object.
ITEM_KEY	Varchar2	Not Null	Limit of 2000 characters. ORIG_SYS_REF for imported items or PS_NODE_ID for non-imported items.
ITEM_KEY_TYPE	Number	Not Null	Limit of 9 digits. Set to 1Value of CZ_PRC_CALLBACK_UTIL.G_ITEM_KEY_BOM_NODE. if ITEM_KEY is ORIG_SYS_REF. Set to 2Value of CZ_PRC_CALLBACK_UTIL.G_ITEM_KEY_PS_NODE. if ITEM_KEY is PS_NODE_ID.
QUANTITY	Number		Limit of 9 digits. Item quantity
UOM_CODE	Varchar2		Limit of 3 characters. UOM code
LIST_PRICE	Number		List price
SELLING_PRICE	Number		Selling price
MSG_DATA	Varchar2		Limit of 2000 characters. Message text filled in by your host application.
CONFIG_ITEM_ID	Number	Not Null	This corresponds to the CZ_CONFIG_ITEMS.CONFIG_ITEM_ID. Note: CZ_PRICING_STRUCTURES.ITEM_KEY is unable to establish the full hierarchy of a configuration when there are multiple instantiations.
PARENT_CONFIG_ITEM_ID	Number		Together with CONFIG_ITEM_ID, this establishes the full hierarchy of the configuration when there are multiple instantiations.

Your pricing package must retrieve the items from this table and call the pricing engine, then capture all of the results and update the CZ_PRICING_STRUCTURES table with list and/or selling prices, and any message text. Oracle Configurator retrieves the prices from the CZ_PRICING_STRUCTURES table during the configuration session, so that they can be presented in the Oracle Configurator window. When the Oracle Configurator window exits, Oracle Configurator deletes the pricing records from the CZ_PRICING_STRUCTURES table.

If your host application must retain the prices for use after the end of the current configuration session, then your pricing package must store the results in application-specific tables (or some other location that is insensitive to the Oracle session). Oracle Configurator does not reference the contents of these application-specific tables.

Examples of the Pricing Callback Interface

Pricing Callback Interfaces must populate the CZ_PRICING_STRUCTURES table.

Pricing Callback Interface shows a possible implementation of the callback interface for multiple-item pricing procedures.

Initialization Message Using Release 12Pricing and ATP Parameters shows how to specify pricing parameters in your initialization message.

Pricing Callback Interface

PACKAGE CZ_PRICE_TEST AUTHID CURRENT_USER AS 
PROCEDURE price_multiple_items (p_configurator_session_key IN VARCHAR2, 
                                  p_price_type IN VARCHAR2, 
                                  p_total_price OUT NUMBER); 
END; 

ATP Callback Interface

The "Get ATP Dates" procedure returns availability dates for all PTO Models but only returns the date for the ATO top level Model. The table ATP Procedure Parameters describes the parameters for the Get ATP Dates procedure.

ATP Procedure Parameters

Parameter	In/Out	Type	Required	Note
configurator_session_key	In	Varchar2	Required	Limit of 50 characters
warehouse_id	In	Number	Required
ship_to_org_id	In	Number	Conditionally Required	You must provide either ship_to_org_id (by itself), or both customer_id and customer_site_id.
customer_id	In	Number	Conditionally Required	You must provide either ship_to_org_id (by itself), or both customer_id and customer_site_id.
customer_site_id	In	Number	Conditionally Required	You must provide either ship_to_org_id (by itself), or both customer_id and customer_site_id.
requested_date	In	Date	n/a	If a date is not provided, then the date defaults to the SYSDATE.
ship_to_group_date	Out	Date nocopy	n/a

The parameters of the interface are passed by positional notation, so you can name the parameters whatever you want, as long as you retain the positionality specified in ATP Procedure Parameters.

Use of the Database with the ATP Callback Interface

When you specify the Get ATP Dates procedure, Oracle Configurator stores the list of items to obtain ATP dates for in the database table CZ_ATP_REQUESTS. For details on Oracle Configurator tables, see the CZ eTRM on MetaLink, Oracle’s technical support Web site.

If you are using the Oracle ATP pricing mechanism, then your ATP package must retrieve the items from the table and call the call_atp() procedure defined in your ATP package, then capture all of the results and update the CZ_ATP_REQUESTS table with ATP dates.

Oracle Configurator retrieves the ATP dates from the CZ_ATP_REQUESTS table during the configuration session, so that they can be presented in the Oracle Configurator window. When the Oracle Configurator window exits, OC deletes the ATP dates from the CZ_ATP_REQUESTS table.

If your host application must retain the ATP dates for use after the end of the current configuration session, then your ATP package must store the results in application-specific tables (or some other location that is insensitive to the Oracle session). Oracle Configurator does not reference the contents of these application-specific tables.

Examples of the ATP Callback Interface

ATP Callback Interface shows an implementation of the callback interface for ATP procedures.

Initialization Message Using Release 12Pricing and ATP Parameters shows how you would specify ATP parameters in your initialization message.

Example of Callback ATP Procedure provides an example in context.

ATP Callback Interface

PACKAGE cz_atp_callback AS 
  PROCEDURE call_atp (p_config_session_key IN VARCHAR2, 
                      p_warehouse_id IN NUMBER, 
                      p_ship_to_org_id IN NUMBER, 
                      p_customer_id IN NUMBER, 
                      p_customer_site_id IN NUMBER, 
                      p_requested_date IN DATE, 
                      p_ship_to_group_date OUT NOCOPY DATE); 
END cz_atp_callback; 

Runtime Pricing Behavior

It is important to understand some aspects of pricing behavior in the runtime Oracle Configurator, as they can affect both performance and the responsibilities of the host application.

• The runtime Oracle Configurator caches list prices of the items until it is terminated. The runtime Oracle Configurator assumes that the list price of any item does not depend on which other items are selected and remains unchanged during the configuration session.

• The runtime Oracle Configurator’s performance depends critically on the performance of the pricing interface package that you provide. List prices in particular must be returned very quickly, because they are demanded for every option that is displayed.

• The runtime Oracle Configurator does not save computed prices. If, after the configuration session ends, the host application requires access to prices that were computed during the session, it is up to the host application’s interface package to save the computed prices. Prices should be saved together with enough information to allow them to be correlated with the components of the saved configuration.

• If the runtime Oracle Configurator is initialized with a previously saved configuration, it is up to the host application to either return the saved list and selling prices or to call the pricing engine to get the current price. Direct or manual editing of prices, adjustments, discounts, and so on is the responsibility of the host application.

Integration of Pricing and ATP with Oracle Configurator

Integrating the Oracle Configurator window with your pricing or ATP implementation consists primarily of causing your host application to post the XML initialization message to the OC Servlet (for example, through the coding of the Configure button), passing as initialization parameters the names of your packages and procedures.

To use the OC pricing and ATP interfaces, you must:

1. Install the OC interface packages in your database, by installing Oracle Configurator with Oracle Rapid Install. See Database Compatibility.

2. Write your own PL/SQL pricing or ATP procedures, using the OC interfaces. See Pricing and ATP Callback Procedures for examples.

3. Install your packages containing your procedures into the Oracle Applications database.

   You can interface to the Oracle QP pricing engine from your own procedures.

4. In the initialization message that your host application passes to the OC Servlet, provide parameters that specify the name of the pricing package, the name of the ATP package, the procedure to use, and the type of pricing to perform.

   See Initialization Parameters for an example. See Pricing Parameters and ATP Parameters for explanation of the parameters.

   You can test the effect of pricing and ATP parameters when you test your Model in Oracle Configurator Developer, by entering the Pricing Package and ATP Package parameters in the in the Custom Initialization Parameters field of the Test Preferences page.

5. Enable pricing display and update behavior, as described in Controlling Pricing and ATP in a Runtime Oracle Configurator.

   Note: The display and updating of pricing are controlled by the values of the database fields CZ_UI_DEFS.PRICE_DISPLAY and CZ_UI_DEFS.PRICE_UPDATE. If these fields are null, then the information is not displayed. For details on these tables, see the CZ eTRM on MetaLink, Oracle’s technical support Web site

Database Compatibility

Oracle Configurator works with Oracle Applications Release 12. To determine the database version supported by Oracle Applications, refer to the Certify and Availability tab on MetaLink, Oracle’s technical support Web site.

To obtain pricing data from an Oracle Enterprise Edition database, as used with Oracle Applications 10.7, 11.0, you must run a concurrent program. See the Populate and Refresh Configuration Models Concurrent Programs.

There are several likely scenarios for pricing and ATP integration. These scenarios are described in the following table:

To Integrate with...	Do the following ...
Oracle Applications Release 12 database	Write your own callback procedures (which can call the QP Advanced Pricing engine). To import BOM Model data to the CZ schema tables, you run concurrent programs in the Oracle Bills Of Material application. To export orders to Order Management (Oracle Applications Release 12), you use existing or new programming in your ­host application.
Third-party database	For both import and export of pricing data, you must write custom programs.

You can use the callback interface in all these scenarios.

Initialization Parameters

Initialization Message Using Release 12 Pricing and ATP Parameters is a test page that shows how you would specify pricing and ATP parameters in your initialization message. The names of the pricing and ATP parameters are typographically emphasized. This example shows parameters for use with Oracle Applications Release 12. See Pricing Parameters and ATP Parameters.

Initialization Message Using Release 12 Pricing and ATP Parameters

<html>
<head>
<title>Pricing Test</title>
</head>
<script language="javascript" >function init() {document.test1.submit();}</script>
<body onload="init();">
<form action="http://www.mysite.com:8802/OA_HTML/CZInitialize.jsp" method="post" id="test1" name="test1"><input type="hidden" name="XMLmsg" value='<initialize>
<param name="database_id">serv02_sid01</param>
<param name="user">operations</param>
<param name="pwd">welcome</param>
<param name="calling_application_id">708</param>
<param name="responsibility_id">22713</param>
<param name="ui_type">JRAD</param>
<param name="ui_def_id">3080</param>
<param name="pricing_package_name">cz_price_test</param>
<param name="price_mult_items_proc">price_multiple_items</param>
<param name="configurator_session_key">1234</param>
<param name="atp_package_name">cz_atp_callback_stub</param>
<param name="get_atp_dates_proc">call_atp</param>
<param name="warehouse_id">207</param>
<param name="customer_id">1000</param>
<param name="customer_site_id">1567</param>
</initialize>'>
</form>
<br>Loading ...
</body>
</html>

To obtain the final prices calculated by your pricing package and ATP package, you need to specify a value of full for the initialization parameter terminate_msg_behavior. When your configuration session terminates normally, Oracle Configurator returns the final prices in the termination message. Your host application can then save the prices as needed.

Controlling Pricing and ATP in a Runtime Oracle Configurator

This section describes how to display prices and Available to Promise (ATP) information in a runtime Oracle Configurator.

Following is an overview of the process:

1. Define the following profile options, as required: CZ: Enable List Prices, CZ: Enable Selling Prices, CZ: Enable ATP.

   For details, see the Oracle Configurator Installation Guide.

2. In Oracle Configurator Developer, select pricing and ATP settings for the generated User Interface.

   For details, see Displaying Prices and ATP Information.

3. If you are deploying a custom application, set the appropriate parameters in the initialization message that is posted to the OC Servlet.

   For details about the initialization and termination messages for pricing and ATP, see Session Initialization and Session Termination.

   For details about the pricing interface package, see Pricing Callback Interface .

Displaying Prices and ATP Information

If you have defined the required profile options, you can control which types of prices and availability information is displayed and how they are updated in a generated User Interface. To do this, edit the UI Definition in Oracle Configurator Developer and modify the Price and Availability Display settings.

For example, you set CZ: Enable List Prices and CZ: Enable ATP to Yes. You can prevent list prices and ATP data from appearing in a UI by deselecting the List Prices and Availability settings in the UI Definition.

For details about the pricing and ATP settings available at the UI Definition level, and how to modify them, see the Oracle Configurator Developer User’s Guide.

Updating Prices

If pricing is enabled and the UI Definition’s pricing settings are set to display prices at runtime, the Recalculate Prices setting controls what action causes selling prices to be updated. You can set this to

• On Request

• On Page Load

• On Change

For details about these settings, see the Oracle Configurator Developer User’s Guide.

Examples of Controlling Pricing

This section lists how the various settings that control pricing can be used together.

Example: List Prices Only

List Price Profile Option and UI Definition Settings lists the recommended property or setting if you want to display only list prices at runtime.

List Price Profile Option and UI Definition Settings

Profile Option or Setting	Value
CZ: Enable List Prices	Yes
Price Display Style	List Price
Price Update	On Request

Example: Selling Prices Only

The table Selling Price Profile Option and UI Definition Settings lists recommended settings if you want to display only selling prices.

Selling Price Profile Option and UI Definition Settings

Property or Setting	Value
CZ: Enable Selling Prices	Yes
Price Display Style	Selling Price
Price Update	On Request