Payroll Action Parameters

Payroll Action Parameters

Payroll action parameters are system-level parameters that control aspects of the Oracle Payroll batch processes. It is important to recognize that the effects of setting values for specific parameters may be system wide. The text indicates where parameters are related to specific processes. For some parameters you should also understand the concept of array processing and how this affects performance.

Action Parameter Values

Predefined values for each parameter are supplied with the system, but you can override these values as part of your initial implementation and for performance tuning.

Action parameter values are specified by inserting the appropriate rows into the following table: PAY_ACTION_PARAMETERS, which has two columns:

PARAMETER_NAME NOT NULL VARCHAR2(30)

PARAMETER_VALUE NOT NULL VARCHAR2(80)

The payroll batch processes read values from this table on startup, or provide appropriate defaults, if specific parameter values are not specified.

Summary of Action Parameters

The following list shows user enterable action parameters and values with any predefined default value.

Note: Case is significant for these parameters.

Parameter

Value

Default

ADD_MAG_REP_FILES

1 or more

4

BAL BUFFER SIZE

1 or more

30

CHUNK SHUFFLE

Y or N

N

CHUNK_SIZE

1 - 16000

20

EE BUFFER SIZE

1 or more

40

LOG_AREA

See later

LOG_ASSIGN_END

See later

LOG_ASSIGN_START

See later

LOGGING

See later

MAX_ERRORS_ALLOWED

1 or more

CHUNK_SIZE or 20 (if no chunk size)

MAX_SINGLE_UNDO

1 or more

50

RR BUFFER SIZE

1 or more

20

RRV BUFFER SIZE

1 or more

30

COST BUFFER

1 or more

20

THREADS

1 or more

1

TRACE

Y or N

N

USER_MESSAGING

Y or N

N

RUN_XDO

Y or N

Y

PRINT_FILES

Y or N

Y

FREQ_RULE_WHOLE_PERIOD

Y

N

REV_LAT_BAL

Y or N

N

PROC_REG_SAL_INACT

Y or N

Y

Note: All parameter names without underscores also have an alias with underscores (except CHUNK SHUFFLE).

Parallel Processing Parameters

THREADS

Parameter Name: THREADS

Parameter Value: 1 or more

Default Value:1

