Skip to content

 
Accessibility Preferences
PowerView is
Off
Switch to Cloud Support Ahmed (Available) (0) Contact UsHelp
 
 
Dashboard
Knowledge
Service Requests
Patches & Updates
Community
Certifications
Systems
Collector
Advanced Customer Services
Settings
Global Search
Doc ID 74315.1

   
Copyright (c) 2019, Oracle. All rights reserved. Oracle Confidential.

Oracle Payroll - Understanding Balances and Balance Retrieval (Doc ID

74315.1) Bottom

  Was this document helpful?  

In this Document
Ye
s
Abstract
History No

Details    

  1. Introduction   Document Details  

  1.1 Balance Feeds
  1.2 Balance Dimensions Type: WHITE PAPER
  1.3 Initial Balance Loading Status:
PUBLISHED
  1.4 Balance Adjustments Last Major Update:
13-Nov-2018
  1.5 Defined Balances Last Update:
13-Nov-2018
2. Retrieving Balance
 
Information      

  2.1 Latest Balances

  2.2 Run Balances   Related Products  
  2.3 Expiry Oracle Payroll
  2.4 Routes      

  2.5 Balance User Exit   Information Centers  

  2.5.1 Deriving the Balance Information Center: Oracle HRMS (Saudi Arabia) [2469373.2]
  2.5.2 Setting Contexts
2.5.3 Sqlplus access to Information Center: Oracle Payroll (All Application Versions) [1482175.2]
 
Balances
Information Center: Oracle HRMS (Kuwait) [2469380.2]
  2.5.4 UK Legislation
Summary Information Center: Oracle E-Business Suite HRMS / HCM [1099813.2]
References
Information Center: Oracle Core Payroll (Costing) (All Application Versions)
[1954800.2]

APPLIES TO: Show More

     

  Document References  
Oracle Payroll - Version
The Secret Life of Initial Balance
11.5.10.2 and later Upload with Screenshots Example
Information in this [60057.1]
document applies to any
platform. Using User Defined Functions (UDFs)
In FastFormula [73452.1]
ABSTRACT
 

 
  Recently Viewed  
Oracle Payroll - Understanding Balances and Balance Retrieval
To give a technical [74315.1]
understanding of Oracle
Payroll balances and how to How to Convert an Implementation User Into a Normal Fusion
retrieve balance values. Application User [2089250.1]

Global Human Resources: Link Existing User Account to

HISTORY Existing Employee in Bulk [2504955.1]

How Can The Implementation User Account Be Converted To

Author:  Lynn Waters An Employee Account? [1568058.1]

DETAILS How to Specify Log in/UserName Format when creating a New

User/ Hiring an Employee [1641572.1]
1. INTRODUCTION
Show More
     

Balances hold the positive or

negative accumulation of
results, generated by payroll
runs, over specified periods
of time. There are two
categories of balances in
Oracle Payroll: Startup
balances are supplied with a
localization to hold data
required by legislation; and
User Defined balances are
defined by the user to meet
specific business
requirements.

1.1 Balance Feeds

Balances are fed with values

held in element input values.
You can define balance
feeds from specific element
input values, or from the Pay
Values of all elements of a
particular classification.

1.2 Balance Dimensions

Balance dimensions define

the period of time over
which the balances
accumulate before being
reset. Examples of the
periods of time are period-
to-date and tax year year-to-
date. There are a number of
standard seeded dimensions
and also legislation specific
dimensions. 

Most balances apply at

assignment level. The
DIMENSION_TYPE held in
PAY_BALANCE_DIMENS
IONS determines how a
balance is treated. The
dimension type can take one
of the following values:

 'A' - The balance is

fed and stored at
assignment-level and
the dimensioncreates
an assignment level
latest balance and
stores it in
PAY_ASSIGNMEN
T_LATEST_BALA
NCES.
 'P' - The balance is
fed and stored at
person-level and the
dimension creates a
person level latest
balance and stores it
in
PAY_PERSON_LA
TEST_BALANCES.
 'N' - Not fed and not
stored. No latest
balance value is ever
created. Whenever
the balance is
accessed the sql to
calculate the value
 isalways executed.
 'F' - Fed but not
