Implementing Accounting Client Extensions for Oracle Internet Expenses

Implementing Accounting Client Extensions for Oracle Internet Expenses

Table of Contents

This white paper contains the following information.

Overview
Standard Accounting Generation
Non-Project Expenses
Expense Allocations Enabled with Online Validation
Expense Allocations Enabled without Online Validation
Expense Allocations Disabled
Project Expenses
Expenses Audit
Client Extensions (AP_WEB_CUST_ACCTG_PKG)
Non-Project Expenses
BuildAccount
GetIsCustomBuildOnly
Project Expenses
BuildDistProjectAccount
Client Extensions Use Cases
Non-Project Expenses
Expense Allocations Enabled With Online Validation
Expense Allocations Enabled without Online Validation
Expense Allocations Disabled
Project Expenses
Change Record
1. Overview

Oracle Internet Expenses Accounting Generation is done during expenses entry, in workflow, and in the expenses audit module. Accounting generation comprises two stages irrespective of where it is done:

Build Code Combinations – This stage entails establishing valid accounting segment values. These values are obtained either through system defaults or user updates.
Validate Code Combinations – This stage ensures that the built code combinations exist and pass cross validation rules. If build code combinations do not exist, they can be created automatically, provided dynamic insertion is turned on.
Standard Accounting Generation – To build code combinations, Oracle Internet Expenses provides hard-coded logic to default accounting segment values. Once defaulted, users can perform updates to complete the build stage. For validations, Oracle Internet Expenses uses the standard Oracle eBusiness suite code combination validations. The standard validation mainly comprises ensuring that code combinations exist, and that code combinations comply with cross validation rules. See: Section 2, Standard Accounting Generation.

Customizable Accounting Generation – Starting in 11i.OIE.J.RUP2, Internet Expenses provides three GL Accounting client extensions. The first two are available for non-project expenses, and the third one is available for project-related expenses. The client extensions are PL/SQL API’s which are designed to let customers create custom rules to build and validate code combinations. If enabled, these PL/SQL API’s are called during expenses entry and in workflow (based on system setup), and in the expenses audit module. See: Section 3, Client Extensions (AP_WEB_CUST_ACCTG_PKG).

Attention:

If PL/SQL API’s are customized, they override both stages of the standard accounting generation irrespective of which expense reporting process they are called from.

2. Standard Accounting Generation

For expenses entry and workflow, three factors determine whether accounting generation occurs during expenses entry versus in workflow:

Whether end users can perform expense allocations (in other words, update GL accounting segments)
Whether online validations is enabled
Whether expenses are charged to Oracle Projects projects and tasks. If expense allocations is enabled, end users can only update accounting for non-project expenses.
For expenses audit, code combinations are rebuilt when auditors change expense types. For project expenses, code combinations can further be rebuilt if accounting is updated directly. For the validation stage, expenses are re-validated when expense types are changed, and when auditors make updates to the accounting segments.

Standard Accounting Generation, Non-Project Expenses

During expenses entry, accounting is built based on system defaults and end user updates. End user updates consist of changing the cost center for the expense report, and updating GL segments for expenses. To track user changes, the account generation occurs twice: once to build the account based on original parameters, and again to build the account based on new parameters. For more information, refer to Setting Up Expense Allocations in chapter 3 of the Oracle Internet Expenses Implementation and Administration Guide. In particular, refer to the Expense Allocation Updates and Validation discussion for how accounts are built and validated.

This table discusses the different use cases for any expense line not charged to Oracle Projects project and task.

Expense Allocations Enabled with Online Validation

Process Point Where Build Accounting Validate Accounting System Setup
Expenses Entry Expense Allocations step
Occurs when:

Users access the page
Users change the expense report cost center after allocations have been made
Users change the expense type for a line that has already been allocated
Users update accounting segments and click Update or Next buttons.
Users do not update accounting, click Next button
Users update accounting segments, click Update or Next buttons.
OIE: Enable Expense Allocations = either ‘Automatically-enabled with Online Validation,’ or ‘User-enabled with Online Validation.’
Workflow Expenses workflow Server Side Validation process Occurs when building the default employee account
Same as build accounting

Not applicable
Expenses Entry Expense Allocations step Update Accounting page User updates accounting segments and clicks Preview or Apply OIE: Enable Expense Allocations = either Automatically-enabled with Online Validation or User-enabled with Online Validation

Expense Allocations Enabled without Online Validation

Process Point Where Build Accounting Validate Accounting System Setup
Expenses Entry Expense Allocations step
Occurs when:

