This chapter describes the format and parameters of the termination message for the runtime Oracle Configurator Servlet.
This chapter covers the following topics:
This chapter describes the format and parameters of the termination message for the runtime Oracle Configurator, including information on:
Note: If your host application is part of Oracle Applications, then the termination message is already defined. You only need to implement a termination message for custom host applications.
This section provides an overview of the termination message.
This document describes the role of the termination message primarily in relation to the initialization message, in Session Initialization. See the following sections for details:
Session termination takes place when the Oracle Configurator window is closed by one of the conditions listed in Termination conditions table.
| Condition | Example | Explanation |
|---|---|---|
| Submission | Your user clicks the Finish button. | See Submission |
| Cancellation | Your user clicks the Cancel button. | See Cancellation |
| Error | A connection cannot be made to the database. | See Error |
When the Oracle Configurator window is closed, terminating your user’s configuration session, the OC Servlet returns the results to your host application in the form of a termination message, written in XML. You need to understand the structure of the termination message to be able to extract the necessary data from it in your return URL servlet. The structure of this message is described in XML Message Structure.
All outputs in the XML termination message are written as XML elements and subelements of the <terminate> document element, in the general form:
<terminate>
<element_name>element_value</element_name>
<element_name>
<subelement_name>subelement_value</subelement_name>
</element_name>
</terminate>
The top-level structure of the <terminate> element is illustrated by these excerpts from its DTD:
... <!ELEMENT terminate (config_header_id?, config_rev_nbr?, valid_configuration?, complete_configuration?, exit, config_outputs?, config_messages?)> ... <!ELEMENT config_outputs (output_option*)> ... <!ELEMENT config_messages (message*)> ...
Structure of Termination Message shows the basic structure of a sample XML termination message. Typographical emphasis and comments have been added to point out the structure; such comments do not appear in actual termination messages.
Structure of Termination Message
<terminate>
<!-- configuration status elements -->
<config_header_id>1780</config_header_id>
<config_rev_nbr>2</config_rev_nbr>
<valid_configuration>true</valid_configuration>
<complete_configuration>true</complete_configuration>
<exit>save</exit>
<config_outputs>
<option>
<component_code>143-1490</component_code>
<quantity>1</quantity>
<list_price>0.00</list_price>
<!-- more elements go here -->
</option>
<!-- more options go here -->
</config_outputs>
<config_messages>
<message>
<message_type>error</message_type>
<message_text>Config header does not exist in database.</message_text>
</message>
<!-- more messages go here -->
</config_messages>
</terminate>
Submission occurs after your user closes the Oracle Configurator window by clicking the Finish button.
The meaning of the Finish button is defined by the context of your host application. For instance, in a web store, it might mean adding the configured product to your user’s "shopping cart", or submitting the configured order to your order entry system.
When the Finish button is clicked, the OC Servlet determines whether a return URL has been specified. If so, the servlet identified by that URL is called, and the results it generates are passed to your host application for further processing. This is the most important job of the return URL servlet; it captures the configuration selections of your user so that your host application can make use of them. For more details, see The Return URL.
After the Oracle Configurator window is closed, your host application must repaint the frame used by the Oracle Configurator window.
After submission, the termination message provides the host application with data describing:
Note: If you are providing guided selling in Oracle Applications Order Management, then your host application should obtain the termination message by using the initialization parameter terminate_id. See the description of that parameter for details.
If a custom host application wraps the runtime Oracle Configurator in its own JavaServer Page (as described in Incorporation of Oracle Configurator in the Host Application’s UI), then Oracle Configurator posts the termination message to it by HTTP connections, using the return URL (see The Return URL). An example of such a host application is Oracle iStore (IBE).
If an Oracle Applications Framework host application incorporates the runtime Oracle Configurator in a region of its own OA Framework page (as described in Incorporation of Oracle Configurator in the Host Application’s UI), then Oracle Configurator leaves the termination message in the OAPageContext, identified by the transient session key czTerminateMessage, then redirects to the same page. An example of such a host application is Oracle Contracts Core (OKC). Note that the termination message may contain error information (see Error) as well as normal termination output.
The host application can retrieve the termination message from the OAPageContext, using the following method, where pageContext is an instance of oracle.apps.fnd.framework.webui.OAPageContext:
(String) pageContext.getTransientSessionValue("czTerminateMessage");
The current configuration status is described by the subelements of <terminate> listed in this section. These subelements are:
This section describes the configuration status subelements of the <terminate> element.
The main identifier of an existing configuration. See the description for config_header_id. This value is displayed in the Oracle Configurator window with the default label "Configuration Header ID".
The revision number of an existing configuration. See the description for config_rev_nbr. This value is displayed in the Oracle Configurator window with the default label "Configuration Revision".
The value is true if all mandatory option classes (required features) are satisfied. This value is displayed in the Oracle Configurator window with the default label "Configuration Complete".
The possible values written for the exit termination element are shown in the following table:
| Value | Meaning |
|---|---|
| save | If the configuration was saved. |
| cancel | If the configuration was cancelled. |
| error | If an error was detected while executing in the UI Server. |
| processed | If a batch validation message was processed but not saved. |
This value is displayed in the Oracle Configurator window with the default label "Exit Status".
Prices are calculated when the user clicks the Summary button. This element tells the host application whether this calculation has happened in synchronization with the configuration. The possible values written for the prices_calculated_flag termination element and their meanings are shown in the following table:
| Value | Meaning |
|---|---|
| true | The configuration has not been changed since the end user clicked the Summary button. That is, the calculated prices are still in synchronization with the configuration. |
| false | Prices were not calculated after the configuration had been changed. This could happen if the end user had never clicked the Summary button before clicking Finish, or if the user changed the configuration and did not click the Summary button before clicking Finish. In this case, the host application should reprice each configuration line, to ensure that the proper prices are applied to the configuration. |
This element is added to the termination message only if:
The validation phase of batch validation was skipped
See Skipping Batch Validation for background.
The following table lists the values allowed for the standard_validation element.
| Value | Meaning |
|---|---|
| true | The standard validation phase of batch validation was executed. |
| false | The standard validation phase of batch validation was skipped. |
Contains the total discounted selling price for all the selected items in the configuration. The selling price and discounts are determined by the callback pricing procedure that you have specified for the configuration session. See Pricing and ATP in Oracle Configurator for details.
The value is true if no error messages are reported for the configuration. This value is displayed in the Oracle Configurator window with the default label "Configuration Valid".
The list of options selected by your user during the configuration session is contained in the <config_outputs> subelement of <terminate>. Each option is enclosed in <option> tags and contains the elements described in this section. These subelements are:
Configuration Outputs in the Termination Message shows an example of configuration outputs in the termination message, with comments added.
Configuration Outputs in the Termination Message
<terminate>
<!-- configuration status goes here -->
<config_outputs>
<option>
<selection_line_id>1846</selection_line_id>
<parent_line_id>1847</parent_line_id>
<component_code>143-1490</component_code>
<quantity>1</quantity>
<list_price>0.00</list_price>
<inventory_item_id>1490</inventory_item_id>
<organization_id>204</organization_id>
<uom>Ea</uom>
<discounted_price>0.00</discounted_price>
<atp_date></atp_date>
</option>
<!-- more options go here -->
</config_outputs>
<!-- configuration messages go here -->
</terminate>
This section describes the subelements for the <config_outputs> subelement of the <terminate> element.
Contains the ATP date. This is calculated by using the ATP procedure specified in the initialization message. See ATP Parameters, and Pricing and ATP in Oracle Configurator .
Provided if ATP is enabled. Contains the ATP date for the entire model.
Indicates the type of the configured BOM node, using the values shown in Values for the Termination Message Element <bom_item_type>.
The following table lists the values for the termination message element <bom_item_type>.
| Value | Name | Meaning |
|---|---|---|
| 1 | BOM_MODEL | BOM Model |
| 2 | BOM_OPTION_CLASS | BOM Option Class |
| 4 | BOM_STD_ITEM | BOM Standard Item |
Contains the quantity of the BOM Model being configured, as of the time that the configuration is saved.
Contains a value extracted from BOM_EXPLOSIONS.COMPONENT_CODE.
Contains the discounted price for the selected option. This is calculated by using the pricing procedure specified in the initialization message. See Pricing Parameters, and Pricing and ATP in Oracle Configurator .
Contains the ID for the item, extracted from MTL_SYSTEM_ITEMS.INVENTORY_ITEM_ID.
Contains the list price for the selected option. This is calculated by using the pricing procedure specified in the initialization message. See Pricing Parameters, and Pricing and ATP in Oracle Configurator.
Contains the organization ID for the item, extracted from MTL_SYSTEM_ITEMS.ORGANIZATION_ID.
Contains the value from CZ_CONFIG_ITEMS.CONFIG_ITEM_ID for the parent node of the configured node. If the parent is the root node, then the value is 0 (zero).
Contains the selected quantity for the option.
Contains the ID of the configuration line. It is the same as CZ_CONFIG_ITEMS.CONFIG_ITEM_ID in the CZ schema.
Contains the unit of measure.
The messages generated by the OC Servlet in response to selections made by your user during the configuration session are contained in the <config_messages> subelement of <terminate>. Each message is enclosed in <message> tags and contains the elements described in this section. These subelements are:
See Error for details on how to handle validation failures.
Configuration Messages in the Termination Message shows an example of a configuration message in the termination message, with typographical emphasis and comments added.
Configuration Messages in the Termination Message
<terminate>
<!-- configuration status goes here -->
<!-- configuration outputs go here -->
<config_messages>
<message>
<message_type>error</message_type>
<message_text>Config header does not exist in database.</message_text>
</message>
<!-- more messages go here -->
</config_messages>
</terminate>
This section describes the subelements for the <config_messages> subelement of the <terminate> element.
If present, one of these elements contains the identifier of the option to which this message is related. May be absent, if the message was not generated by a node.
Contains the name of the option to which this message is related.
Contains the text of the message.
Contains the severity level of the message. Possible values include the following:
suggestion
warning
overridable error
error
autoselection
autoexclusion
not satisfied
Cancellation occurs after your user closes the Oracle Configurator window by clicking the Cancel button. Control is returned to the host application, and no configuration information is returned. Validation failure information is not returned in the termination message for a cancellation. The termination message contains only the <exit> subelement, with a value of cancel:
Cancellation in the Termination Message
<terminate> <exit>cancel</exit> </terminate>
Error occurs after some condition prevents initialization of the Oracle Configurator window, or submission of the user’s selections. Such conditions might include:
Incorrect database connection or user login parameters (see Login Parameters)
Lack of any configuration parameters (see Model Identification Parameters)
Incorrect type for a parameter
A fatal exception in the Configurator Messaging service
If there were validation failures during your user’s configuration session, each failure on the list of the validation failure objects is returned as a <message> element describing the failure. Information about the failure is returned to the OC Servlet as an object of type oracle.apps.cz.cio.ValidationFailure, which you can access through the Oracle Configuration Interface Object (CIO).See the Oracle Configurator Extensions and Interface Object Developer’s Guide for details.
Control is returned to the host application, and no configuration information is returned. As shown in Error Information in the Termination Message, any validation failures are returned as messages in the <config_messages> element and the termination message contains the <exit> subelement, with a value of error.
Error Information in the Termination Message
<terminate>
<valid_configuration>false</valid_configuration>
<complete_configuration>false</complete_configuration>
<exit>error</exit>
<config_messages>
<message>
<message_type>error</message_type>
<message_text>Problem processing normal request: Could not post XML message to result URL:Connection refused</message_text>
</message>
</config_messages>
</terminate>
The program specified by the return_url initialization parameter determines how your host application uses the configuration information produced by your user’s selections in the Oracle Configurator window. For demonstration purposes, the return URL program shown in this document is a Java servlet, but you can use another type of program that performs the same role.
If you have specified the return URL using a parameter in your initialization message for the Oracle Configurator window, then the return URL servlet is called upon termination of a configuration session. For details about this parameter, see Return URL Parameter.
The termination message is passed to the return URL as the value of the XMLmsg argument. The initialization message that was passed to the configurator is also passed to the return URL, as the value of the INITmsg parameter.
The return URL must perform all middle-tier and database processing of the configuration and then return HTML that closes the Oracle Configurator window and continues with the program flow for the host application.
You specify the location of your return URL servlet in the XML initialization message, as the value of the parameter return_url. For an example, see HTML for Invoking the Runtime Oracle Configurator with Return URL.
See also:
The first step in implementing a return URL is to register an alias name for the return URL servlet. For details, see the Oracle Configurator Installation Guide.
An example of a return URL servlet is shown in Example Return URL Servlet (Checkout.java). You can modify this servlet code for your host application’s requirements.
To use some of the configuration information returned in the termination message (for example, the outputs described in Configuration Outputs), you can write a Java method that obtains the value of an element in the termination message by using the getTagValue() method defined in the Checkout servlet.
The following code fragment obtains the value of the <valid_configuration> output:
Obtaining Values from Termination Message
String getValidConfig(XMLDocument doc) {
// get element from termination msg
return getTagValue(doc, "valid_configuration", null);
}
For example, the following value of the <valid_configuration> output is provided by the following termination message:
<valid_configuration>true</valid_configuration>
When the Checkout servlet is called after submission, it replaces the Oracle Configurator window with an HTML page, like this:
HTML Output Produced from Termination Message
<html> <head><title>Checked Out with Valid Configuration</title></head> <body> Configuration Valid?: true </body> </html>