Extending R12 Charges

Functionality with User Hooks

An Oracle White Paper
Jan 2015
Version 1.1
 Extending R12 Charges Functionality with User Hooks

1. INTRODUCTION .................................................................................. 4
2. USER HOOKS FOR CHARGES CREATION ................................ 4
3. USER HOOKS FOR CHARGES UPDATE ..................................... 6
4. USER HOOK FOR PRICING ............................................................. 8
5. USER HOOKS FOR SUBMITTING ORDERS ............................... 9
6. CONCLUSION ......................................................................................11

Extending R12 Functionality with Charges User Hooks Page 2

Table of Figures
Figure 1: Create Charge Details User Hooks Parameter Definition.................................................. 5
Figure 2: Update Charge Details User Hooks Parameter Definition ................................................ 7
Figure 3: Call Pricing Item User Hook Parameter Definition ........................................................... 9
Figure 4: Submit Order User Hooks Parameter Definition ............................................................. 10

Extending R12 Functionality with Charges User Hooks Page 3

Extending R12 Charges Functionality with User Hooks

1. INTRODUCTION
Charges is a basic and core functionality used by many customers of Service, Depot Repair, and Field Service for
billing and for the entering of customer logistics orders to handle exchanges, replacements, and return for credit.
It is tightly integrated with TeleService, Field Service, and Depot Repair applications. In addition to the core
functionality provided out of the box, Charges also includes a set of user hooks that can be leveraged to
customize and extend customer functionality. These user hooks include:
Charges Creation Pre and Post Hooks
Charges Update Pre and Post Hooks
Charges Pricing User Hook
Submit Order User Hooks
This document presents each of these user hooks and describes its usage and purpose.

2. USER HOOKS FOR CHARGES CREATION

2.1 Description
Charges can be created through the TeleService UIs or through the Create_Charge_Details API. This API
supports usage of the Customer Pre and Post JTF user hooks. As the name suggests, the pre hook is executed
before the charge lines are created. The post hook is executed after the charge lines are created. The customer
user hook APIs are defined in packages CS_Charge_Details_CUHK and are invoked from within the
CS_Charge_Details_PVT.Create_Charge_Details API.
2.2 Usage Examples
Example 1: The create/update charges user hooks can be used to dynamically populate custom fields. Customers
may create custom fields on the UI or want to save additional information in the database tables. The user hooks
can execute logic to derive values for these fields based on customer rules or conditions, and populate these fields
accordingly.
Example 2: The create/update charges user hooks can be used to dynamically turn on or turn off the OM
interface option. Based on a customer rules and conditions, the create/update charges user hook can dynamically
check or uncheck the OM interface flag for the charge line so that only billable charges are submitted to order
management.

Extending R12 Functionality with Charges User Hooks Page 4

 2.3 API Signatures1
The user hook signatures are given below and are the same for the pre and post hooks.
PROCEDURE Create_Charge_Details_Pre (
p_api_version IN NUMBER,
p_init_msg_list IN VARCHAR2 DEFAULT FND_API.G_FALSE,
p_commit IN VARCHAR2 DEFAULT FND_API.G_FALSE,
p_validation_level IN NUMBER DEFAULT FND_API.G_VALID_LEVEL_FULL,
x_return_status OUT NOCOPY VARCHAR2,
x_msg_count OUT NOCOPY NUMBER,
x_object_version_number OUT NOCOPY NUMBER,
x_estimate_detail_id OUT NOCOPY NUMBER,
x_line_number OUT NOCOPY NUMBER,
x_msg_data OUT NOCOPY VARCHAR2,
p_resp_appl_id IN NUMBER DEFAULT NULL,
p_resp_id IN NUMBER DEFAULT NULL,
p_user_id IN NUMBER DEFAULT NULL,
p_login_id IN NUMBER DEFAULT NULL,
p_transaction_control IN VARCHAR2 DEFAULT FND_API.G_TRUE,
p_est_detail_rec IN CS_CHARGE_DETAILS_PUB.Charges_Rec_Type);

PROCEDURE Create_Charge_Details_Post (
p_api_version IN NUMBER,
p_init_msg_list IN VARCHAR2 DEFAULT FND_API.G_FALSE,
p_commit IN VARCHAR2 DEFAULT FND_API.G_FALSE,
p_validation_level IN NUMBER DEFAULT FND_API.G_VALID_LEVEL_FULL,
x_return_status OUT NOCOPY VARCHAR2,
x_msg_count OUT NOCOPY NUMBER,
x_object_version_number OUT NOCOPY NUMBER,
x_estimate_detail_id OUT NOCOPY NUMBER,
x_line_number OUT NOCOPY NUMBER,
x_msg_data OUT NOCOPY VARCHAR2,
p_resp_appl_id IN NUMBER DEFAULT NULL,
p_resp_id IN NUMBER DEFAULT NULL,
p_user_id IN NUMBER DEFAULT NULL,
p_login_in IN NUMBER DEFAULT NULL,
p_transaction_control IN VARCHAR2 DEFAULT FND_API.G_TRUE,
p_est_detail_recIN CS_CHARGE_DETAILS_PUB.Charges_Rec_Type);

