The Payroll Run process calculates the gross to net payment for your employees.
This process uses payroll actions to represent each payroll run. It identifies which assignments have payroll actions performed on them - that action is an assignment action of the type payroll.
The results from processing each element for an assignment are the run result values. These individual results are accumulated into balances that summarize gross to net, and in particular the payment balances. Payment balances are taken forward by Pre-Payments, which is the next process in the regular pay cycle.
The first phase of the Payroll Run process is to determine the assignments and elements to be included in the current batch. The user specifies these by selecting an assignment set and element set when initiating the run. The default is All.
The Payroll Run accesses a number of specific entities for processing. It identifies whether they are used for select, update, delete or insert. Where an entity is datetracked, the Payroll Run process also identifies any datetracked information that has changed, and actions it accordingly. For example, an update of a datetracked entity may require an actual insert into the table.
The following list indicates the main entities for processing:
Key: S = Select, U = Update, D = Delete, I = Insert.
| Entity Name | Datetracked? | Processing |
|---|---|---|
| Payroll Action | No | S, U, I |
| Assignment Action | No | S, U, I |
| Element Entry | Yes | S, U |
| Element Entry Value | Yes | S, U |
| Person Latest Balance | No | S, U, I |
| Assignment Latest Balance | No | S, U, I |
| Balance Context | No | S, U, I |
| Action Context | No | S, I |
| Run Result | No | S, U, I |
| Run Result Value | No | S, U, I |
The Payroll Run applies the appropriate processing to each assignment. For a specific payroll run, this is identified by an assignment action. The following 'pseudo code' represents the processing that occurs:
get assignment status();
if assignment status is 'Process' then
load element entries and values ();
load latest balances ();
while(entries to process)
create run results if necessary ();
set up User Defined Context Area ();
/* third party hook */
get processing mode for entry ();
if(we are not skipping) then
look for formula to run ();
if(there is formula to execute) then
execute formula ();
if(error detected) then
handle error ();
end if;
end if;
post run results and feed balances ();
end if ;
end while ;
flush run results and values ();
write / update latest balances ();
end if ;
Element entries hold the entry values that are input to the gross to net calculations. The result of processing each entry value is a run result value. Before processing each assignment, Payroll Run loads all entries for that assignment into memory. This includes any pre-inserted run results and values.
By default, nonrecurring entries are only fetched if they are unprocessed in the current pay period. Recurring entries are always fetched and processed when you submit a payroll run. You must use frequency rules, element skip formulas, or element sets to limit the inclusion of recurring entries.
If you make an additional entry of a recurring element, the Payroll Run processes the additional entry as a nonrecurring entry. (Additional entries are not used by Oracle Payroll in the US.)
The sequence of processing entries for each assignment is determined by the processing priority of the element, and the subpriority order of each entry. When the subpriority is null, entries are ordered by:
processing priority
element_type_id
entry type
Payroll Run checks for Overrides and Replacement entries before calculating normal entries and additional entries for non-US legislations.
If subpriority is specified, the in-memory list is reordered to reflect this. Adjustments and target entries are kept together.
Payroll Run implements the entry processing rules for a terminated assignment.
For the US legislation, this means that if the date earned of Payroll Run is between the actual date of termination and the final process date for an assignment, the assignment is processed only when there exists an unprocessed nonrecurring entry for the assignment.
For non-US legislations, a user can also enter a last standard process date. This means that if the date earned of Payroll Run is between the last standard process date and the final process date for an assignment, the assignment is processed only when there exists an unprocessed nonrecurring entry for the assignment.
An additional entry counts as nonrecurring for termination purposes.
For every entry that is processed there must be a run result; for each entry value there must be a run result value. If these do not already exist, by pre-insertion, then the appropriate run results and values are created in memory and are inserted into the database, ready for Payroll Run to process.
For example, a nonrecurring entry may have pre-inserted run results and values if you have entered the Pay Value.
Pre-inserted values are automatically deleted by a rollback or mark for retry operation, and Payroll Run re-establishes them. However on the rollback of a reversal, nonrecurring pre-inserted values are re-established.
At the same time, Payroll Run uses the current exchange rate for the payroll to perform any currency conversions. This happens if the input and output currency codes of the element are different. You can define an element with any input currency.
If the element contributes to a payment balance for the employee the output currency must be the base currency of the Business Group. Payment balances can be converted into other currencies as part of the PrePayments process linked to payment methods.
Before an entry is processed, Payroll Run sets up the contexts that are needed by FastFormula for Payroll and Element Skip formulas. This may include legislative specific contexts. The values of all the contexts are held in a special data structure, known as the User Defined Context Area (UDCA). The generic contexts that are always created provide additional route information for the formula. These are:
ORIGINAL_ENTRY_ID
ELEMENT_ENTRY_ID
BUSINESS_GROUP_ID
PAYROLL_ACTION_ID
PAYROLL_ID, ASSIGNMENT_ID
ASSIGNMENT_ACTION_ID
DATE_EARNED
ELEMENT_TYPE_ID
TAX_UNIT
JURISDICTION
SOURCE_ID
A special third party interface is called so that the value of legislative specific contexts can be set. This has been used extensively for US legislations.
Element Skip Rules enable you to define specific formula criteria to determine whether an entry is processed or not. A skip rule formula must return a skip_flag value of Y or N.
Where appropriate, a skip formula is fired and any input values are taken from the in memory run result values (to allow for any currency conversion). When looking at the skipping of an adjustment, the formula inputs are taken from the entry values of the normal target entry, not the adjustment entry itself.
There may also be legislative-specific skip rules predefined for specific elements. This additional third party skip hook is called at the same time that the internal function looks for a normal skip formula. This legislative specific skip rule is defined in 'C' code.
Note: Mexican elements do not employ skip rules by default. They must be enabled manually.
Payroll Run uses processing modes to control whether entries of an element are processed. At first, the mode is set to indicate that it should process. Then, depending on the entry type and whether a skip rule has fired, a different mode may be set. This controls the processing of the current entry and (possibly) other entries of the same element. For example, when processing an Override entry, the mode is set to Override. This mode persists throughout the processing of this element, so no other entries are processed.
Payroll Run needs to be able to access and maintain balances and latest balances. In summary, the Payroll Run:
Loads any existing assignment- or person-level latest balances into memory
Checks all loaded balances for expiry, and sets them to zero if they have expired
Creates new in memory latest balances, where required
Adds the appropriate run results to the current value of balances in memory
Writes the new balances to the database (for some balance dimensions types only)
For more information about latest balances, see: Balances in Oracle Payroll.
Any existing assignment-level or person-level latest balances (and any associated balance contexts) are loaded into memory before any entries are processed. The basic data structure for this is a doubly linked list, kept ordered by balance_type_id. The balance values themselves are held and manipulated as Oracle Numbers. The fetch is a union, in this case because the two types of balances are held in separate tables.
Latest balances should expire (that is, return to zero) at a time determined by their dimension. For example, a YTD (Year to Date) balance expires at the end of the year.
All loaded balances are checked for expiry. If they have expired, they are set to zero. The expiry step is entirely separate from the loading step, due to the need to deal with balance context values.
To process expiry checking, the Payroll Run calls Expiry Checking code that is held in a PL/SQL package. To prevent performance from being degraded, the number of accesses required is cut down by making certain assumptions about the different expiry checking levels. The assumptions made are determined by the balance's expiry checking type. See: Expiry Checking Type.
Not all balances are loaded from the database, some have to be created. Once they have been created, they have to be maintained.
For some dimension types, the newly created or updated balances must be written to the tables.
A balance's dimension type determines how it is treated by the payroll run. For example, balances with the dimension type F are fed but not stored, so the Payroll Run creates a balance in memory. For a description of the dimension types, see: Dimension Type.
There are three places in the code where in memory balances are created. One place is for dimension types A, P and F, and two places are for type R.
An in memory balance is created when a formula has just accessed a defined balance with the dimension type A, P or F and which is not already held as an in memory balance. The in memory balance is created using the value accessed by the formula.
An in memory balance with a value of zero is created before the execution of a formula, if the formula accesses a defined balance with the run level balance dimension type (R). (A run level balance must be zero, by definition.)
In memory balances with a value of zero are created before balance feeding time if the code is attempting to feed defined balances with run level dimension types (R).
The corollary of the above rules is that, except for the Run Level dimension type, a latest balances can only be created for a particular defined balance when that balance is accessed by an executed formula.
Next, the appropriate run results are added to the current value of the balance.
A summary of the algorithm that is used is:
For each processed run result, look at the balance feeds, which identify the balance types that are potentially fed by each run result value.
Scan the in memory balances to see if there are any potential feeds.
If there are, perform feed checking.
The feed checking strategy is determined by the feed checking type on the appropriate balance dimension. See: Feed Checking Type.
If the result of feed checking is that the run result should feed the balance, then: balance value = balance value + (result value * scale).
In the case of run result values that might feed run level balances, Payroll Run might need to create them in memory, before feed checking occurs. Since Payroll Run cannot identify which balances might be required at this point, it has to create all those it might need.
In practice, this means it creates balances for each of the run level defined balances that might potentially be fed by the run result being examined.
Note: If the dimension type is R and the feed checking type is set to S, this represents a special case for United States legislation. A different algorithm is used in this case.
The contents of the in memory balances (and any associated contexts) need to be written to the database as appropriate, that is, where the replace flag on the in memory balance is set. Only balances with a dimension type of A or P are written. This occurs after all entries have been processed for the current assignment action.
After all element entries have been processed for the assignment, the in memory balance list is scanned, data is moved to an array buffer and then array inserted or updated on the database.
Payroll Run calls FastFormula to enable it to perform its complex calculations.
Note: Even if a formula has been defined against an element using a formula processing rule, it does not fire if the Pay Value is not null.
The interface used by Payroll Run to access FastFormula is made up of two sections, which are:
The common part of the interface (available to any product)
This sets up pointers from Formula's internal data structures to the data to be input to the formula (contexts and inputs) and output from the formula (formula results).
A special interface
This is designed especially for Payroll Run, and allows access to Formula's database item cache.
Payroll Run goes through the following steps:
Declares that a new formula is executed.
Formula tells the run code what formula contexts, inputs and outputs are required.
The in memory balance chain is scanned.
If the formula might access any of the defined balances held as latest balances, it writes the current value of the balance to the FastFormula database item cache.
Any formula contexts are satisfied. All the values are taken from the User Defined Context Area (UDCA).
Values that are passed to the formula as 'inputs are' variables are satisfied. This is done by looking for a run result value that has an associated Input Value name matching the input variable name.
The outputs that FastFormula has told the run code about are directed to a buffer area.
The third party post formula hook is called. This enables special legislative dependent functions to manipulate the formula results before they are processed by Payroll Run. For instance, it enables certain run results to be suppressed.
The formula results are processed.
Following the execution of a formula, Payroll Run loops through any returned results, processing them as required by the formula result rules. It looks for a formula result rule name that matches the formula result that has been returned. There are several types of result rule, and they are summarized below, from an internal processing point of view.
If the severity level of the message is fatal, it causes an assignment level error. Otherwise, the message is written to the messages table. Note that the length of a message is restricted to the size that can be held in the run result values table (currently 60 characters).
If the Unit Of Measure is Money, the value is rounded as necessary. Then the run result value chain is searched for the entry holding the Pay Value and is updated. The replace flag is set to indicate this.
These two types are grouped together, because they cause very similar processing. During the processing of the current element entry, all indirects are held on a temporary chain, and merged into the main entry chain later.
First of all the temporary chain is searched. If there is no existing entry for the element, a new one is created and added to the chain. Then, in the indirect rule case only, the appropriate entry value is located and updated with the new value. In the Order Indirect case, the subpriority of the indirect entry is set to the formula result value.
Note: If two formula result rules target the same input value, the second result to be processed takes precedence.
Following the processing of all formula results, the chain of indirects is merged into the main element entry chain at the appropriate point. What is appropriate depends on the main processing priority and the subpriority (which can be set using the Order Indirect rule).
Payroll Run prevents the processing priority of an indirect element from being the same as the element that gives rise to the indirect. However, the form continues to disallow this. Same priority indirects was provided specifically for United States legislative requirements.
Same priority indirects can cause problems, however, because they create an endless loop.
Payroll Run calls a PL/SQL procedure to find the appropriate element entry to update. This procedure then performs the date effective update. If this entry happens to exist further down the entry chain, its value is updated to reflect the change.
Payroll Run calls a PL/SQL procedure to find the appropriate element entry to stop. This procedure then performs the date effective delete.
The run result and their associated run result values form the corollary of element entries and element entry values. The entries express eligibility to certain elements, whilst the results and values contain the after effect of processing those entries.
During processing, run results and values are held in memory, hung off the in memory element entry chain. This reflects their close connection in database terms.
Results and values are created internally in one of three ways:
Loaded when entries and entry values are loaded - as pre-inserted results, arising from nonrecurring element entries.
Created by Payroll Run before processing the appropriate element entry if there are any missing results and values.
Created via indirect results.
Payroll Run handles Hot and Cold defaulting while it checks that results and values exist. If results and values do already exist, and are null, Payroll Run attempts to default them.
If currency conversion is required, it is performed at the same time. Internally, it uses Oracle Numbers for the calculation. Following this, if it is processing an input value with a 'Money' Unit of Measure, it performs rounding on the result as necessary.
The process moves the results and values to a special buffer and then writes the run results and values to the database (update or insert). It uses array processing techniques (similar to the technique used by latest balances).
This process is usually referred to as flushing the results and there are two circumstances that may trigger it:
If the process is about to execute a formula that accesses a database item not held in memory. The route for that database item might need to access run results that have been generated so far in Payroll Run itself. This assumption is made because there is no way of finding out for sure.
When all the element entries for the assignment action have been processed, any remaining results and values are flushed.
During processing, Payroll Run has to access attributes of certain entities that represent static definition data. For instance, it may need to know the element name or the balance feeds for a particular input value. Furthermore, the same data typically requires access many times over. If this data were selected from the database every time it was needed, it would cause severe performance degradation.
To resolve this problem, a special static payroll data cache was introduced. All the appropriate data for the entity is loaded into memory the first time it is accessed. From then on, any subsequent accesses to the data can go straight to memory.