Browser version script Skip Headers

Oracle® Fusion Applications Project Management Implementation Guide
11g Release 1 (11.1.2)
Part Number E20384-02
Go to contents  page
Contents
Go to Previous  page
Previous
Go to previous page
Next

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

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:

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:

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 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:

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:

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:

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:

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:

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

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:

  • 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

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:

  • 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.