Users access the page
Users change the expense report cost center after allocations have been made
Users changed the expense type for a line that has already been allocated
Users update accounting segments and click Update or Next buttons.
Does not occur during expenses entry

OIE: Enable Expense Allocations = either ‘Automatically-enabled’, or ‘User-enabled’.
Workflow Expenses workflow Server Side Validation process Does not occur in workflow, for accounting generation at the distribution level
After user submits expense report

No setup required to enable in workflow. Performer must be defined for Expense Allocation Errors notification.
Workflow Expenses workflow Server Side Validation process Occurs when building the default employee account at the header level
Same as build accounting

Expense Allocations Disabled

Process Point Where Build Accounting Validate Accounting System Setup
Expenses Entry Not applicable
Does not occur during expenses entry

Does not occur during expenses entry

OIE: Enable Expense Allocations = ‘No’
Workflow Expenses workflow Server Side Validation process After user submits expense report, for accounting generation at the distribution level
Same as build accounting

Not applicable

Standard Accounting Generation, Project Expenses

If expenses are charged to Oracle Projects projects and tasks, account generation is only performed in workflow. For more information, refer to Integrating with Oracle Projects in chapter 2 of the Oracle Internet Expenses Implementation and Administration Guide. In particular, refer to the Project Expense Report Account Generator discussion.

This table discusses the behavior of any expense line charged to a project and task.

Where Occurs Where Occurs Build Accounting Validate Accounting System Setup
Expenses Entry Not applicable
Does not occur during expenses entry

Same as build accounting

Projects entry enabled via the OIE: Enable Projects Allocations profile option
Workflow Expenses workflow Server Side Validation process Internet Expenses calls the Project Expense Report Account Generator, for accounting generation at the distribution level
Same as build accounting

Define Account Generator in Oracle Projects
Workflow Expenses workflow Server Side Validation process Occurs when building the default employee account at the header level
Same as build accounting

Not applicable

Standard Accounting Generation, Expenses Audit

The Expenses Audit module is accessed from either of the following seeded responsibilities: Internet Expenses Auditor, or Internet Expenses Audit Manager.

This table discusses the accounting generation behavior in the Expenses Audit module.

Project or Non-Project Where Build Accounting Validate Accounting Comments
Non-Project Expenses On Audit Expense Reports page
Occurs when auditors change expense types

Same as build accounting For build accounting, segment values are overwritten if segments defined for the expense type setup
Project Expenses On Audit Expense Reports page
Occurs when auditors change expense types

Internet Expenses calls the Project Expense Report Account Generator

Same build comments as for non-project expenses

3. Client Extensions (AP_WEB_CUST_ACCTG_PKG)

As noted in the overview, three separate PL/SQL API client extensions are provided with OIE.J RUP2. The following issues should be kept in mind as you plan and implement your customizations.

System Setup Controls Behavior – The build and validation stages refer to the same setup that was documented in the Standard Accounting Generation section earlier. For example, if you enable expense allocations without online validation, then only the build portion of the customization will be called during expenses entry.
Impact on Standard Accounting Generation – If the customization is performed, then both the standard build and validation logic are overridden. For the validation stage, you should call the standard validation logic from your customization.
Impact on Expenses Processing – Since the same PL/SQL API’s are called during expenses entry, workflow, and expenses audit, the customization applies to all three points in the expenses process. In other words, you cannot choose to, for example, call the customization for expenses entry, and not for expenses audit.
Impact in Expenses Audit – The customization is only called when auditors change expense types. If auditors directly update accounting segments, then no builds occur, and the standard validation logic is invoked.

Attention:

It is critical that you evaluate the performance impact if accounting generation is customized. In addition, it is recommended that you call the standard accounting validation instead of creating your own customized validation logic.

Client extensions are provided in PL/SQL package AP_WEB_CUST_ACCTG_PKG, which is stored under:

$AP_TOP/patch/115/sql/apwcaccs.pls (package specification)
$AP_TOP/patch/115/sql/apwcaccb.pls (package body)
Non-Project Expenses

BuildAccount

This function provides a client extension to Oracle Internet Expenses for building and validating account code combinations for non-project related expense lines.

FUNCTION BuildAccount(
p_report_header_id IN NUMBER,
p_report_line_id IN NUMBER,
p_employee_id IN NUMBER,
p_cost_center IN VARCHAR2,
p_exp_type_parameter_id IN NUMBER,
p_segments IN AP_OIE_KFF_SEGMENTS_T,
p_ccid IN NUMBER,
p_build_mode IN VARCHAR2,
p_new_segments OUT NOCOPY AP_OIE_KFF_SEGMENTS_T,
p_new_ccid OUT NOCOPY NUMBER,
p_return_error_message OUT NOCOPY VARCHAR2) RETURN BOOLEAN;