stored. This
dimension type
creates a balance in
memory during the
payroll run. This
balance is fed by the
run code but is not
stored as a latest
balance.
 'R' - Run level
balance. This
dimension type is
used specifically for
those balances that
total for the current
run. No latest
balance is held.

It is possible in, UK
legislation, to create your
own balance dimensions in
Release 11 using the Create
Balance Dimension process
(via the Submit Processes
and Reports screen
[Processes & Reports-
>Submit Processes &
Reports]). You enter a
balance suffix, a balance
level (eg Assignment), a
balance time period start
date and a reset frequency.
This dimension will then be
available to use with any
predefined or user defined
balance.

There are two dimensions

supplied specifically for UK
Court Order elements. They
hold values for specific
element entries and are
needed when an assignment
has more than one current
Court Order. They are
_ELEMENT_ITD and
_ELEMENT_PTD and
cannot be used with any
other elements.

1.3 Initial Balance Loading

The balance upload

procedure transfers
accumulated seeded & user
balance values into Oracle
Payroll for use by
implementations which
begin processing mid-
financial year. Year to date
and other balance values are
required by Oracle Payroll to
calculate earnings and
deductions in accordance
with local legislative
requirements. Often
processing under Oracle
Payroll begins during a
financial year and no
accumulated balance values
will be held at the
commencement of this
processing. It follows that
these required balance
values must be loaded into
Oracle Payroll prior to
processing payrolls mid-
year. This is achieved
through the Initial Balance
Upload process.  

For more information

see Document 60057.1 The
Secret Life of Initial Balance
Upload; and the Oracle
HRMS UK Implementation
Guide essay Initial Balance
Loading for Oracle Payroll.

1.4 Balance Adjustments

A balance adjustment may
be necessary when an
incorrect payment has been
made and it is not possible to
rollback the payroll and
rerun. It allows you to
correct an incorrect balance
value. When you save an
adjustment it processes like
a payroll run with just one
entry and the value you enter
becomes a processed run
result.

1.5 Defined Balances

A defined balance is the

name used to identify a
combination of balance type
and balance dimension eg
GROSS_PAY_ASG_YTD.
In reports on balances you
will need to refer to
DEFINED_BALANCE_ID
to return a value. Defined
balances are held in
PAY_DEFINED_BALANC
ES.

2. RETRIEVING
BALANCE
INFORMATION

2.1 Latest Balances

To improve payroll run

performance, some balance
values are held explicitly in
the database. These are
known as latest balance
values. The payroll process
accesses and updates latest
balance values as it runs. If a
latest value is not set then
the balance value has to be
accessed by a run balance
(see section 2.2 Run
Balances) or calculated by
summing the run results for
the balance (see section 2.4
Routes).

Latest balance values are

held in
PAY_ASSIGNMENT_LAT
EST_BALANCES and
PAY_PERSON_LATEST_
BALANCES (depending on
the defined balance's
dimension_type (see section
1.2)). These are two distinct
tables but both use a primary
key of
LATEST_BALANCE_ID
that is supplied by the
sequence
PAY_LATEST_BALANCE
S_S.   These tables also hold
the value of the balance prior
to the current value
(PRV_BALANCE_VALUE
). When a rollback is
performed the latest balance
values are deleted and so the
value in
PRV_BALANCE_VALUE
can be accessed to allow the
payroll to be rerun without a
performance degradation. 

These tables are maintained

by the payroll run which
inserts or updates a row in
the relevant latest balances
table for each defined
balance referenced by a
Payroll Fastformula. So if a
particular balance and
dimension combination is
not accessed by Fastformula,
the latest value will not be
stored.

2.2 Run Balances

Run Level Balances are used

to improve the performance
of balance retrieval when no
latest balance is available. 
The payroll run already
calculates all the assignment
run level balances as it
processes and these are now
saved in
PAY_RUN_BALANCES.
By storing run balances,
which are the lowest
possible value that can
contribute to a balance, it is
simply a matter of summing
the contributing rows to
return other dimensions e.g.
YTD and QTD.  Legislative
teams decide which balances
may be calculated as Run
Level balances
and group them within
Balance Categories. Balance
Categories are stored in the
table
PAY_BALANCE_CATEG
ORIES_F and the column
SAVE_RUN_BALANCE_E
NABLED defines whether
the balances in that category
are Run Balance enabled.

