This chapter covers the following topics:
This chapter describes the integration of Oracle iStore with Oracle Configurator.
Oracle Configurator allows user configuration of complex items. It also provides guided selling, where the user is offered a list of choices or sequential questions to create a hierarchical list of items to view and purchase. Oracle Configurator is used to create product models and to help the buyer assemble related and dependent products in the shopping cart.
You can use the Configurator Developer UI to create the product models for dependent and related products, and to build rules around the products.
To be configurable in Oracle iStore, a product model must have the following characteristics:
The model and its associated option classes and standard items are defined in the Master Inventory Organization and assigned to the shipping organization.
The model has a BOM item type of "Model" in Oracle Inventory, and its associated options have a BOM item type of "Option Class."
The model and its associated options are Published and Orderable on the Web.
The model and its associated option classes have a BOM structure defined in Oracle Bills of Material.
The model and its components have been added to a price list. You can set the price of the option classes to zero if necessary, but they must be assigned to a price list.
You have transferred the model and its components to the Oracle Configurator schema by running the Populate Configuration Models concurrent program from Oracle Manufacturing. (Choose Flow Manufacturing, Setup, Other, Configurator, Populate Configuration Models.)
If you changed the model and its components in Oracle Order Management after you populated it into the Oracle Configurator schema, then you must run the Refresh Configuration Models concurrent program from Oracle Manufacturing. (Choose Flow Manufacturing, Setup, Other, Configurator, Refresh Configuration Models.)
The product models are imported initially from BOM models. You can use the Configurator Developer UI to create a tree structure for the product model. For example, if customers want to build their own laptops from a site of electronic items, then you can use the Configurator Developer UI to define the structure and the dependent (mandatory and optional) products (e.g., a 15” or 17” screen with 16MB or 32MB RAM and 6GB or 8GB drive).
Oracle iStore allows users to configure items by retrieving the Configurator module through the Customer UI. This functionality is discussed in this section.
The following is the business flow for configuring items in the Customer UI.
When the customer is browsing items in an Oracle iStore site, a Configure button appears next to each configurable item. Configurable items have a BOM item type of "Model" in Oracle Inventory, and are associated with a Configurator UI. In the shopping cart, a Reconfigure link appears underneath the top item in a configured item.
Note that configured items are not merged in the shopping cart, regardless of the setting of IBE: Merge Shopping Cart Lines.
When the user selects Configure, the site sends a message to populate the Configurator UI with the item ID. The Configurator UI appears in the frame provided in an Oracle iStore page. Here, the related or dependent products can be assembled for placing the order.
Once the customer has finished building the list of selected items for the order, selecting Done in the Configurator UI's top menu bar places all the items in the shopping cart.
In the shopping cart, the user can update the quantity for the top level item.
Note: Launching Oracle Configurator from Oracle iStore is not supported if users are connected to your sites through Secure Socket Layer (SSL) network connections.
See Oracle Configurator Developer User's Guide for detailed setup documentation.
Oracle iStore gets the Configurator UI via the Oracle Configurator Servlet URL, which handles all interaction between the client and the server. The URL is the location where the Oracle Configurator servlet resides. The installer of the servlet sets up this URL. For example, the URL could be
http://apps-server-host:8800/oa_servlets/oracle.apps.cz.servlet.UiServlet
The server and directory structure are installation-specific information that the calling application must read, but the oracle.apps.cz.servlet.UiServlet portion is always the same. Oracle iStore reads this URL from the profile option, BOM: Configurator URL of UI Manager. Set this profile option to the correct URL. You must also set the profile option, ASO: Configurator URL to the same URL.
The Configurator UI is created with DHTML or a Java applet. The look and feel are similar to the Oracle iStore UI. If you want to change the Configurator UI, you can modify the HTML templates for Oracle Configurator. These templates are loaded in Oracle iStore's html directory on the same server by default. The Oracle Configurator data is stored in the CZ tables in the APPS schema.
If you change the UI for a model in Oracle Configurator Developer, you must restart the Application server and clear the cache before the new UI is available in Oracle iStore.
Oracle Configurator Developer allows users to create configuration models using Oracle Inventory items and pre-existing ATO/PTO models, and to allow runtime users to order such models through Oracle iStore -- this is the goal of Solution-Based Modeling.
With Developer-created models, configuration users can create multiple instances of a configurable model component, with each model component configured differently -- this is known as multiple instantiation. In Oracle iStore, multiple instantiation enables Customer UI users to add components during their user session, adding and configuring as many separate components as needed. Oracle iStore displays and prices each sub-model according to its individually selected options.
Note that this does not require integration with Oracle Advanced Pricing.
To allow Oracle iStore (and Oracle Quoting) to distinguish between multiple instances of a component, the field aso_quote_line_details.config_item_id is used. When cart (quote) lines are added to a cart (quote) from a saved configuration, this field is populated with the config_item_id from aso_i_config_details_v.config_item_id.
Oracle iStore prices a configuration together with the rest of the cart lines. When pricing the restored/reconfigured configuration, the current option selections are matched with the previously saved cart lines. To accomplish the re-pricing, Oracle iStore uses the Oracle Configurator columns --- config_item_id and parent_config_item_id --- in the cz_pricing_structures table. These columns contain unique, temporary values for the newly selected items. The config_item_id column has appropriate values for the items existing in the saved configuration. The config_item_id column corresponds to the configuration_id column in Oracle Order Management.
Note that solution based modeling is not supported with Oracle iStore shopping list functionality.
For more information, see the Oracle Configurator Implementation Guide and the Oracle Configurator User Guide.
Companies may wish to distinguish between novice and expert users and then provide an Oracle Configurator UI based on their usage level. For example, Oracle Configurator can be set up so that novice users might only see high level, guided selling questions, while expert users would have access to an alternative UI with detailed options. This ability to distinguish between flows can also impact the model structure, the rules in a configuration session and the specialty site.
In order to support the Oracle Configurator usage functionality, Oracle iStore provides a hook in the API Java layer that allows merchants to supply custom code. The custom code can get the necessary parameters from the cookie and return the usage. If null is returned by the custom code, Oracle iStore does not pass the config_effective_usage parameter in the initialization string -- otherwise, it passes the value returned by the custom code.
If no parameter is passed for usage in the initialization message (config_effective_usage), Oracle Configurator looks at the profile option, CZ: Publication Usage, for the usage value. If the profile has not been set, then Configurator uses the default usage, which is Any Usage.
A Java abstract class, public abstract class ConfiguratorHook, also is provided to act as an interface for a customer to implement the hook. This class contains one method, public abstract String getUsageParameter (String inventoryItemId, HashMap hashedParameters), which throws ConfiguratorException, FrameworkException, SQLException.
Create a Java file in your implementation of this abstract class, and name it CustomConfigHook.java. You can find an example in the section, "Example of CustomConfigHook Java File", below.
Add code and logic to implement the getUsageParameter API to return the usage parameter values used in the Configurator Developer tool to distinguish which UI to use.
Place the class file in the oracle.apps.ibe.configurator package.
Bounce the middle-tier server.
Below is an example of a customized class file implementers might create and compile to pass a usage parameter. Implementers can create their own versions of the CustomConfigHook.java file to return strings created in the Configurator Design tool based on the values which will be the determining factors for retrieving the specified UI (for example, Site ID, whether the user has certain permission or not, values in the cookie, values in the input hash table passed in from customizations in the ibeCFgdFrameSources.jsp page, etc.).
This example file returns the string, Simple UI, if the user is in Site ID 1000; otherwise it returns, Advanced UI.
package oracle.apps.ibe.configurator;
import oracle.apps.jtf.base.resources.FrameworkException;
import com.sun.java.util.collections.HashMap;
import java.sql.*;
import oracle.apps.ibe.util.RequestCtx;
import java.math.BigDecimal;
public class CustomConfigHook extends ConfiguratorHook {
/**********************************************************************
* Abstract method which defines the parameters for retrieving a configurator usage parameter
*
* @param inventoryItemId:String, hashedParameters:HashMap (to pass in any other parameters an implementation may need)
* @return String (value to be passed in the Configurator's xml initialize message as the "config_effective_usage" parameter)
* @throws FrameworkException - if there is a framework layer error
* @throws SQLException - if there is a database error
* @throws ConfiguratorException - for throwing application specific errors
***********************************************************************/
public String getUsageParameter(String inventoryItemId, HashMap hashedParameters)
throws ConfiguratorException, FrameworkException, SQLException
{
if (RequestCtx.getMinisiteId() == new BigDecimal("1000"))
return "Simple UI";
else
return "Advanced UI";
}
}
Use the following procedure to set up Oracle iStore with Oracle Configurator.
Prerequisites
The file env.txt, located in the $COMMON_TOP/html directory, defines the directory that the variable $FND_TOP represents. The content of the file should be similar to the following example:
FND_TOP=/<root path>/<database or environment name>/fnd/11.5.0
You have set up and tested the Oracle Configurator servlet.
You have built Configurator UIs for the configurable items that you plan to sell.
Steps
In Oracle Inventory, make sure that every item that can be shown for a configured item, from the root model item to every option class and every leaf node, is set with the required product flags in the Master Item form. See the chapter, Implementing Products, for more information.
In Oracle Pricing, make sure that every item that can be shown for a configured item is added to the price list that will be used by the site and customer, even if it has a zero price. See the chapter, Implementing Pricing, for more information.
Log in to Oracle Forms with the System Administrator responsibility and set the profile option, BOM: Configurator URL of UI Manager, at (a) site, (b) iStore application, and (c) IBE_CUSTOMER responsibility levels to the Oracle Configurator Servlet URL: http://<host>:<port>/<servlet zone>/oracle.apps.cz.servlet.UiServlet.
The values for the host, port, and servlet zone are determined by your Application server configuration.
Set the profile option, ASO: Configurator URL, to the same value as BOM: Configurator URL of UI Manager.
Set the profile option, OM: Use Configurator, to Yes at the site level. This profile option is necessary for successful order placement.
Edit the database instance's Database Configuration (.dbc) file. The .dbc file enables connection to the database and is installed in the $FND_TOP/secure/ directory. The following edits are required in addition to any configuration settings that are required by other Oracle applications:
Only Oracle thin drivers are supported, so uncomment: APPS_JDBC_DRIVER_TYPE=THIN
Add the following line and replace the item between brackets with the appropriate value: BATCH_VALIDATE_USER=[Applications Username of the Guest]
Add the following line and replace the item between brackets with the appropriate value: BATCH_VALIDATE_PWD=[Applications Password of the Guest]
Uncomment the following line and replace "host_name" with the appropriate value: DB_HOST=host_name
Uncomment the following line and replace "port_number" with the appropriate value: DB_PORT=port_number
Uncomment the following line and replace "database_name" with the appropriate value: DB_NAME=database_name
The jserv.properties file must have the template URL defined as follows (these URLs must be able to be resolved when entered into a browser):
wrapper.bin.parameters=-Dcz.uiservlet.templateurl=http://<host>:<port>/OA_HTML/US/czFraNS.htm
wrapper.bin.parameters=-Dcz.uiservlet.templateurl.ie=http://<host>:<port>/OA_HTML/US/czFraIE.ht
In the Oracle iStore Site Administration UI, add the model item to some part of the catalog to be displayed.
In a load balanced environment, set the profile options, IBE: iStore Non Secure URL and IBE: iStore Secure URL to the load balancer URL (the www.oracle.com one).
See the appendix, Profile Options, for more information about the profile options.
Use the following procedure to test the Oracle Configurator setup.
Prerequisites
You have enabled cookies for both the browser and the middle tier. Oracle Configurator requires cookies.
Steps
Test that the Oracle Configurator middle tier servlet is running and getting the Oracle Configurator version, by entering the following URL in the browser: http://<host>:<port>/<servlet zone>/oracle.apps.cz.servlet.UiServlet? test=version.
The browser should return a message similar to the following statement: Using configuration software build: 11.5.1.14.27 Expecting schema: 14c.
Create the Configurator Standalone Test Page by writing the following lines into an HTML file with an .htm file name extension.
<!--========================================================================
| Copyright (c)2000 Oracle, Redwood Shores, CA
| All rights reserved.
+==========================================================================
|
| FILE
| Configurator Standalone Test Page
|
| DESCRIPTION
| This page posts an initialize message to the Configurator Servlet
| in order to provide an test of the middle tier, isolated from the
| rest of iStore.
|
| To use this page, read the comments below and replace the values in []
| with values specific to your implementation. Remove the []'s too.
| Remember to edit the form action near the bottom of the page.
| Then open the page in a browser and click the Launch DHTML button.
|
+=======================================================================-->
<HTML>
<HEAD>
<TITLE>Configurator Standalone Test Page</TITLE>
<SCRIPT LANGUAGE=javascript>
<!--
//globals
var ns4 = (document.layers)? true : false;
var ie4 = (document.all)? true : false;
function submitXML1 () {
var xmlValue = '';
xmlValue += '<initialize>';
//Replace the file name with the implemented dbc filename:
xmlValue += '<param name="database_id">[dbcfilename.dbc]</param>';
//Replace the value with the inventory info of the configurable model item:
xmlValue += '<param name="model_id">[1234]</param> ';
xmlValue += '<param name="model_uom">[Ea]</param> ';
xmlValue += '<param name="model_quantity">1</param> ';
//Try to use an icx session ticket retrieved from a logged init message
xmlValue += '<param name="icx_session_ticket">CB3E55CF36C0AECD
</param> ';
//This responsibility ID is currently irrelevant
xmlValue += '<param name="responsibility_id">22372</param> ';
//Enter the appropriate application ID (usually, it will be 671 for iStore)
xmlValue += '<param name="calling_application_id">[671]</param> ';
//Enter the organization ID for the configurable item:
xmlValue += '<param name="context_org_id">[123]</param> ';
//Use any date earlier than the current sysdate
xmlValue += '<param name="config_creation_date">[06-1-2000]
</param> ';
//Do not change the UI type for this test:
xmlValue += '<param name="ui_type">DHTML</param>';
//If the jserv properties are not correctly defined, the template URL can be
//defined here:
// xmlValue += '<param name="template_url">
// http://[machine]:[port]/OA_HTML/US/czIFrame.htm</param>';
//Alternate way of connecting to the database if the dbc file is not working
//(replaces database_id)
// xmlValue += '<param name="alt_database_name">
// jdbc:oracle:thin:@[machine]:[port]:[sid]</param>';
// xmlValue += '<param name="user">[login]</param>';
// xmlValue += '<param name="pwd">[password]</param>';
// xmlValue += '<param name="gwyuid">[login]/[password]</param>';
//Alternate way of specifying which DHTML UI to launch (replaces model_id
//and context_ord_id)
// xmlValue += '<param name="ui_def_id">[1234]</param>';
xmlValue += '</initialize>';
submitXML (xmlValue);
}
function submitXML (xml) {
if (ns4) {
document.form1.XMLmsg.value = xml;
document.form1.submit ();
} else if (ie4) {
form1.XMLmsg.value = xml;
form1.submit();
}
}
//-->
</SCRIPT>
</HEAD>
<BODY>
<FORM action="http://[machine]:[port]/servlets/oracle.apps.cz.servlet.UiServlet" method=POST
id=form1 name=form1>
<input type="hidden" name="XMLmsg" value=''>
</FORM>
<FORM action="" method=POST id=form2 name=form2>
<INPUT type="button" value="Launch DHTML" id=button1 name=button1 onclick="javascript:submitXML1();">
</FORM>
</BODY>
</HTML>
Edit the fields in the Configurator Standalone Test Page as explained in the comment lines.
Open the Configurator Standalone Test Page in a browser.
In the Configurator Standalone Test Page, select Launch DHTML.
The UI should appear.
This section lists checkpoints and fixes that you can use to resolve common Oracle Configurator integration errors. You can also use the Oracle Configurator initialize and terminate messages in the Oracle iStore Java log file as diagnostic tools.
This section lists checkpoints and fixes for common Oracle Configurator integration errors.
This error happens when the item is not published to the specialty site correctly.
Check that you have added the item to a published site section.
In Oracle Inventory, confirm that the item's Web Status is Published.
This error can happen for a variety of reasons. Use the following checkpoints and fixes to resolve the error:
Make sure the model was populated for the Master Inventory Organization. Using the Bills of Material responsibility, run the Populate Configuration Models concurrent program for the model and choose the value of the profile option IBE: Item Validation Organization for the Organization parameter.
Check that all of the model's option classes and components are on the price list that is defined for the user, and that they have prices.
In Oracle Inventory, check that the item has the properties Orderable on the Web and Web Status = Published.
Check that a Configurator UI exists for the model, using the following SQL query:
select cz_cf_api.ui_for_item
(<item_id>,<org_id>,sysdate,'DHTML',-1,1234,<appid - iStore is 671>)
from dual;
For example, see the following SQL statement:
select cz_cf_api.ui_for_item
(137,204,sysdate,'DHTML',-1,1234,671)
from dual;
If the SQL query returns a non-null value, the Configurator UI exists.
If the query returns a null value, the cause is one of the following cases:
No Configurator UI exists for the model. You must use Oracle Configurator Developer to build a Configurator UI.
A Configurator UI exists for the model, but it is not published for the user's application (usually Oracle iStore). In Oracle Configurator Developer, check that the model is in Complete status and includes Oracle iStore (IBE) as an application, then publish the Configurator UI. If the user's application ID is something other than 671 for Oracle iStore, the model's Configurator UI must be published for that application too. You can check the user's application ID in the cookie and in the initialize message from the Oracle iStore Java log file. Once the Configurator UI is published, you must restart the Application server and clear the cache to make the Configurator UI available.
When the Configure button appears for a configurable item after completing these fixes or any other fixes, you should first try to add a standard item to the shopping cart. If you cannot add the standard item, then the issue is with the shopping cart and you will not be able to add a configurable item.
This error can happen for a variety of reasons. Use the following checkpoints and fixes to resolve the error:
Make sure the value of the profile option BOM: Configurator URL of UI Manager is valid. Remember to check the machine name, domain name, port number, and servlet zone.
Test that Oracle Configurator itself has been installed correctly and that the servlet is running, as described in the section, "Testing the Oracle Configurator Setup".
Check that the Oracle Configurator HTML pages exist by navigating to:
http://<host>:<port>/OA_HTML/US/czIFrame.htm
Your browser should display a row of four buttons, labeled Summary, Availability, Done, and Cancel.
Verify that the database instance's .dbc file is in the $FND_TOP/secure directory.
Check that the correct $FND_TOP directory is specified in the $COMMON_TOP/html/env.txt file.
Check that cookies are turned on for both the browser and the middle tier.
Check the Oracle iStore Java log file's initialize and terminate messages for Oracle Configurator. Review the log messages to find possible errors, such as references to other environments and missing or incorrect values.
Check that Oracle Configurator can run independently of Oracle iStore by using the Configurator Standalone Test Page described in the section, "Testing the Oracle Configurator Setup", in this chapter. If you have the initialize message from the Oracle iStore Java log file, edit the Configurator Standalone Test Page to include the message's values. When you select Launch DHTML in the page, the UI should launch and run, and you should be able to select Done and see summary information. If the UI does not launch or you cannot see summary information, there is a middle tier setup issue.
This error occurs when profile options have not been set up correctly.
Verify that all required profile options have been set up.
This error can occur for a variety of reasons. Check the Oracle Configurator UI log files for the errors listed below, and use the fix described for the error. The Oracle Configurator UI log files are named cz_exc__.log. They are located in the $OAH_TOP/util/apache/1.3.9/Apache/logs/ directory or the $APACHE_TOP/Jserv/logs directory.
Database Connection Error—The .dbc file has not been set up correctly. Set up the .dbc file using the guidelines in the section, "Setting up Oracle Configurator", in this chapter.
Socket Connection Error—The Application server is not running. Restart the Application server.
Data/End of Communication Error—The Application server is not running. Restart the Application server.
Unsatisfied Link Error—The LD_LIBRARY_PATH and shared library linking are not correct. Correct the LD_LIBRARY_PATH and shared library linking.
OCI8/Thick Driver Error—The thin driver is not specified in the .dbc file. Edit the .dbc file to specify the thin driver.
Other Errors—The profile option that identifies the Configurator URL has an invalid value. Enter the correct URL as the value of the profile options BOM: Configurator URL of UI Manager and ASO: Configurator URL.
This error can happen for a variety of reasons. Use the following checkpoint to diagnose the error:
Check the terminate message in the Oracle iStore Java log file to see if Oracle Configurator returned an error. If so, there is an issue with the Oracle Configurator setup.
This error happens when the items are not set up correctly in Oracle Inventory.
In Oracle Inventory, check that the items have the properties Orderable on the Web and Web Status = Published.
This error can happen for a variety of reasons. Use the following checkpoints and fixes to resolve the error:
Verify that carts holding only standard items can be placed as orders. If not, then the issue is not necessarily related to Oracle Configurator.
In Oracle Order Management, check that for the Standard transaction type, a line flow has been defined for the item's User Item Type. For example, if the User Item Type is ATO Model, then verify that a line flow for the Item Type ATO Model has been defined for the Standard transaction type.
In a load balanced environment, be sure to set the profile options, IBE: iStore Non Secure URL and IBE: iStore Secure URL to the load balancer URL (the www.oracle.com one).