| RETURNS
| True if BuildAccount was customized
| False if BuildAccount was NOT customized

How BuildAccount is invoked

BuildAccount is invoked:
indirectly by the Middle Tier (Java objects used in Expenses Entry and Audit call a PL/SQL wrapper which call BuildAccount)
directly by the Server Tier (PL/SQL wrappers used by Expenses Entry, Audit, and Workflow call BuildAccount)
How to validate account segments in BuildAccount

For details on how to validate key flexfields, refer to Oracle Application Flexfields Guide. You may also refer to Internet Expenses Standard Accounting Generation logic in AP_WEB_ACCTG_PKG.BuildAccount ($AP_TOP/patch/115/sql/apwacctb.pls).

Error Handling in BuildAccount

Since BuildAccount is invoked in 2 different technology stacks: Java objects(indirectly) and PL/SQL (directly), you must accommodate two types of error handling.

For Java technology stack, you must use FND_MSG_PUB and FND_MESSAGE PL/SQL APIs to initialize an error stack and add a message to the error stack.

To initialize the error stack:
FND_MSG_PUB.initialize;

To create a message:

if the message is stored in FND_NEW_MESSAGES:
FND_MESSAGE.set_name(&APPL_SHORT_NAME, &MESSAGE_NAME);
e.g.
FND_MESSAGE.set_name(‘SQLAP’, ‘OIE_CORRECT_INVALID_CCID’);

To add a message to the error stack:
FND_MSG_PUB.ADD();
BuildAccount parameter p_return_error_message OUT NOCOPY VARCHAR2, allows you to pass back the error message text to the PL/SQL technology stack, which can be displayed in Expenses Worklfow.

To set the return error message parameter:

if the message is stored in FND_NEW_MESSAGES:
FND_MESSAGE.set_name(&APPL_SHORT_NAME, &MESSAGE_NAME);
p_return_error_message := FND_MESSAGE.GET;
e.g.
FND_MESSAGE.set_name(‘SQLAP’, ‘OIE_CORRECT_INVALID_CCID’);
p_return_error_message := FND_MESSAGE.GET;

GetIsCustomBuildOnly

GetIsCustomBuildOnly is called by the Expenses Entry Allocations page when users press Update/Next (only in the case where Online Validation is disabled). Since Online Validation is disabled, there needs to be a capability to use the BuildAccount client extension to rebuild account segments in expenses entry. The GetIsCustomBuildOnly function allows you to indicate whether you want to enable this capability or not.

If you do enable this capability, then you must update BuildAccount to support p_build_mode=C_CUSTOM_BUILD_ONLY.

If you do not enable this capability, then the possibility for rebuilding the account segments may occur in Expenses Workflow with BuildAccount p_build_mode=C_VALIDATE.

FUNCTION GetIsCustomBuildOnly RETURN NUMBER;

| RETURNS
| return 1 – if you want to enable custom builds
| return 0 – if you do not want to enable custom builds

| If Online Validation is enabled, custom rebuilds can be performed
| in BuildAccount (when p_build_mode = C_VALIDATE).
|
| If Online Validation is disabled, custom rebuilds can be performed
| in BuildAccount, as follows:
| (1) in Expenses Entry Allocations page (when p_build_mode = C_CUSTOM_BUILD_ONLY)
| (2) in Expenses Workflow AP Server Side Validation (when p_build_mode = C_VALIDATE)

How GetIsCustomBuildOnly is invoked

GetIsCustomBuildOnly is invoked:
Indirectly by the Middle Tier (Java object used in Expenses Entry calls a PL/SQL wrapper which call GetIsCustomBuildOnly)
Directly by the Server Tier (PL/SQL wrapper used by Expenses Entry calls GetIsCustomBuildOnly)
Project Expenses

BuildDistProjectAccount

This function provides a client extension to Internet Expenses for building and validating account code combinations for projects related expense lines.

FUNCTION BuildDistProjectAccount(
p_report_header_id IN NUMBER,
p_report_line_id IN NUMBER,
p_report_distribution_id IN NUMBER,
p_exp_type_parameter_id IN NUMBER,
p_new_segments OUT NOCOPY AP_OIE_KFF_SEGMENTS_T,
p_new_ccid OUT NOCOPY NUMBER,
p_return_error_message OUT NOCOPY VARCHAR2,
p_return_status OUT NOCOPY VARCHAR2) RETURN BOOLEAN;