To identify the currently

seeded categories you can
run the sql ...

select category_name,
legislation_code,
save_run_balance_enabled
From
pay_balance_categories_f;
Below is a current list of GB
legislation categories.  A
User Defined Balance can be
calculated from it's run
balance if the Balance
Category for the balance
allows this.

CATEGORY_NAME             
  LEGIS  
SAVE_RUN_BALANCE_ENABLED

Vehicle Related          
GB      N
OMP
Balances               
GB      N
OSP
Balances               
GB      N
Miscellaneous             
  GB      N
NI and PAYE
Deductions      GB      Y
Statutory
Payments          GB     
Y
Earnings                  
  GB      Y
Direct Payments          
GB      Y
Other
Deductions           
GB      Y

The concurrent program

Generate Run Balances
upgrades historical run data
into the
PAY_RUN_BALANCES
table.  The process will also
need to be run if the status of
a defined balance becomes
'Invalid'. This can be seen in
the Status field on the
Balance Dimensions 
screen for a specific balance,
or by running the 'Run
Balance Architecture
Diagnostic Report'.

2.3 Expiry

A balance is reset when it

expires and this is dependent
on its dimension.  For
example consider the
GROSS_PAY_YTD
balance. When you cross the
tax year boundary you
would expect the value to
return to zero. This expiry of
a balance is maintained
internally and there is code
(in pygbexc.pkb) to work
out if such a boundary has
been crossed for GB
legislation. The balance is
not physically reset in the
database unless it is actually
updated by an assignment
action, so a balance that you
would have expected to
expire but that has not been
updated in a payroll run will
still hold it's old value. 

The latest balance tables

have columns
EXPIRED_VALUE and
EXPIRED_ASSIGNMENT_
ACTION_ID which hold the
value of the dimension of the
balance when it expired, and
the assignment_action_id
which allowed it to expire.

2.4 Routes

During a payroll run, latest

balance values are read and
maintained. For reporting on
balances, the Balance User
Exit uses the latest balances
where they are available.
Where they are not available
the route code is used to
calculate the required
balance value.

Each balance dimension has

an associated route. This is a
fragment of sql code which
defines the value to be
returned when you access a
balance. The code is held in
the TEXT column of
FF_ROUTES.

The select clause of the

statement is always

select
nvl(sum(TARGET.result_val
ue * FEED.scale),0)

So it is a sum of all the run

result values retrieved by the
route code. That is, a sum of
all the run result values that
feed the specific balance
type across a certain span of
time. 

Some example route code is

shown below. It is taken
from FF_ROUTES.TEXT
for the _ASG_PROC_PTD
dimension. The code
requires parameters for
assignment_action_id and
balance_type_id.pay_balanc
e_feeds_f FEED

,pay_run_result_values
TARGET
,pay_run_results RR
,pay_payroll_actions PACT
,pay_assignment_actions
ASSACT
,pay_payroll_actions BACT
,pay_assignment_actions
BAL_ASSACT
where
BAL_ASSACT.assignment_act
ion_id = &B1
and
BAL_ASSACT.payroll_action
_id =
BACT.payroll_action_id
and FEED.balance_type_id
= &U1
and FEED.input_value_id =
TARGET.input_value_id
and TARGET.run_result_id
= RR.run_result_id
and
RR.assignment_action_id =
ASSACT.assignment_action_
id
and
ASSACT.payroll_action_id
= PACT.payroll_action_id
and PACT.effective_date
between
FEED.effective_start_date
and
FEED.effective_end_date
and RR.status in
('P','PA')
and PACT.time_period_id =
BACT.time_period_id
and
ASSACT.action_sequence <=
BAL_ASSACT.action_sequenc
e
and ASSACT.assignment_id
=
BAL_ASSACT.assignment_id

The code identifies all the

possible feeds to the balance,
and restricts the period from
which you select the run
results.

 The BAL_ASSACT
table looks at the
'current' action for
this assignment; 
 The ASSACT table
picks up the actions
for the same
assignment with run
results which feed
the balance;
 The PACT table
