Skip Headers

Contents

48 Project Billing Configuration: Define Project Billing Extensions

This chapter contains the following:

Billing Extension Components: How They Work Together

Planning Your Billing Extension Implementation: Explained

Billing Extension

Labor Billing Extension

Nonlabor Billing Extension

Output Tax Extension

Receivables Transaction Type Extension

FAQs for Define Project Billing Extensions

Billing Extension Components: How They Work Together

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.

General Information

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.

Call Process

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.

Call Location

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.

Required Input

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.

Default Event Type

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.

Default Plan Type

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.

Planning Your Billing Extension Implementation: Explained

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.

Design Billing Extensions

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.

Write and Store PL/SQL Procedures

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 Billing Extensions

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 Invoice Methods and Revenue Methods

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.

Billing Extension

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: REV (for revenue) INV (for invoice)
p_calculation_level	Calculation level code for the billing extension. Valid values are: LINE PROJECT_CONTRACT_LINKAGE
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: S (for success) E (for expected error) U (for unexpected error)
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 Extension

Labor Billing Extension

The 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: ACTUAL (default value) FORECAST
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: 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.
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?

Nonlabor Billing Extension

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

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?

Output Tax Extension

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

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: S (Successful) E (Error) Varchar2
x_msg_count	Message count. Valid values are: >=0 (Greater than zero) Number
x_msg_data	Actual message in case of any errors. Default value is Null. Varchar2

Receivables Transaction Type Extension

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

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: INVOICE (Regular invoice) CREDIT_MEMO (Crediting invoice) WRITE_OFF (Write-off invoice) CANCEL (Canceling invoice)
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: S (Successful) E (Error)
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.

FAQs for Define Project Billing Extensions

What's the difference between transaction dependent and transaction independent billing extensions?

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.