RETURNS
| True if BuildDistProjectAccount was customized
| False if BuildDistProjectAccount was NOT customized

How BuildDistProjectAccount is invoked

BuildDistProjectAccount is invoked:
Indirectly by the Middle Tier (Java object used in Expenses Audit calls a PL/SQL wrapper which call BuildDistProjectAccount)
Directly by the Server Tier (PL/SQL wrappers used by Expenses Audit and Workflow call BuildDistProjectAccount)
How to validate account segments in BuildDistProjectAccount

Error Handling in BuildDistProjectAccount

Since BuildDistProjectAccount is invoked in 2 different technology stacks: Java objects(indirectly) and PL/SQL (directly), you must accommodate two types of error handling.

For Java technology stack, you must use FND_MSG_PUB and FND_MESSAGE PL/SQL APIs to initialize an error stack and add a message to the error stack.

To initialize the error stack:
FND_MSG_PUB.initialize;

To create a message:

if the message is stored in FND_NEW_MESSAGES:
FND_MESSAGE.set_name(&APPL_SHORT_NAME, &MESSAGE_NAME);
e.g.
FND_MESSAGE.set_name(‘SQLAP’, ‘OIE_CORRECT_INVALID_CCID’);

To set the return error message parameter:

In either case(invoked from Java or PL/SQL), you must set parameter p_return_status to either:

‘SUCCESS’
‘ERROR’
‘VALIDATION_ERROR’
‘GENERATION_ERROR’

4. Client Extensions Use Cases

Non-Project Expenses

Expense Allocations with Online Validation

This describes the use cases, current business logic, and client extensions used in Expense Allocations with Online Validation.

Use Case Client Extension
When Expense Allocations page is first accessed

When Expense Allocations page is accessed after user changed the expense type for a line that has already been allocated

When Expense Allocations page is accessed after user changed the expense report header cost center

AP_WEB_CUS_ACCTG_PKG.BuildAccount

| PARAMETERS
| p_report_header_id – contains report header id
| p_report_line_id – contains report line id
| p_employee_id – contains the employee id
| p_cost_center – contains the expense report cost center
| p_exp_type_parameter_id – contains the expense type parameter id
| p_segments – contains the expense report line segments
| p_ccid – NULL in this case
| p_build_mode – AP_WEB_ACCTG_PKG.C_DEFAULT
| p_new_segments – returns the new expense report line segments
| p_new_ccid – returns the new expense report line
| code combination id
| p_return_error_message – returns any error message if an error occurred

When user presses Update on Expense Allocations page for lines that have been updated by users. Also, when users click Next for lines that haven’t been validated

AP_WEB_CUS_ACCTG_PKG.BuildAccount

| PARAMETERS
| p_report_header_id – contains report header id
| p_report_line_id – contains report line id
| p_employee_id – contains the employee id
| p_cost_center – NULL in this case
| p_exp_type_parameter_id – NULL in this case
| p_segments – contains the expense report line segments
| p_ccid – NULL in this case
| p_build_mode – AP_WEB_ACCTG_PKG.C_VALIDATE
| p_new_segments – returns the new expense report line segments
| p_new_ccid – returns the new expense report line
| code combination id
| p_return_error_message – returns any error message if an error occurred

When Expense Report is processed by Expenses Workflow AP Server Side Validation Process (AP Validate Expense Report)

(Always used for building and validating default employee accounting at the header level)

AP_WEB_CUS_ACCTG_PKG.BuildAccount

| PARAMETERS
| p_report_header_id – NULL in this case
| p_report_line_id – NULL in this case
| p_employee_id – contains the employee id
| p_cost_center – contains the expense report cost center
| p_exp_type_parameter_id – NULL in this case
| p_segments – NULL in this case
| p_ccid – NULL in this case
| p_build_mode – AP_WEB_ACCTG_PKG.C_DEFAULT_VALIDATE
| p_new_segments – returns the default employee segments
| p_new_ccid – returns the default employee code combination id
| p_return_error_message – returns any error message if an error occurred
Expense Allocations without Online Validation

This describes the use cases, current business logic, and client extensions used in Expense Allocations without Online Validation.

Use Case Client Extensions
When Expense Allocations page is first accessed

When Expense Allocations page is accessed after user changed the expense type for a line that has already been allocated

When Expense Allocations page is accessed after user changed the expense report header cost center

AP_WEB_CUS_ACCTG_PKG.BuildAccount

When user presses Update/Next from Expense Allocations page for lines that haven’t been validated yet and a Custom Build hook is provided