Figure 1: Create Charge Details User Hooks Parameter Definition

Parameter Name Type Data Type Required Validation, Default, Comment

p_api_version IN NUMBER Parameter for the API version. If the API is called
with a value that does not match the version of the
API being called, the API returns an Unexpected
Error message.
p_init_msg_list IN VARCHAR2 FND_API.G_FALSE or FND_API.G_TRUE.
FND_API.G_TRUE causes the API to initialize
the message stack. If the value is
FND_API.G_FALSE, the calling program must
initialize the message stack using the API
FND_MSG_PUB.initialize.
Default FND_API.G_FALSE
p_commit IN VARCHAR2 Indicates if the API is to commit its results.
Default FND_API.G_FALSE

1 As of the publication date of this whitepaper, the official R12 Charges API whitepaper has not yet been released. Please
refer to that whitepaper for the exact API signatures and parameter names.

Extending R12 Functionality with Charges User Hooks Page 5

Parameter Name Type Data Type Required Validation, Default, Comment

p_validation_level IN NUMBER Parameter for controlling the validation level in the

API. Values are
FND_API.G_VALID_LEVEL_FULL and
FND_API.G_VALID_LEVEL_NONE.
Default FND_API. G_VALID_LEVEL_FULL
x_return_status OUT VARCHAR2 Return status of the API request.
x_msg_count OUT NUMBER Count of the messages returned by the API.
x_object_version_num OUT NUMBER Object version of the charge line created.
ber
x_estimate_detail_id OUT NUMBER Estimate detail identifier of the charge line created.
x_line_number OUT NUMBER Line number of the charge line created.
x_msg_data OUT VARCHAR2 A concatenated error/warning message string.
p_resp_appl_id IN NUMBER User Responsibility Application Identifier.
Default fnd_global.resp_appl_id
p_resp_id IN NUMBER User Responsibility Identifier
Default fnd_global.resp_id
p_user_id IN NUMBER User Identifier
Default fnd_global.user_id
p_login_id IN NUMBER Login Session Identifier
Default fnd_global.login_id
p_transaction_control IN VARCHAR2 Used by the API for transaction Control. This
parameter is set to 'F' (False) only if the API is
called from triggers, as triggers do not allow
Transaction Control in procedures.
p_est_detail_rec IN CHARGES_R PL/SQL record type that has all the attributes
EC_TYPE users can provide to create charge details.
Please see section 3.6.1 below for more details.

3. USER HOOKS FOR CHARGES UPDATE

3.1 Description
Charges can be updated through the TeleService UIs or through the Update_Charge_Details API. This API
supports usage of the Customer Pre and Post JTF user hooks. As the name suggests, the pre hook is executed
before the charge lines are updated. The post hook is executed after the charge lines are updated. The customer
user hook APIs are defined in packages CS_Charge_Details_CUHK and are invoked from within the
CS_Charge_Details_PVT.Update_Charge_Details API.
3.2 Usage Examples
Please refer to the examples given in section 2.

3.3 API Signatures

The user hook signatures are given below and are the same for the pre and post hooks.
PROCEDURE Update_Charge_Details_Pre (
p_api_version IN NUMBER,
p_init_msg_list IN VARCHAR2 := FND_API.G_FALSE,

Extending R12 Functionality with Charges User Hooks Page 6

 p_commit IN VARCHAR2 := FND_API.G_FALSE,
p_validation_level IN NUMBER := FND_API.G_VALID_LEVEL_FULL,
x_return_status OUT NOCOPY VARCHAR2,
x_msg_count OUT NOCOPY NUMBER,
x_object_version_number OUT NOCOPY NUMBER,
x_msg_data OUT NOCOPY VARCHAR2,
x_estimate_detail_id OUT NOCOPY NUMBER,
p_resp_appl_id IN NUMBER := FND_GLOBAL.RESP_APPL_ID,
p_resp_id IN NUMBER := FND_GLOBAL.RESP_ID,
p_user_id IN NUMBER := FND_GLOBAL.USER_ID,
p_login_id IN NUMBER := NULL,
p_transaction_control IN VARCHAR2 := FND_API.G_TRUE,
p_est_detail_rec IN OUT Charges_Rec_Type := G_MISS_CHRG_REC);