picks up the payroll
actions which own
 the ASSACT actions;
 The FEED table
picks up all the input
values which feed the
balance;
 The RR (run results)
table picks up only
results that are
processed ('P' or
'PA');
 The PACT table only
picks up payroll
actions in the same
time period as the
'current' action (as
this is a PTD
dimension);
 The ASSACT table
only picks up actions
previous to and
including the current
action.

2.5 Balance User Exit

The 'Core Balance User Exit'

is actually PL/SQL (not 'C'
code as the name suggests)
and is used for reporting
balance values.

The function to get the

balance value is
PAY_BALANCE_PKG.GE
T_VALUE. The balance
function works in two modes
- assignment action mode
and date mode.

Assignment action mode

retrieves the balance value
as it is after a specified
assignment action
completed.

Function get_value
(p_define_balance_id in
number,
p_assignment_action_id in
number,
p_always_get_db_item in
boolean default false)
return number;

 p_defined_ba
lance_id -
combination
of
balance_type
_id and
dimension_id
from
PAY_DEFIN
ED_BALAN
CES.DEFINE
D_BALANC
E_ID
 p_assignment
_action_id -
ID of the
assignment
action which
updated the
balance to the
value you
want to
retrieve
 p_always_get
_db_item -
This can be
ignored as it
is used for
testing
purposes to
ensure the
function
always
derives the
balance from
the database
item and not
the latest
balance.
Date mode retrieves the
balance value for a specified
assignment on a specified
date.

Function get_value
(p_define_balance_id in
number,
p_assignment_id in
number,
p_virtual_date in date,
p_always_get_db_item in
boolean default false)
return number;

 p_defined_ba
lance_id -
combination
of
balance_type
_id and
dimension_id
from
PAY_DEFIN
ED_BALAN
CES.DEFINE
D_BALANC
E_ID
 P-
assignment_i
d - the
assignment_i
d from
PER_ASSIG
NMENTS_F
 p_virtual_dat
e - The date
for which you
want to get
the balance
value
 p_always_get
_db_item -
This can be
ignored as it
is used for
testing
purposes to
 ensure the
function
always
derives the
balance from
the database
item and not
the latest
balance.

It is not necessary to pass a

'mode' parameter to the
function as the pl/sql
'overloading' feature is used
allowing the function to
recognize which mode is
assumed.

2.5.1 Deriving the Balance

When the
PAY_BALANCE_PKG.GE
T_VALUE function is run in
date mode, a temporary row
is inserted into
PAY_ASSIGNMENT_ACT
IONS. This then allows the
two modes to use the same
method to derive the balance
value. At the end of the 
function, the temporary row
is removed.  In both modes,
to derive the balance value,
the pl/sql first checks if the
balance is of a
dimension_type that saves
latest balance values (see
section 1.2 Balance
Dimensions). If it is then it
will look in the relevant
latest 
balance table (person or
assignment) for a latest
balance for the appropriate
assignment_action_id. If it
finds a latest balance then it
will then check whether the
balance has expired (see
section 2.1 Expiry) and if so
it will return 0; if not it will
return the latest balance
value. If there is no latest
balance available then the
function builds pl/sql code
from FF_ROUTES based on
the balance dimension,
defined balance_id and
assignment_action_id (see
section 2.4 Routes). This
code runs and produces the
balance value.

2.5.2 Setting Contexts

It is necessary to set up
contexts before accessing
parameterized balances.  In
the UK the only
parameterized balances are
the Court Order balances.
You set up the contexts
using the
PAY_BALANCE_PKG.SE
T_CONTEXT(p_context_na
me, p_context_value)
procedure.

To set the context for a

Court Order balance for
example you would run

PAY_BALANCE_PKG.SET_CONTE
XT(ORIGINAL_ENTRY_ID,
1201);

The values for

p_context_name and
p_context_value can be
found as follows:

1. select
latest_balance_id
from
pay_assignment_latest_bal
ances
where assignment_id =
and defined_balance_id =
/

2. select context_id,
value
from
pay_balance_context_value
s
where latest_balance_id =
/

3. select context_name
from ff_contexts
where context_id =
/

 p_context_na
me is
'context_nam
e' from query
3;
 p_context_val