Oracle Payroll is designed to take advantage of multiprocessor machines. This means that you can improve performance of your batch processes by splitting the processing into a number of `threads'. These threads, or sub-processes, will run in parallel.

When you submit a batch process to a concurrent manager the THREADS parameter determines the total number of sub-processes that will run under the concurrent manager. The master process will submit (THREADS - 1) sub-processes.

Set this parameter to the value that provides optimal performance on your server. The default value, 1, is set for a single processor machine. Benchmark tests on multiprocessor machines show that the optimal value is around two processes per processor. So, for example, if the server has 6 processors, you should set the initial value to 12 and test the impact on performance of variations on this value.

Important:
The concurrent manager must be defined to allow the required number of sub-processes to run in parallel. This is a task for your Applications System Administrator.

CHUNK_SIZE

Parameter Name: CHUNK_SIZE

Parameter Value: 1 - 16000

Default Value: 20

Size of each commit unit for the batch process. This parameter determines the number of assignment actions that are inserted during the initial phase of processing and the number of assignment actions that are processed at one time during the main processing phase.

Note: This does not apply to the Cheque Writer/Check Writer, Magnetic Tape or RetroPay processes.

During the initial phase of processing this parameter defines the array size for insert. Large chunk size values are not desirable and the default value has been set as a result of benchmark tests.

Each thread processes one chunk at a time.

Array Select, Update and Insert Buffer Size Parameters

The following parameters control the buffer size used for 'in-memory' array processing. The value determines the number of rows the buffer can hold.

Note: These parameters apply to the Payroll Run process only.

When you set values for these parameters you should note that there is a trade-off between the array size, performance and memory requirements. In general, the greater the number of rows fetched, updated or inserted at one time, the better the performance. However, this advantage declines at around 20.

Therefore, the improvement between values 1 and 20 is large, while between 20 and 100 it is small. Note also that a higher value means greater memory usage. For this reason, it is unlikely that you will gain any advantage from altering the default values.

CHUNK_SIZE

Parameter Name:CHUNK_SIZE

Parameter Value: 1 - 16000

Default Value: 20

Size of each commit unit for the batch process. As before.

RR BUFFER SIZE

Parameter Name: RR BUFFER SIZE

Parameter Value: 1 or more

Default Value: 20

Size of the Run Result buffer used for array inserts and updates: one row per Run Result.

RRV BUFFER SIZE

Parameter Name: RRV BUFFER SIZE

Parameter Value: 1 or more

Default Value: 30

Size of the Run Result Value buffer used for array inserts and updates: one row per Run Result Value. Typically this will be set to (RR BUFFER SIZE * 1.5).

BAL BUFFER SIZE

Parameter Name: BAL BUFFER SIZE

Parameter Value: 1 or more

Default Value: 30

Size of the Latest Balance buffer used for array inserts and updates: 1 row per Latest Balance.

EE BUFFER SIZE

Parameter Name: EE BUFFER SIZE

Parameter Value: 1 or more

Default Value: 40

Size of the buffer used in the initial array selects of Element Entries, Element Entry Values, Run Results and Run Result Values per assignment.

Costing Specific Parameters

COST BUFFER SIZE

Parameter Name: COST BUFFER SIZE

Parameter Value: 1 or more

Default Value: 20

Size of the buffer used in the array inserts and selects within the Costing process.

Magnetic Tape Specific Parameters

ADD_MAG_REP_FILES

Parameter Name: ADD_MAG_REP_FILES

Parameter Value: 1 or more

Default Value: 4

The maximum number of additional audit or report files the magnetic tape process can produce.

Error Reporting Parameters

In every pay cycle you would expect some errors to occur in processing individual assignments, especially in the Payroll Run. These errors are usually caused by incorrect or missing data in the employee record. For practical reasons, you would not want the entire run to fail on a single assignment failure. However, if many assignments generate error conditions one after the other, this will usually indicate a serious problem, and you will want to stop the entire process to investigate the cause. For processes that support assignment level errors you can use the MAX_ERRORS_ALLOWED parameter to control the point at which you want to stop the entire process to investigate these errors.

The processes that use this feature are:

Payroll Run

Pre-Payments

Costing

Rollback

MAX_ERRORS_ALLOWED

Parameter Name: MAX_ERRORS_ALLOWED

Parameter Value: 1 or more

Default Value: CHUNK_SIZE or 20 (if no chunk size)

The number of consecutive actions that may have an error before the entire process is given a status of 'Error'.

Frequency Rule Specific Parameters

FREQ_RULE _WHOLE_PERIOD

Parameter Name: FREQ_RULE_WHOLE_PERIOD

Parameter Value: Y

Default Value: N

You may find that a payroll is processed twice in the same month even though you have specified a monthly frequency rule. Duplicate processing occurs because Oracle Payroll associates the first date of the month with the first payroll period. In most cases this is a correct association. However, if you run an offset bi-weekly payroll, you may find that your payroll is processed twice in the same month because an additional start of month day is visible to the frequency rule.

Your System Administrator can enforce the monthly frequency rule by setting the FREQ_RULE_WHOLE_PERIOD parameter to Y.

However, once this parameter has been set to Y, we strongly recommend that you leave it unchanged. Any subsequent attempt to update or delete this parameter setting could introduce unexpected results.

Example for Frequency Rule parameters

The action parameter FREQ_RULE_WHOLE_PERIOD controls the frequency rule so that the period number is calculated either for Effective Date or for Date Earned rule only in the payroll run, based on the action parameter value of FREQ_RULE_WHOLE_PERIOD.

Oracle Payroll enables you to process elements with Date Earned and Effective Date frequency in the same payroll process to control the calculation of the period_number based on the frequency rule_date_code entered in the Element definition window along with Action Parameter value FREQ_RULE_WHOLE_PERIOD instead of only with action parameter value FREQ_RULE_WHOLE_PERIOD.

Setting up the parameter FREQ_RULE_WHOLE_PERIOD value impacts the calculation method of period number for frequency rule Effective Date and not Date Earned or Regular Payment. You are advised to setup to suit your requirement so that the element is processed accordingly.

Oracle Payroll processes elements based on the frequency period defined. You can define the frequency rules by selecting one of the following options:

Date Earned - Based on the end date of the pay period

Effective Date - Based on the effective date of the payroll process. This is the date that you enter in the Date Paid of the Quick Pay window.

Date Paid - Regular Payment Date in the per_time_periods table. This is calculated based on the Offset mentioned while creating the payroll.

The following examples illustrate how the application works when you use the different values for the Frequency Rule parameter:

FREQ_RULE set as Date Earned

If you set the frequency rule as Date Earned, the end date of period on which the date earned falls is considered for calculating the period number.

Example :Consider an element A with the frequency rule date as 'E' (Date Earned) and Processing Period as 1. The Bi-Weekly Offset is 7:

Start Date - 13-Dec-09

End Date - 26-Dec-09 (Date Earned, end of pay period)

Date Paid - 01-Jan -10(Date Paid given in Quick Pay)

Paid Date- 02-Jan-10 (Regular Payment Date according to given offset)

The Date Earned date (26-Dec-09) falls in December. You can check the number of period falls from time_periods. Here the period number is '2', so the element will not be processed.

The Date Earned date (09-Jan-10) falls in January. You can check that the number of period end date falls in the month from time_periods. Here the period number '1', so the element is processed

FREQ_RULE set as Effective Date

Scenario 1: When parameter FREQ_RULE_WHOLE_PERIOD value is set to N

If you set the frequency rule as Effective Date and when the parameter FREQ_RULE_WHOLE_PERIOD value is set to N, the end date of period on which date paid falls (entered on the Quick Pay window) is considered for calculating the period number.

Consider an element A with the frequency rule dates - 'F' (Effective Date) and processing period 1. The Bi-Weekly Offset is 7.

Run the first payroll run with the following values:

Start Date - 13-Dec-09

End Date - 26-Dec-09 (Date Earned, end of pay period)

Date Paid - 01-Jan-10 (Date Paid entered in Quick Pay)

Paid Date- 02-Jan-10 (Regular Payment Date according to the given offset)

Effective Date/Date Paid - 01-Jan-10 falls in the period.

Start Date - 27-Dec-09

End Date - 09-Jan-10

The period end 09-Jan-10 falls in January. You can check the period number from where the end date falls in the month from the time_periods. Here the period number is 1, so the application processes the element.

The period end date 23-Jan-10 falls in January. You check the number of period number from where the end date that falls in the month from the time_periods. Here the period number is 2, so the element will not be processed.

Scenario 2 : When parameter FREQ_RULE_WHOLE_PERIOD value is set to Y

If you set the parameter FREQ_RULE_WHOLE_PERIOD value as 'Y', the start date of period on which date paid (entered in the Quick Pay) falls is considered for calculating the period number.

Example : Consider the element A with frequency rule date as F (Effective Date) and processing period selected as 1. The Bi-Weekly Offset is 7.

When you run the first Payroll Run with the following values:

Start Date - 13-Dec-09

End Date - 26-Dec-09 (Date Earned, end of pay period)

Date Paid - 01-Jan-10 (date paid given in Quick Pay)

Paid Date - 02-Jan-10 (Regular Payment Date according to the offset)

Effective Date/Date Paid - 01-Jan-10 falls in the period

Start Date - 27-Dec-09

End Date - 09-Jan-10

The start date of the period falls in December. You check the period number from where the period start date in December from time_periods and end of the period (where the effective date falls). Here, the period Number is 2, so the element is skipped and not processed.

The start date of the period falls in January. You check the period number from where the period start date falls in January from time_periods. Here the period number is 1, so the element will be processed.

The end date of period on which Date Paid (entered within the Quick Pay) is considered for calculating the period number.

FREQ_RULE as Regular Payment Date

If the frequency rule is set as R (Regular Payment date) by adding new lookup code 'R' to lookup type PAY_FRULE_DATES or legislation specific lookup PAY_US_FRULE_DATES. The count of regular payment date (regular_payment_date) that falls in the month is considered for calculating the period number.

Regular Payment Date is 02-JAN-2010, the count of the regular payment date falls in January and is 1, and so the element is processed.

The Regular Payment Date is 02-Jan-2010 and the count of the regular payment date in January is 2 and so the element is not processed.

If the frequency rule is based on Regular Payment Date, you must record the same in Element definition window by setting up new lookup code 'R' to lookup type PAY_FRULE_DATES or legislation specific lookup PAY_US_FRULE_DATES .(If not already present).

Note: You must not use the parameter value FREQ_RULE_WHOLE_PERIOD = 'R' for the regular payment calculation.

Rollback Specific Parameters

Rollback of specific payroll processes can be executed in two ways. A batch process can be submitted from the Submit Requests window. Alternatively, you can roll back a specific process by deleting it from the Payroll Process Results window or the Assignment Process Results window. When you roll back from a window this parameter controls the commit unit size.

MAX_SINGLE_UNDO

Parameter Name: MAX_SINGLE_UNDO

Parameter Value: 1 or more

Default Value: 50

The maximum number of assignment actions that can be rolled back in a single commit unit when rollback is executed from a form. Although you can change the default limit, you would usually use the Rollback process from the SRS screen if it is likely to be breached.

Reversal Specific Parameters

REV_LAT_BAL

Parameter Name: REV_LAT_BAL

Parameter Value: Y/N

Default Value: N

If you set the REV_LAT_BAL parameter to Y, you can maintain the latest balances for each reversal that you run. By default, the Reversal process always removes latest balances. This parameter enables you to maintain the latest balances and reduce your processing time.

However, be aware that maintaining latest balances also introduces a performance overhead. The relative advantage of maintaining latest balances depends on the number and frequency of reversals that you normally run.

Payroll Archive/Payslip Archive

The parameter enables the archiver to obtain the data for the element to be archived for an employee's assignment from the pay_run_results/pay_run_balances rather than a previous archive.

INIT_PAY_ARCHIVE

Use the parameter if there is data corruption on your instance or a code issue that prevents the archive of non-recurring elements. The element is not picked up in subsequent archives until the application processes the element again. Use this parameter to resolve any kind of data corruption in the archiver that you corrected in the live tables. Oracle recommends you use the date parameter as a best practice.

Parameter Name: INIT_PAY_ARCHIVE

Parameter Value: Y/N

Y - always check run result/balance

Default Value: N

Parameter Value: Date in YYYY/MM/DD format

Get data from run results and run balances only if the archiver is run with an End date as a parameter value

Payroll Process Logging

During installation and testing of your Oracle Payroll system you may need to turn on the detailed logging options provided with the product. Use the LOGGING parameter to provide a large volume of detailed information that is useful for investigating problems.

Detailed logging options should only be switched on when you need to investigate problems that are not easily identified in other ways. The logging activities will have an impact on the overall performance of the process you are logging. Usually, this feature is needed during your initial implementation and testing before you go live. In normal operation you should switch off detailed logging.

Important:
If you need to contact Oracle Support for assistance in identifying or resolving problems in running your payroll processes, you should prepare your log file first. Define the Logging Category, Area and range of Assignments and then resubmit the problem process.

Logging Categories

Logging categories define the type of information included in the log. This lets you focus attention on specific areas that you consider may be causing a problem. You can set any number of these by specifying multiple values:

G General (no specific category) logging information

Output messages from the PY_LOG macro for general information. This option does not sort the output and you should normally choose a list of specific categories.

M Entry or exit routing information

Output information to show when any function is entered and exited, with messages such as 'In: pyippee', 'Out : pyippee'. The information is indented to show the call level, and can be used to trace the path taken through the code at function call level. Often, this would be useful when attempting to track down a problem such as a core dump.

P Performance information

Output information to show the number of times certain operations take place at the assignment and run levels and why the operation took place. For example, balance buffer array writes.

E Element entries information

Output information to show the state of the in-memory element entry structure, after the entries for an assignment have been fetched, and when any item of the structure changes; for example, addition of indirects or updates. This also shows the processing of the entry.

L Balance fetching information

Output information to show the latest balance fetch and subsequent expiry stage.

B Balance maintenance information

Output information to show the creation and maintenance of in-memory balances

I Balance output information

Output information to show details of values written to the database from the balance buffers.

R Run results information

Output information to show details of run results and run result values written to the database from the Run Results or Values buffer.

F Formula information

Output information to show details of formula execution. This includes formula contexts, inputs and outputs.

C C cache structures information.

Output information to show details of the payroll cache structures and changes to the entries within the structure.

Q C cache query information

Output information to show the queries being performed on the payroll cache structures.

S C Cache ending status information

Output information to show the state of the payroll cache before the process exits, whether ending with success or error. Since much of the logging information includes id values, this can be used to give a cross reference where access to the local database is not possible.

T PL/SQL Detail

Detail of PL/SQL debug information for the process. You can only use the T parameter if you also specify the Z parameter. Include the T parameter when debugging any process that uses PL/SQL intensively, for example, PrePayments.

V Vertex (available to US and Canadian customers only)

Output information to show the values being passed in and out of the Vertex tax engine.

This option also creates a separate file in the Out directory showing the internal settings of the engine.

Z PL/SQL Output

Output information to show the PL/SQL debug information for a process. If you specify the Z parameter, you can also specify the T parameter to show PL/SQL detail. Include the Z parameter when debugging any process that uses PL/SQL intensively, for example, PrePayments.

Logging Parameters

LOGGING

Parameter Name: LOGGING

Parameter Value: G, M, P, E, L, B, I, R, F, C, Q, S, T, V, Z

Default Value: No logging

LOG_AREA

Parameter Name:LOG_AREA

Parameter Value: Function to start logging

Default Value: No default

LOG_ASSIGN_START

Parameter Name: LOG_ASSIGN_START

Parameter Value: Assignment to start logging

Default Value: All assignments

LOG_ASSIGN_END

Parameter Name: LOG_ASSIGN_END

Parameter Value: Assignment to end logging, including this one

Default Value: All assignments

Output Log File

When you enable the logging option the output is automatically included in the log file created by the concurrent manager. You can review or print the contents of this log file.

Except for the General category, the log file will contain information in a concise format using id values. This keeps the size of the log file to a minimum while providing all the technical detail you need.

To help you understand the output for each logging category, other than 'G' and 'M', the log file contains a header indicating the exact format.

Miscellaneous Parameters

USER_MESSAGING

Parameter Name: USER_MESSAGING

Parameter Value: Y/N

Default Value: N

Set this to parameter to 'Y' to enable detailed logging of user readable information to the pay_message_lines table. This information includes details about the elements and overrides that are processed during the Payroll Run.

Note: This information is useful when you are investigating problems, but you may find that it is too detailed for normal working.

TRACE

Parameter Name: TRACE

Parameter Value: Y/N

Default Value: N

Set this parameter to 'Y' to enable the database trace facility. Oracle trace files will be generated and saved in the standard output directory for your platform.

Warning:
Use the trace facility only to help with the investigation of problems. Setting the value to `Y' causes a significant deterioration in database performance. If you experience a significant problem with the performance of your payroll processes, check that you have reset this parameter to the default value - 'N'.