PROCEDURE Update_Charge_Details_Post (
p_api_version IN NUMBER,
p_init_msg_list IN VARCHAR2 := FND_API.G_FALSE,
p_commit IN VARCHAR2 := FND_API.G_FALSE,
p_validation_level IN NUMBER := FND_API.G_VALID_LEVEL_FULL,
x_return_status OUT NOCOPY VARCHAR2,
x_msg_count OUT NOCOPY NUMBER,
x_object_version_number OUT NOCOPY NUMBER,
x_msg_data OUT NOCOPY VARCHAR2,
x_estimate_detail_id OUT NOCOPY NUMBER,
p_resp_appl_id IN NUMBER := FND_GLOBAL.RESP_APPL_ID,
p_resp_id IN NUMBER := FND_GLOBAL.RESP_ID,
p_user_id IN NUMBER := FND_GLOBAL.USER_ID,
p_login_id IN NUMBER := NULL,
p_transaction_control IN VARCHAR2 := FND_API.G_TRUE,
p_est_detail_rec IN OUT Charges_Rec_Type := G_MISS_CHRG_REC);

Figure 2: Update Charge Details User Hooks Parameter Definition

Parameter Name Type Data Type Required Validation, Default, Comment

p_api_version IN NUMBER Parameter for the API version. If the API is called
with a value that does not match the version of the
API being called, the API returns an Unexpected
Error message.
p_init_msg_list IN VARCHAR2 FND_API.G_FALSE or FND_API.G_TRUE.
FND_API.G_TRUE causes the API to initialize
the message stack. If the value is
FND_API.G_FALSE, the calling program must
initialize the message stack using the API
FND_MSG_PUB.initialize.
Default FND_API.G_FALSE
p_commit IN VARCHAR2 Indicates if the API is to commit its results.
Default FND_API.G_FALSE
p_validation_level IN NUMBER Parameter for controlling the validation level in the
API. Values are
FND_API.G_VALID_LEVEL_FULL and
FND_API.G_VALID_LEVEL_NONE.
Default FND_API. G_VALID_LEVEL_FULL
x_return_status OUT VARCHAR2 Return status of the API request.
x_msg_count OUT NUMBER Count of the messages returned by the API.
x_object_version_num OUT NUMBER Object version of the charge line created.
ber
x_msg_data OUT VARCHAR2 A concatenated error/warning message string.

Extending R12 Functionality with Charges User Hooks Page 7

Parameter Name Type Data Type Required Validation, Default, Comment

x_estimate_detail_id OUT NUMBER Estimate detail identifier of the charge line created.
p_resp_appl_id IN NUMBER User Responsibility Application Identifier.
Default fnd_global.resp_appl_id
p_resp_id IN NUMBER User Responsibility Identifier
Default fnd_global.resp_id
p_user_id IN NUMBER User Identifier
Default fnd_global.user_id
p_login_id IN NUMBER Login Session Identifier
Default fnd_global.login_id
p_transaction_control IN VARCHAR2 Used by the API for transaction Control. This
parameter is set to 'F' (False) only if the API is
called from triggers, as triggers do not allow
Transaction Control in procedures.
p_est_detail_rec IN CHARGES_R PL/SQL record type that has all the attributes
EC_TYPE users can provide to create charge details.
Please see section 3.6.1 below for more details.

4. USER HOOK FOR PRICING

4.1 Description
The Call Pricing Item API is invoked during the creation of a charge line as well during the update of a charge
line. If a charge line is being created, this API is called to return the price of the item selected, given the quantity,
contract and pricelist for the charge line. After the charge line is created, if the user attempts to change the item,
quantity, contract, or the pricelist values, then this API is again invoked to recalculate the price.
The Call Pricing Item API supports usage of the Customer Pre JTF user hook. If the user hook is called and a
list price is returned, then no additional calls are made to the Pricing API to fetch the item price. This is different
from other pre hooks that simply precedes the normal procedure invocation.

4.2 Usage
Example 1: Customers can leverage this user hook to integrate with Advanced Pricing to retrieve the item price
based on modifiers, qualifiers, and other advanced pricing features. The logic in the user hook will need to inquire
Advanced Pricing tables either through SQL or Advanced Pricing APIs to calculate the appropriate item price.
Customers are strongly advised to work with the Advanced Pricing team to develop the logic.

