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.
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.
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 |
Note: All parameter names without underscores also have an alias with underscores (except CHUNK SHUFFLE).
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.
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.
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.
Parameter Name: CHUNK_SIZE
Parameter Value: 1 - 16000
Default Value: 20
Size of each commit unit for the batch process. As before.
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.
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).
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.
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.
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.
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.
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
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'.
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.
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.
Consider the following:
Start Date -0 7-Dec-09
End Date - 09-Jan -10 (Date Earned)
Paid Date - 15-Jan-10 (Date Paid/Regular Payment date, here both are equal)
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.
When you run the Payroll Run subsequently, with the following values:
Start Date - 27-Dec-09
End Date - 09-Jan-10 (Date Earned)
Paid Date - 15-Jan-10 (Date Paid/Regular Payment date, here both are equal)
Effective Date/Date Paid - 15-Jan-10 falls in the period
Start Date - 10-Jan-10
End Date - 23-Jan-10
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.
When you run the Payroll Run subsequently:
Start Date - 27-Dec-09
End Date - 09-Jan-10 (Date Earned)
Paid Date - 15-Jan-10 (Date Paid/Regular Payment date, here both are equal)
Effective date/Date Paid - 15-Jan-10 falls in the period.
Start Date - 10-Jan-10
End Date - 23-Jan-10
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.
Start Date - 27-Dec-09
End Date - 09-Jan-10 (Date Earned)
Paid Date -15-Jan-10 (Date Paid/Regular Payment date, here both are equal)
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 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.
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.
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.
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.
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
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 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.
Parameter Name: LOGGING
Parameter Value: G, M, P, E, L, B, I, R, F, C, Q, S, T, V, Z
Default Value: No logging
Parameter Name: LOG_AREA
Parameter Value: Function to start logging
Default Value: No default
Parameter Name: LOG_ASSIGN_START
Parameter Value: Assignment to start logging
Default Value: All assignments
Parameter Name: LOG_ASSIGN_END
Parameter Value: Assignment to end logging, including this one
Default Value: All assignments
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.
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.
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'.
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.
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.
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:
Insert new rows (or update existing rows) in the table PAY_ACTION_PARAMETERS.
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.