RUN_XDO

Parameter Name: RUN_XDO

Parameter value: Y/N

Default value: Y

Set this parameter to 'Y' to run XML Publisher for Report Generation.

This parameter is responsible for launching the XML Publisher for Report Generation and using XML Publisher API calls to produce the output.

PRINT_FILES

Parameter Name: PRINT_FILES

Parameter value: Y/N

Default value: Y

Set this parameter to 'Y' to use concurrent request Payroll File Reporter to publish the output.

This parameter is responsible for launching the Payroll File Reporter sub request and to view the completed PDF report. You can choose the Payroll File Report and click View Output. Payroll File Reporter is used to publish the generated report/output.

The default behavior of Oracle HRMS is not to process the Regular Salary and Regular Wages elements when the assignment status of an employee is not Active (System Status is not set to 'Active Assignment). If the pay action parameter value is set to Y, then the application overrides the default behavior and processes the Regular Salary and Regular Wages elements as normal during payroll run as long as the Payroll Status is set to 'Process.

For information about Regular Salary and Regular Wages elements, refer to the Oracle HRMS Compensation and Benefits Management Guide

System Management of QuickPay Processing

When users initiate a QuickPay run or a QuickPay prepayments process, the screen freezes until the process finishes. QuickPay is set up to manage any cases in which the concurrent manager fails to start the process within a specified time period, or starts it but fails to complete it within the specified period. This situation can sometimes arise when, for example, many high priority processes hit the concurrent manager at the same time.

The system's management of the screen freeze occurring when a user initiates a QuickPay process involves:

Checking the concurrent manager every few seconds for the process completion.

Unfreezing the screen and sending an error message to the user when the process has not completed within a maximum wait time.

The error message includes the AOL concurrent request ID of the process. The user must requery the process to see its current status.

System administrators can improve the speed of QuickPay processing at their installation by:

Changing the default for the interval at which checks for process completion occur.

By default, the check of the concurrent manager occurs at 2 second intervals. The parameter row QUICKPAY_INTERVAL_WAIT_SEC in the table PAY_ACTION_PARAMETERS sets this default.

Changing the default for the maximum wait time.

The maximum wait time allowed for a QuickPay process to complete defaults to 300 seconds (5 minutes), after which the system issues an error message. The parameter row QUICKPAY_MAX_WAIT_SEC in the PAY_ACTION_PARAMETERS table sets this default.

Defining a new concurrent manager exclusively for the QuickPay run and prepayments processes.

To change the defaults for the interval at which checks occur or for the maximum wait time:

Notice that QUICKPAY_INTERVAL_WAIT_SEC and QUICKPAY_MAX_WAIT_SEC are codes for the Lookup type ACTION_PARAMETER_TYPE.

To define a new concurrent manager exclusively for the two QuickPay processes:

Exclude the two QuickPay processes from the specialization rules for the standard concurrent manager.

Include them in the specialization rules for the new QuickPay concurrent manager to be fewer than those of the standard concurrent manager. Doing so reduce the time it takes to start requests for the QuickPay processes.