Example 2: Customers can leverage this user hook to perform currency conversion of the item price. The
current Charges functionality does not allow agents to select a currency for the charge line that is different from
the base currency of the pricelist. Customers can customize the UI to allow users to select a different currency
and trigger a call to the Pricing API. The logic in the Pricing user hook can then be used to do the currency
conversion to return the correct item price based on the newly selected currency.

Extending R12 Functionality with Charges User Hooks Page 8

 4.3 API Signature
The customer user hook API is defined in packages CS_Charge_Details_CUHK and is invoked from within the
CS_Item_Pricing_Pkg.Call_Pricing_Item API.
The user hook signature is given below.
PROCEDURE Call_Pricing_Item_Pre (
p_inventory_item_id IN NUMBER,
p_price_list_id IN NUMBER,
p_uom_code IN VARCHAR2,
p_currency_code IN VARCHAR2,
p_quantity IN NUMBER,
p_org_id IN NUMBER,
x_list_price OUT NOCOPY NUMBER,
p_in_price_attr_tbl IN ASO_QUOTE_PUB.Price_Attributes_Tbl_Type,
x_return_status OUT NOCOPY VARCHAR2,
x_msg_count OUT NOCOPY NUMBER,
x_msg_data OUT NOCOPY VARCHAR2 );

Figure 3: Call Pricing Item User Hook Parameter Definition

Table 1: Parameter Type Data Type Required Validation, Default, Comment

Name
p_inventory_item_id IN NUMBER Inventory item in the charge line.

p_pricelist_id IN NUMBER Unique ID of the Price List on the charge line.

p_uom_code IN VARCHAR2 Optional Unit Of Measure code of the item.
p_currency_code IN VARCHAR2 Currency used for item price.
p_quantity IN NUMBER Quantity of the item.
p_org_id IN NUMBER The Operating Unit of the Charge line.
x_list_price OUT NUMBER Return list price of the item.
p_in_price_attr_tbl IN ASO_QUOTE Table or Price Attributes Type
_PUB.Price_Att
ributes_Tbl_Ty
pe
x_return_status OUT VARCHAR2 Return status of the API request.
x_msg_count OUT NUMBER Count of the messages returned by the API.
x_msg_data OUT VARCHAR2 A concatenated error/warning message string.

5. USER HOOKS FOR SUBMITTING ORDERS

5.1 Description
The Submit Order API is called to submit the actual charge lines to Order Management for the creation or
update of an order. The Submit Order API supports usage of the Customer JTF user hooks. If activated, the
user hook is invoked before an order is created or updated. The customer user hook APIs are defined in package
CS_Charge_Details_CUHK and are invoked from within the CS_Charge_Create_Order_PVT.Submit_Order
API.
5.2 Usage

Extending R12 Functionality with Charges User Hooks Page 9

 Example 1: These user hooks can be used by customers to override the order line type associated with the
service activity code. Order line types are used in Order Management to drive accounting, workflows or
approvals. Currently, the current service activity code setup UI does not support the mapping of one service
activity code to multiple order line types. However, these user hooks can enable customers to plug in logic right
before creating or updating the order to determine which order line type should be used, based on the
information given on the charge line. Without this, users would have to setup a different service activity code for
every different order line type.
Example 2: Customers can also leverage this user hook to pass information into the order header flexfields and
line flexfields. The current logic does not pass any information to the order management header or lines
flexfields, but users can include this logic in the user hooks.

5.3 API Signatures

The user hook signatures are given below, one is invoked before the order is created and one is invoked before
the order is updated.

PROCEDURE Create_Order (
p_api_version_number IN NUMBER,
l_header_rec IN OUT NOCOPY ASO_QUOTE_PUB.Qte_Header_Rec_Type ,
l_hd_shipment_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Shipment_Tbl_Type,
l_line_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Qte_Line_Tbl_Type,
l_line_dtl_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Qte_Line_Dtl_Tbl_Type,
l_ln_shipment_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Shipment_Tbl_Type,
l_hd_payment_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Payment_Tbl_Type,
l_line_price_adj_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Price_Adj_Tbl_Type,
l_lot_serial_tbl IN OUT NOCOPY ASO_ORDER_INT.Lot_Serial_Tbl_Type,
l_control_rec IN OUT NOCOPY ASO_ORDER_INT.control_rec_type,
x_return_status OUT NOCOPY VARCHAR2,
x_msg_count OUT NOCOPY NUMBER,
x_msg_data OUT NOCOPY VARCHAR2);