AP_WEB_CUS_ACCTG_PKG.BuildAccount

| PARAMETERS
| p_report_header_id – contains report header id
| p_report_line_id – contains report line id
| p_employee_id – contains the employee id
| p_cost_center – NULL in this case
| p_exp_type_parameter_id – NULL in this case
| p_segments – contains the expense report line segments
| p_ccid – NULL in this case
| p_build_mode – AP_WEB_ACCTG_PKG.C_CUSTOM_BUILD_ONLY
| p_new_segments – returns the new expense report line segments
| p_new_ccid – returns the new expense report line
| code combination id
| p_return_error_message – returns any error message if an error occurred

When Expense Report is processed by Expenses Workflow AP Server Side Validation Process (AP Validate Expense Report)

(Used to build accounting at the line level)

AP_WEB_CUS_ACCTG_PKG.BuildAccount

| PARAMETERS
| p_report_header_id – contains report header id
| p_report_line_id – contains report line id
| p_employee_id – contains the employee id
| p_cost_center – contains the expense report cost center
| p_exp_type_parameter_id – contains the expense type parameter id
| p_segments – contains the expense report line segments
| p_ccid – NULL in this case
| p_build_mode – AP_WEB_ACCTG_PKG.C_VALIDATE
| p_new_segments – returns the new expense report line segments
| p_new_ccid – returns the new expense report line
| code combination id
| p_return_error_message – returns any error message if an error occurred

When Expense Report is processed by Expenses Workflow AP Server Side Validation Process (AP Validate Expense Report)

(Always used for building and validating default employee accounting at the header level)

AP_WEB_CUS_ACCTG_PKG.BuildAccount

This describes the use cases, current business logic, and client extensions used when Expense Allocations is disabled.

Use Case Client Extensions
When Expense Report is processed by Expenses Workflow AP Server Side Validation Process (AP Validate Expense Report)

(Used to build accounting at the line level)

AP_WEB_CUS_ACCTG_PKG.BuildAccount

| PARAMETERS
| p_report_header_id – contains report header id
| p_report_line_id – contains report line id
| p_employee_id – contains the employee id
| p_cost_center – contains the expense report cost center
| p_exp_type_parameter_id – contains the expense type parameter id
| p_segments – NULL in this case
| p_ccid – NULL in this case
| p_build_mode – AP_WEB_ACCTG_PKG.C_DEFAULT_VALIDATE
| p_new_segments – returns the new expense report line segments
| p_new_ccid – returns the new expense report line
| code combination id
| p_return_error_message – returns any error message if an error occurred

When Expense Report is processed by Expenses Workflow AP Server Side Validation Process (AP Validate Expense Report)

(Always used for building and validating default employee accounting at the header level)

AP_WEB_CUS_ACCTG_PKG.BuildAccount

This describes the use cases, current business logic, and client extensions used Expense Audit.

Use Case Client Extensions
When Auditor changes the Expense Report Line’s Expense Type in Expenses Audit

AP_WEB_CUS_ACCTG_PKG.BuildAccount

| p_return_error_message – returns any error message if an error occurred

Project Expenses

This describes the use cases, current business logic, and client extensions used for Projects.

Use Case Client Extensions
When Expense Report is processed by Expenses Workflow AP Server Side Validation Process (AP Validate Expense Report)

(Used to build accounting at the line level)

AP_WEB_CUS_ACCTG_PKG.BuildDistProjectAccount

| PARAMETERS
| p_report_header_id – contains report header id
| p_report_line_id – contains report line id
| p_report_distribution_id – contains report distribution id
| p_exp_type_parameter_id – contains the expense type parameter id
| p_new_segments – returns the new expense report line segments
| p_new_ccid – returns the new expense report line
| code combination id
| p_return_error_message – returns any error message if an error occurred
| p_return_status – returns either ‘SUCCESS’, ‘ERROR’,
‘VALIDATION_ERROR’, ‘GENERATION_ERROR’

When Auditor changes the Expense Report Line’s Expense Type in Expenses Audit

AP_WEB_CUS_ACCTG_PKG.BuildDistProjectAccount

When Expense Report is processed by Expenses Workflow AP Server Side Validation Process (AP Validate Expense Report)

(Always used for building and validating default employee accounting at the header level)

AP_WEB_CUS_ACCTG_PKG.BuildAccount

Reference Doc ID 333199.1

Enterprise Resource Planning and Integrations BlogSpot

Implementing Accounting Client Extensions for Oracle Internet Expenses

Leave a Reply Cancel reply

Share this:

Like this:

Related

Leave a Reply Cancel reply