Oracle® Fusion
Applications Project Management Implementation Guide 11g Release 1 (11.1.3) Part Number E20384-03 |
![]() Contents |
![]() Previous |
![]() Next |
This chapter contains the following:
Billing Extension Components: How They Work Together
Planning Your Billing Extension Implementation: Explained
Receivables Transaction Type Extension
FAQs for Define Project Billing Extensions
Implement a billing extension to define a set of company-specific business rules that create automatic invoice and revenue events. To use the billing extension functionality, create a billing extension and assign it to a bill plan or revenue plan.
Order
If multiple billing extensions are assigned to a bill or revenue plan, enter a numeric value to determine when this extension is called. Oracle Fusion Project Billing calls billing extensions in ascending order.
Procedure
To implement a company specific rule for creating automatic invoice and revenue events, you must first write a PL/SQL procedure that calculates the event amount. Enter the name of the PL/SQL procedure on the billing extension page.
Transaction Independent
Transaction independent billing extensions are called once for each contract line or associated project, depending on the extension calculation level defined in the bill or revenue plan. They are usually defined to import transactions from external applications. If the billing extension is for invoices, the extension is called during the Generate Invoice process before the invoice preprocessor, which creates billing transactions. If the billing extension is for revenue, the extension is called during the Generate Revenue process before revenue transactions are processed.
Note
If you do not enable the transaction independent feature of a billing extension, it will be transaction dependent. Transaction dependent billing extensions are called only if billable expenditure items and events exist that need to be processed.
The call process determines whether to call the PL/SQL procedure that calculates the amount during invoice generation or revenue generation.
Note
If you require a procedure to create both automatic invoice and revenue events, you must create two separate billing extensions.
Select a location (time) within the invoice or revenue generation program where the billing extension is called. The predefined locations are:
Before billing transaction creation
Select this location if you want to call the billing extension before any recognizing revenue or calculating invoice amounts for the contract line or project and contract line combination.
An example of a requirement for which you may want to use this call location is if you want to place all unbilled, unpaid supplier invoice items on hold so they are not billed; and to release the billing hold on any unbilled, paid supplier invoice transactions that are on hold. You can then bill the paid supplier invoice items during standard invoice processing.
After invoice and revenue distribution lines are created
Select this option to call the billing extension after the revenue and invoice processing is complete.
Examples of requirements for which you may want to use this call location are if you want to notify a project manager when an invoice of a certain amount is created, or if you want to create a fixed fee event that is dependent on the total transaction amount billed on the invoice.
Before invoice deletion
Select this option if you want to call the billing extension before deleting invoice distribution lines. This call location is only valid for invoice billing extensions.
Specify whether an amount or percentage is required for entry when you assign the billing extension to a bill or revenue plan. When you define a bill or revenue plan that uses the billing extension, you must enter a specific amount or percentage that is used when calculating the automatic invoice or revenue event.
Specify an event type to determine the default event attributes to use for events created by the billing extension. You can override the attributes for default event type in your procedure.
Specify a default financial cost plan type to use for calculations that use budgeted amounts. If the value is not provided for a cost plan type, but is needed for the calculation, the process will error. You can override the attributes for default plan in your procedure.
You should carefully design billing extensions before implementing them in Oracle Fusion Projects. Careful planning of your billing extensions help to ensure that you are calculating and generating revenue and invoices according to your company-specific rules.
Carefully plan the definition of billing extensions before you begin writing them. Typically, the logic of your billing extensions are dependent on your company's implementation of Oracle Fusion Projects. Consider the following issues when designing your billing extensions:
Are you calculating a revenue amount or an invoice amount? Are the amounts generated during revenue generation or invoice generation?
How are the amounts calculated? What are the inputs to the calculation?
How are the inputs derived?
How are the amounts processed:
For reporting purposes?
For accounting purposes?
For invoicing?
How are the attributes of the automatic event set: event type, event organization, event description, completion date?
Under what conditions is this calculation used? What types of contracts? What types of billing terms?
How is the billing extension processed for adjustments? Adjustments are defined as revenue credits or invoice credit memos, based on other transactions.
Can this billing extension be called with other billing extensions assigned to the same bill plan or revenue plan? If so, what is the dependency and order of your billing extensions?
What is the exception handling if some input values cannot be found?
How is the logic affected if the inputs change over time?
Is there a limit on the amount calculated? If so, what is the logic?
Once you answer these questions, you should have the appropriate information to define a billing extension in Oracle Fusion Projects and to document the functional specifications for your technical resource to use in writing the PL/SQL procedure.
After you design your billing extensions, write the PL/SQL procedures that define the logic of the billing extensions.
After you write your procedures, store them in the database and test them to ensure that your billing extension logic works as expected.
Define your billing extensions that specify the PL/SQL procedure name and additional information for Oracle Fusion Projects to use when processing billing extensions.
You use the Create Billing Extensions page to define billing extensions.
Note
This step assumes that an event type has already been defined for the default event type.
Assign billing extensions to the appropriate invoice methods and revenue methods. Your contract users will select these invoice methods and revenue methods on bill plans and revenue plans. The assigned billing extensions are copied from the methods to the plans.
Use the Billing Extension to implement company-specific business rules to automatically create invoice or revenue events. Billing extensions automatically calculate summary invoice or revenue amounts during invoice or revenue generation.
To use the billing extension functionality, you must implement a billing extension and assign it to either an invoice method or a revenue method. You can assign a billing extension to more than one invoice or revenue method. When you specify the invoice or revenue method on a bill or revenue plan, the billing extensions assigned to that method are copied to the plan. Depending on the definition of the assigned billing extension, you might be required to specify a percentage or amount to use as input when calculating the event amount.
The extension is defined by the following items.
Extension Component |
Name |
---|---|
Body template |
pjb_bill_extn_sample_pkg.pkb |
Specification template |
pjb_bill_extn_sample_pkg.pkh |
Package |
pjb_bill_extn_sample_pkg |
Procedure |
SampleExtn |
Your extension procedure can call other procedures or views. These other procedures or views can be predefined or you can write your own.
Parameters
Information about parameters for this billing extension are in the table below.
Parameter Name |
Description |
---|---|
p_bill_plan_id |
Bill plan or revenue plan identifier from pjb_bill_plans_b or okc_k_lines_b. |
p_contract_id |
Contract identifier from okc_k_headers_all_b. |
p_contract_line_id |
Contract line identifier from okc_k_lines_b. |
p_linkage_id |
Project and contract linkage identifier from pjb_cntrct_proj_links. Pass the value when the calculation level code is PROJECT_CONTRACT_LINKAGE. |
p_linked_project_id |
Project identifier from pjb_cntrct_proj_links linked to the contract. Pass the value when the calculation level code is PROJECT_CONTRACT_LINKAGE. |
p_linked_task_id |
Task identifier from pjb_cntrct_proj_links linked to the contract. Pass the value when the calculation level code is PROJECT_CONTRACT_LINKAGE. |
p_calling_process |
Calling process for the billing extension. Valid values are:
|
p_calculation_level |
Calculation level code for the billing extension. Valid values are:
|
p_bill_frm_date |
Invoice or revenue from date. |
p_bill_to_date |
Invoice or revenue to date. |
p_amt |
Invoice amount or revenue amount. This is generally used when the extension calling place is AFTER_DRAFT. |
p_percent |
Percentage |
p_assignment_detail_id |
Assignment detail identifier pjb_assignment_details. |
p_extension_id |
Billing extension identifier obtained from table pjb_billing_extensions. |
p_assignment_id |
Assignment identifier |
p_event_type_id |
Event type identifier from pjb_event_types_b. |
p_default_event_type_description |
Event type description identifier from pjf_event_types_tl. |
p_cost_fin_plan_type |
Cost financial plan type identifier. This is generally used when the invoice or revenue method is Percent Spent. |
p_invoice_id |
Invoice identifier |
p_request_id |
Request identifier |
p_cont_curr_code |
Contract currency code |
p_ledger_curr_code |
Ledger currency code |
X_return_status |
Status of the procedure. Valid values are:
|
X_msg_count |
Message count. Valid values are greater than or equal to zero. |
X_msg_data |
Actual message when there is an exception. |
Implementing Your Company's Billing Extension
To implement your company-specific billing methods, you first design and write rules to calculate billing amounts using PL/SQL procedures. You then enter the billing extension definition in Oracle Fusion Projects to specify additional information (such as the procedure name to call) that is used by the revenue and invoice programs to process the extension.
You define billing extensions in the Create Billing Extensions page, and specify the following items:
The name of the procedure to call.
Whether the procedure is called during invoicing or revenue recognition.
The call location within the invoice or revenue program where the extension is called.
Whether an amount or percentage is required when the billing extension is assigned to a bill plan or revenue plan.
The budget type to use as input for calculations that use budgeted amounts.
The values entered in the Create Billing Extensions page can be used in your billing extension procedure by accessing the table pjb_billing_extensions. The values entered in the Billing Extensions tab of the Create Bill Plan or Create Revenue Plan page can also be used in your billing extension procedure by accessing the table pjb_assignment_details.
Processing
When you run the revenue or invoice processes, Oracle Fusion Projects looks for active billing extensions assigned to a bill plan or revenue plan. When a billing extension is found, the processes read the billing extension definition and call the appropriate procedure. If there are multiple active billing extensions assigned to a bill or revenue plan, Oracle Projects calls the extensions by the order entered on the Create Billing Extension page, and then by the order of the assignment to the bill or revenue plan.
Automatic Events
Your billing extension calculates revenue and invoice amounts and creates one or more automatic events. Oracle Fusion Projects processes these events as it does other manually entered events. You can store audit amounts and references for these events in the audit amount and reference columns of the Events table.
You can increase or decrease revenue and invoice amounts for automatic events. You can also place automatic events on invoice or revenue hold indefinitely, and remove the holds later.
Automatic events are either only applicable to invoicing or only applicable to revenue recognition, but not both.
The billing extension uses the public procedure MyPackageName.insert_event to automatically create events.
Internal Payables Invoice Attribute Override ExtensionThe Labor Billing Extension allows you to derive labor billing amounts for individual labor transactions.
You can use the labor billing extension to implement unique labor billing methods. Some examples of how you can use the labor billing extension are to:
Bill overtime premium hours at cost.
Bill based on volume of work performed.
The Labor Billing Extension is called during the invoice or revenue generation process to determine labor revenue and billing amounts.
The extension is defined by the following items:
Extension Component |
Name |
---|---|
Body template |
pjb_client_extn_billing.pkb |
Specification template |
pjb_client_extn_billing.pkh |
Package |
pjb_client_extn_billing |
Procedure |
Calc_Labor_Bill_Amount |
Important
Do not change the name of the extension procedures or parameters. Also, do not change the parameter types or parameter order in your procedure. After you write a procedure, compile it and store it in the database.
Parameters
Information about parameters for this billing extension are in the table below.
Parameter Name |
Description |
---|---|
p_transaction_type |
Varchar2 Valid values are:
|
p_contract_id |
Number |
p_expenditure_item_id |
Number |
x_amount |
Number No value is passed in to the x_amount parameter. Do not expect an amount in this parameter when you create calculations in the extension. The billing extension must assign a value to the x_amount parameter, or else the extension will be ignored by the calling program. |
x_bill_rate_flag |
Varchar2 Return one of the following values as the x_bill_rate_flag parameter value to specify if the amount that you have derived is based on a bill rate or a percent markup:
If you specify that your amount is based on a bill rate, Oracle Fusion Projects populates the bill rate of the expenditure item by dividing the bill amount by the number of hours. If you specify that your amount is a markup, Oracle Fusion Projects does not set the bill rate. |
x_bill_trans_currency_code |
Varchar2 |
x_bill_txn_bill_rate |
Number |
x_markup_percentage |
Number If you specify that your amount is based on markup, populate x_markup_percentage with the markup percentage amount, so that the expenditure item record will contain accurate data. |
x_rate_source_id |
Number |
x_return_status |
Varchar2 |
x_msg_count |
Number |
x_msg_data |
Varchar2 |
Oracle Fusion Projects uses the labor billing extension for rate-based invoice method classifications or rate-based and as-incurred revenue method classifications during the invoice or revenue generation process. During processing, if Oracle Fusion Projects encounters a transaction that has a derived bill amount from a labor billing extension, it skips the standard bill amount and rate calculation section of the revenue generation process for that transaction.
Design Issues
Consider the following design issues for labor billing extensions:
What are the conditions and circumstances in which you cannot use the standard, rate-based invoice and revenue method classifications supported by Oracle Fusion Projects?
How are the invoice and revenue amounts calculated in these cases?
How do you identify labor transactions that meet these conditions?
How do you store rates and other information that your calculations may require? How are the rates and other information maintained?
What are the exception conditions for your labor billing extension? What is the exception handling if you cannot find a rate that should exist?
The Nonlabor Billing Extension enables you to derive billing amounts for individual nonlabor transactions.
You can use the Nonlabor Billing Extension to implement unique nonlabor invoice methods or revenue methods. Some examples of how you can use the Nonlabor Billing Extension are for:
A tiered pricing method
External application rate derivation
The Nonlabor billing extension procedure Oracle provides can be called during either the invoice or revenue generation process to determine the nonlabor invoice or revenue amounts.
The extension is defined by the following items:
Extension Component |
Name |
---|---|
Body template |
pjb_client_extn_billing.pkb |
Specification template |
pjb_client_extn_billing.pkh |
Package |
pjb_client_extn_billing |
Procedure |
Calc_NLBR_Bill_Amount |
Important
Do not change the name of the extension procedures or parameters. Also, do not change the parameter types or parameter order in your procedure. After you write a procedure, compile it and store it in the database.
Parameters
Information about parameters for this client extension are below.
Bill Rate
Return one of the following values as the x_bill_rate_flag parameter value to specify if the amount that you have derived is based on a bill rate or a percent markup:
B (specifies bill rate)
null or value other than B (specifies markup)
If you specify that your amount is based on a bill rate, Oracle Fusion Projects populates the bill rate of the expenditure item by dividing the bill amount by the number of hours. If you specify that your amount is a markup, Oracle Fusion Projects does not set the bill rate.
Status
Use the x_status parameter to handle error conditions for your procedure. This parameter indicates the processing status of your extension as described in the following table.
Status |
Description |
---|---|
x_status = 0 |
The extension executed successfully. |
x_status < 0 |
An Oracle error occurred and the process did not complete. Oracle Fusion Projects writes an error message to the process log file and rolls back the transactions processed for the entire project. |
x_status > 0 |
An application error occurred. Oracle Fusion Projects writes a rejection reason to PA_EXPENDITURE_ITEMS.REV_DIST_ REJECTION_CODE and does not mark items as revenue distributed. You can review the rejection reason in the revenue generation exception report. |
Oracle Fusion Projects uses nonlabor billing extensions for rate-based invoice method classifications or rate-based and as-incurred revenue method classifications during invoice or revenue generation. During processing, if Oracle Fusion Projects encounters a transaction that has a derived bill amount from a nonlabor billing transaction, it skips the standard bill amount and rate calculation section of the invoice or revenue process for that transaction.
Design Issues
Consider the following design issues for nonlabor billing extensions:
What are the conditions and circumstances in which you cannot use the standard, rate-based invoice and revenue method classifications supported by Oracle Fusion Projects?
How are the invoice and revenue amounts calculated in these cases?
How do you identify nonlabor transactions that meet these conditions?
How do you store rates and other information that your calculations require? How are the rates and other information maintained?
What are the exception conditions for your nonlabor billing extension? What is the exception handling if you cannot find a rate that should exist?
You set up a hierarchy for Oracle Fusion Projects in the application tax options of Oracle E-Business Tax. The Generate Invoice process uses the Application Tax Options hierarchy to determine the default tax classification codes on invoice lines. The Output Tax billing extension is one of the default tax options in the Application Tax Options hierarchy.
The Generate Invoice process calls the Output Tax extension if it does not find the default tax classification code from the other tax options you defined in the application Tax Options hierarchy. You can use the extension to satisfy your business rules in assigning the default tax classification code for invoice lines.
The name for this procedure is get_tax_codes. This procedure assigns a tax classification code to an invoice line.
The extension is defined by the following items:
Extension Component |
Name |
---|---|
Body template |
pjb_client_extn_output_tax.pkb |
Specification template |
pjb_client_extn_output_tax.pkh |
Package |
pjb_client_extn_output_tax |
Procedure |
get_tax_codes |
Important
Do not change the name of the extension procedures or parameters. Also, do not change the parameter types or parameter order in your procedure. After you write a procedure, compile it and store it in the database.
Parameters
Information about parameters for this billing extension are in the table below.
Parameter Name |
Description |
---|---|
p_Contract_Id |
Contract identifier, Number |
p_Customer_Id |
Customer identifier, Number |
p_bill_to_site_use_id |
Bill-to Site identifier, Number |
p_ship_to_site_use_id |
Ship-to Site identifier, Number |
p_ledger_id |
Ledger, Number |
p_expenditure_item_id |
Expenditure item, Number |
p_event_id |
Event, Number |
p_line_type |
Default value is Null, Number |
x_output_tax_code |
Tax ID |
x_return_status |
Return status of the procedure. Valid values are:
Varchar2 |
x_msg_count |
Message count. Valid values are:
Number |
x_msg_data |
Actual message in case of any errors. Default value is Null. Varchar2 |
The Receivables Transaction Type Extension enables you to determine the receivables transaction type when you transfer invoices to Oracle Fusion Receivables.
Oracle Fusion Projects calls the Receivables Transaction Type Extension during the Transfer Invoices to Oracle Fusion Receivables process.
The extension is defined by the following items:
Extension Component |
Name |
---|---|
Body template |
pjb_client_extn_inv_transfer.pkb |
Specification template |
pjb_client_extn_inv_transfer.pkh |
Package |
pjb_client_extn_inv_transfer |
Procedure |
get_ar_trx_type |
Important
Do not change the name of the extension procedures or parameters. Also, do not change the parameter types or parameter order in your procedure. After you write a procedure, compile it and store it in the database.
Parameters
Information about parameters for this billing extension are in the table below.
Parameter Name |
Description |
---|---|
p_Contract_Id |
Contract identifier, Number Corresponds to column CONTRACT_ID in the OKC_K_HEADERS_ALL_B table. |
p_Invoice_Num |
Invoice number Corresponds to column INVOICE_NUM in the PJB_INVOICE_HEADERS table. |
p_Invoice_Class |
Invoice class, Varchar2 Valid values are:
|
p_Contract_Curr_Inv_Amt |
Sum of invoice amount in contract currency, Number Corresponds to column CONTRACT_CURR_INV_AMT in the PJB_INVOICE_LINES table. |
p_Contract_Curr_Code |
Contract currency code, Varchar2 Corresponds to column Contract_Currency_code in the PJB_INVOICE_HEADERS table. |
p_Inv_Curr_Code |
Invoice currency code, Varchar2 Corresponds to the column Invoice_Currency_code in the PJB_INVOICE_HEADERS table. |
p_Inv_Curr_Inv_amt |
Sum of invoice amount in invoice currency, Number Corresponds to column Inv_Curr_Line_Amt in the PJB_INVOICE_LINES table. |
p_Ar_trx_type_Id |
Transaction Type ID, Number Corresponds to column CUST_TRX_TYPE_ID in the RA_CUST_TRX_TYPES table. |
X_ar_trx_type_id |
Transaction type ID, Number |
x_return_Status |
Return status of the procedure, Varchar2 Valid values are:
|
x_msg_count |
Message count, Number Valid values are greater than zero. |
X_msg_data |
Actual message when an error exists, Varchar2 Default value is Null. |
Transaction dependent billing extensions are only executed when other transactions are processed. Transaction dependent billing extensions are called only if billable expenditure items and events exist that need to be processed. For example, a transaction dependent billing extension is not called when there are new transactions set to nonbillable status that are not processed during revenue or invoice generation.
Transaction independent billing extensions are executed for each contract with an active billing assignment, even if there are no transactions to process. This type of billing extension relies on input other than billable transactions on a contract.
Note
Transaction independent billing extensions are processed every time you generate revenue or invoices.