PROCEDURE Update_Order (
p_api_version_number IN NUMBER,
l_header_recIN OUT NOCOPY ASO_QUOTE_PUB.Qte_Header_Rec_Type,
l_line_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Qte_Line_Tbl_Type,
l_line_dtl_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Qte_Line_Dtl_Tbl_Type,
l_ln_shipment_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Shipment_Tbl_Type,
l_hd_payment_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Payment_Tbl_Type,
l_line_price_adj_tbl IN OUT NOCOPY ASO_QUOTE_PUB.Price_Adj_Tbl_Type,
l_lot_serial_tbl IN OUT NOCOPY ASO_ORDER_INT.Lot_Serial_Tbl_Type,
l_control_rec IN OUT NOCOPY ASO_ORDER_INT.Control_Rec_Type,
x_order_header_rec OUT NOCOPY ASO_ORDER_INT.Order_Header_rec_type,
x_order_line_tbl OUT NOCOPY ASO_ORDER_INT.Order_Line_Tbl_Type,
x_return_status OUT NOCOPY VARCHAR2,
x_msg_count OUT NOCOPY NUMBER,
x_msg_data OUT NOCOPY VARCHAR2);

Figure 4: Submit Order User Hooks Parameter Definition

Parameter Name Type Data Type Required Validation, Default, Comment

p_api_version_number IN NUMBER Parameter for the API version. If the API is

called with a value that does not match the

Extending R12 Functionality with Charges User Hooks Page 10

 Parameter Name Type Data Type Required Validation, Default, Comment

version of the API being called, the API

returns an Unexpected Error message.
l_header_rec IN/OUT ASO_QUOTE_ Quoting Header Record Type; Used to pass
PUB.Qte_Head data on the quote header.
er_Rec_Type
l_hd_shipment_tbl IN/OUT ASO_QUOTE_ Table of Shipment Type;
PUB.Shipment_
Tbl_Type
l_line_tbl IN/OUT ASO_QUOTE_ Table of Quote Line Type;
PUB.Qte_Line_
Tbl_Type
l_line_dtl_tbl IN/OUT ASO_QUOTE_ Table of Quote Line Detail Type;
PUB.Qte_Line_
Dtl_Tbl_Type
l_ln_shipment_tbl IN/OUT ASO_QUOTE_ Table of Shipment Type;
PUB.Shipment_
Tbl_Type
l_hd_payment_tbl IN/OUT ASO_QUOTE_ Table of Payment Type;
PUB.Payment_
Tbl_Type
l_line_price_adj_tbl IN/OUT ASO_QUOTE_ Table of Price Adjustment Type;
PUB.Price_Adj_
Tbl_Type
l_lot_serial_tbl IN/OUT ASO_QUOTE_ Table of Lot Serial Type;
PUB.Lot_Serial_
Tbl_Type
l_control_rec IN/OUT ASO_ORDER_ Table of Control Type;
INT.Control_Re
c_Type
x_order_header_rec OUT ASO_ORDER_ Table of Order Header Record Type;
INT.Order_Hea
der_Rec_Type
x_order_line_tbl OUT ASO_ORDER_ Table of Order Line Type;
INT.Order_Line
_Tbl_Type
x_return_status OUT VARCHAR2 Return status of the API request.
x_msg_count OUT NUMBER Count of the messages returned by the API.
x_msg_data OUT VARCHAR2 A concatenated error/warning message string.

6. CONCLUSION
User hooks are designed to provide flexibility to incorporate additional logic within the core applications. The
Charges user hooks presented in the document allow customers to customize the functionality in the charges module
without having to worry about future upgrades and patches. Because they occur in the API level, the user hook logic
applies whether charges are created on the UI level or through APIs invoked from its integrated applications.
2Leveraging these user hooks is an obvious choice for extending charges functionality.

2 Bug 15959759 has been filed to invoke the create/update charges user hook from the UI.

Extending R12 Functionality with Charges User Hooks Page 11

Extending R12 Functionality with Charges User Hooks Page 12
Extending R12 Charges Functionality with User Hooks
Oct 2010
Author: [OPTIONAL]
Contributing Authors: [OPTIONAL]

Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065
U.S.A.

Worldwide Inquiries:
Phone: +1.650.506.7000
Fax: +1.650.506.7200
oracle.com

Copyright 2010, Oracle. All rights reserved.

This document is provided for information purposes only and the
contents hereof are subject to change without notice.
This document is not warranted to be error-free, nor subject to any
other warranties or conditions, whether expressed orally or implied
in law, including implied warranties and conditions of merchantability
or fitness for a particular purpose. We specifically disclaim any
liability with respect to this document and no contractual obligations
are formed either directly or indirectly by this document. This document
may not be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without our prior written permission.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.