ue is 'value'
from query 2.

For the Court Order

balances, the value for
p_context_name will always
be
'ORIGINAL_ENTRY_ID'.

For balances that are not

parameterized, no calls to
pay_balance_pkg.set_contex
t are necessary.

2.5.3 Sqlplus access to

Balances

The pl/sql routines used in

the balance function can be
called either using:

SQL> select
pay_balance_pkg.get_value
(179, 1121) from dual;
or using the following
example which uses the
get_value function in
assignment action mode:

SQL> set serveroutput on

SQL> declare val number;
2 begin
3 val :=
pay_balance_pkg.get_value
(113, 1121);
4
dbms_output.put_line(val)
;
5 end;
SQL> /
118.1

This will output the value

held in the variable 'val' to
the screen. 118.1 in this
case.

In my example (run on
SN153) the
defined_balance_id (113) is
the defined balance for
NI_A_EMPLOYEE_ASG_P
TD and the
assignment_action (1121) is
a quickpay for
assignent_id=44 with an
effective date of 30-SEP-
1999.

You could run the same code

to run the function in date
mode by supplying the date
mode parameters in line 3:

SQL> set serveroutput on

SQL> declare val number;
2 begin
3 val :=
pay_balance_pkg.get_value
(113, 44,to_date('30-SEP-
1999',
'DD-MON-YYYY'));
4
dbms_output.put_line(val)
;
5 end;
SQL> /
118.1

2.5.4 UK Legislation

The core balance user exit is

replaced with the UK's
Balance User Exit in installs
using UK legislation. This
PL/SQL package is called
HR_GBBAL.  It is not used
within the payroll run - just
in reporting balance values. 
It was written to speed up
performance and provide
view-based balance values,
as the core package could
not do this due to pragma
restrictions and dynamic
SQL. The package is called
by a number of views that
were created for this
purpose. This makes
reporting on balances in
sql*plus much easier that it
is with the core balance user
exit.

For example the view

PAY_GB_BALANCES_V
can display a balance value
and the effective date of the
balance:

SELECT ITEM_NAME
, RESULT_VALUE
FROM PAY_GB_BALANCES_V
WHERE ASSIGNMENT_ID = 44
AND EFFECTIVE_DATE = '30-
SEP-XX'
/

This code will display all

balance names and values
that were updated by an
assignment action on 30-
SEP-XX for
ASSIGNMENT_ID=44.
SELECT BALANCE_NAME
, VALUE
FROM
PAY_PAYGBBAL_VALUES_V
WHERE
ASSIGNMENT_ACTION_ID =
1121
/

This code will display all

balance names and values
for
ASSIGNMENT_ACTION_I
D = 121.

Other localizations use the

core package to report on
balances unless (like UK and
Canada) they have defined
their own.

SUMMARY

Additional
References: 

Document 60057.1 
The Secret Life of
Initial Balance
Upload
Note Document
73452.1 Using User
Defined Functions
(UDFs) In
FastFormula: Oracle
Payroll UK Users'
Guide ch13
Controlling Balance
Information
(A58383-01)

 
 

REFERENCES

NOTE:60057.1 - The Secret

Life of Initial Balance
Upload with Screenshots
Example
NOTE:73452.1 - Using User
Defined Functions (UDFs)
In FastFormula
 Didn't find what you are looking for? Ask in Community...

Related
 
Product
s
 Oracle E-Business Suite  > Human Capital Management > Payroll > Oracle Payroll > Balances and
Balance Uploads > Balance Retrieval (get_value) -

Keywords
ADJUSTMENT; BALANCE ADJUSTMENT; BALANCE DIMENSION; BALANCE TYPE; BALANCE UPLOAD; BALANCE
VALUES; CREATE BALANCE; DIMENSION; FASTFORMULA; ICPY_BALANCES; ICPY_BALINIT; ICPY_GENRUNBAL;
INITIAL BALANCE UPLOAD; PAYROLL; PAY_DEFINED_BALANCES; RUN BALANCE; RUN RESULTS

 
Error
s
ORA-6571

Back to Top
 
Copyright (c) 2019, Oracle. All rights reserved.   Legal Notices and Terms of Use   Privacy Statement