Payroll: Editing formulas

Payroll Formulas

Changing Baseline Formulas

• Current Payroll formulas are store in support Drive
• Custom formulas may be added to the baseline formulas only when preceeded by a *.
• Any formula that relies on a specifically-named definition that is NOT a baseline definition should be preceeded with a *.
• Baseline definitions should NEVER contain any G/L Accounts or G/L masks.

1. Prior to making a change, create a subdirectory BKUPmmddyyyy and move all .XML files into the backup area.
2. Create a new company in Keystone that will be used exclusively for Payroll Formula development and testing.
3. Login as Admin and change the System Options to activate Payroll.
4. Backup the database.
5. Login as a user, go to the Setup/Utilities menu and import the configuration.
6. Go to Month-End and set up the accounting periods.
7. Go to File Maintenance.
   1. Go to Tax Codes and make sure at least one state tax code is active.
   2. Go to Company Maintenance and set up a company.
8. Make your payroll formula changes.
9. Create several employees and do a test run to make sure all calculations are correct.
10. Use the <CTRL>+ function in Timecard Maintenance to do basic testing, then a Calculate Payroll run for full testing.
11. If there are any self-correcting formulas, do several runs, including runs that will leave employees below, at and above the threshholds.
12. When testing is complete, backup the database.
13. Go to Setup/Utilities and export the configuration.
14. Restore your clean database.
15. Re-import the newly creating configuration files to assure they will load correctly.
16. Notify development and support staff of the change.

Payroll OPerations (POP)

Payroll formulas are based on the following Payroll Operations codes.
Optional parameters and default values are enclosed in square brackets [].

OP	OPERATION	PARAMETERS	DESCRIPTION
1	ADD	[P1] P2 [P3]	Sets P1 [SELF.CUR] = P2 + P3 [0]
2	SUBTRACT	[P1] P2 P3	Sets P1 [SELF.CUR] = P2 - P3
3	MULTIPLY	[P1] P2 P3	Sets P1 [SELF.CUR] = P2 * P3. Use CONTROL_FLAG to specify number of digits after the decimal (0-4).
4	DIVIDE	[P1] P2 P3	Sets P1 [SELF.CUR] = P2 / P3. Use CONTROL_FLAG to specify number of digits after the decimal (0-4). Note that P3 cannot be zero.
5	MOD	[P1] P2 P3	Sets P1 [SELF.CUR] = P2 MOD P3. MODULUS gives you the remainder of a division. Eg: 8 MOD 3 = 2. Note that P3 cannot be zero.
6	CLEAR	[P1]	Sets P1 [SELF.CUR] to zero.
7	ABS	[P1] P2	Sets P1 [SELF.CUR] to the Absolute Value of P2.
8	SET	[P1] P2	Sets P1 [SELF.CUR] = P2.
9	MIN	[P1] P2 P3	Sets P1 [SELF.CUR] to the lower value of P2 or P3.
10	MAX	[P1] P2 P3	Sets P1 [SELF.CUR] to the higher value of P2 or P3.
11	EXIT		Exits processing this definition.
12	WRITE	P1	Sets value of Employee Factor name specified in P1. *** Feature not yet implemented ***
13	WARN		Generates warning in COMMENTS (explanation) field to the WARNINGS tab and on the CALCULATE PAYROLL list. Notes: Setting CONTROL_FLAG to 9 will prevent payroll from being processed. Comments can display Data values by using square Brackets ([ and ]), e.g. Current value for [DEF_ID] is [self.cur]
14	DEBUG	P1	Reports P1's value to a log. If not specified, dumps self.cur and all variables. *** Feature not yet implemented ***
15	IF	P1 [P2] [P3]	P1 = field or variable P2 = logical operator (<, >, =, <>, <=, >=) P3 = field, variable or constant
16	ELSE		Specifies the alternate path for an IF statement.
17	ENDIF		Terminates an IF statement.
18	WARNIF	P1 [P2] [P3]	Similar to IF, if evaluates true, returns the contents of COMMENTS in the log.
19	PROMPTIF	P1 [P2] [P3]	Similar to WARNIF. If evaluates true, opens dialog box with COMMENTS in the prompt, allows user to Continue, Skip Definition, Skip Employee or Abort run. CONTROL_FLAG sets the default selection (0 = continue, 1 = abort) *** Feature no longer implemented ***
20	EXITIF		Similar to IF. If evaluates true, exits processing of this definition for the employee.
21	STOPIF	P1 [P2] [P3]	Similar to IF. If evaluates true, logs COMMENT field value, warns user and exits payroll processing run.
22	PROCESSXREF	[P1] P2 [P3]	Sets P1 [SELF.CUR] = XREF result, P2 = code type ("D", "X", etc.), P3 (optional) = Definition Id
23	SUMDEFTYPE	[P1] P2 [P3]	Sets P1 [SELF.CUR] = SumDefType result, P2 = definition type ("D", "X", etc.), P3 (optional) = Filter
24	CALCTAX	[P1] [P2] [P3]	Sets SELF.CUR = Payroll Tax Library result, P1 = net pay to this point, P2 = tax library param 1 override, P3 = tax library param 2 override
25	TIMECARD	[P1] P2 [P3]	Sets P1 [SELF.CUR] = sum of timecard values, P2 = Timecard type ("HOURS", "PAY", "REIMB", "DAYS"), P3 = Filter
26	MACRO	P1	Calls Macro named in P1. Macro names must have double quotes on each side of the name. Macros may be nested.
27	EVENT	P1 P2 [P3]	Generates an entry in the employee's EVENT history. P1 = Event Type, P2 = Amount, P3 = Trx Type to link to. Writes COMMENTS value to log as well.
28	APBEGIN	P1 P2 P3	Prepares an A/P output record. P1 = Addenda Format, P2 = Vendor ID, P3 = A/P Amount.
29	APFIELD	P1 [P2]	Sets a field to a value in the A/P output record. P1 = Field Name, P2 = Field Value [empty string].
30	APEND	[P1] [P2]	Writes an A/P output record. P1 = Expense G/L Account, P2 = A/P Invoice Description.
31	SETNZ	[P1] P2 [P3]	Sets P1 [SELF.CUR] = P2 if P2 is not zero, otherwise sets P1 = P3 [leaves P1 unchanged]. *** Requires Keystone 3.2.4 or higher ***

Working With Definition Values

Standard Definition Suffixes

• • .cur - current value
  • .MTD - Month-to-date value
  • .QTD - Quarter-to-date value
  • .YTD - Year-to-date value
  • .<factorname> - returns value of the factor.
  • .isovr - returns true/false value based on an override value entered in the Timecard.
  • .ovr - returns the override value from the Timecard.

Notes

• A definition can only update itself or accumulators. It cannot update another definition.
• A definition can read values of any other definition's values by using a .CUR, .MTD, .QTD, .YTD suffix.
• All definitions reference themselves using the self prefix. (Eg: self.cur)
• Definition variables are prefixed by defvar. (Definition Variable). Eg: defvar.calc_rate
• Definition variables in one definition will not carry their value to another definition, but they DO carry into any macros called within the definition.

System Variables

• System variables are prefixed by sysvar. (System Variable). Eg: sysvar.pdsded
• System variables can be referenced by any Definition.
• System variables cannot be changed by a formula.

Common system variables:

• sysvar.pdsded - Deduction Periods
• sysvar.pdstax - Tax Periods
• sysvar.dedweek - Deduction Week
• sysvar.payfreq - Pay Frequency
• sysvar.chkdate - Check Date
• sysvar.pdbegin - Period Begin
• sysvar.pdend - Period End

Def Type Codes

VALUE	DESCRIPTION (SUMDEFTYPE / PROCESSXREF)
"A"	Total of all Direct Deposits
"D"	Total of all Deductions. You may specify "COMPANY_PAID=N" in P3 to exclude company-paid items.
"R"	Get total of all reimbursements (non-taxable income)
"T"	Get total of all taxes. You may specify "COMPANY_PAID=N" in P3 to exclude company-paid items.
"X"	Total of all Tax-Exempt deductions

VALUE	DESCRIPTION (TIMECARD)
"PAY"	Total of all PAY definition types.
"HOURS"	Total of all HOURS definition types.

Commonly used MACROS

MACRO	USAGE
@BALANCE	Validates payment (defvar.payment) against balance (defvar.balance). If a negative payment is made, it adds to the balance and sets a warning level of 2.
@CONVRATE	Converts integer (self.RATE) factor into a decimal defvar.rate. Doesn't allow a value less than 0 or greater than 1.
@CURLIM	Compares self.cur to self.CUR_LIMIT factor (if it exists). If there is no current limit factor, or if it's zero, it leaves self.cur untouched. Otherwise it assures that the self.cur does not exceed the limit.
@GETBAL	Calculates the balance of the current definition, stored in defvar.balance
@GETDDAMT	Calculates the Direct Deposit amount, storing it in defvar.dd_tot
@GETFEDXM	Calculates the amount not subject to Fed Withholding, storing it in defvar.fed_exemptions
@GETFICAXM	Calculates the amount not subject to FICA withholding, storing it in defvar.fica_exemptions
@GETGRS	Calculates the gross pay, storing it in defvar.gross_pay
@GETMCXM	Calculates the amount not subject to Medicare withholding, storing it in defvar.mc_exemptions
@GETNAT	Calculates Net After Taxes, storing it in defvar.net_after_taxes. Note: This number represents Net Pay minus Taxes - deductions are not included in this figure.
@GETNET	Calculates the current net pay, storing it in defvar.net_pay Note: This number is will included all deductions taken at the time of the processing, so can vary in each calculation.
@GETSTXM	Calculates the amount not subject to State Withholding, storing it in defvar.state_exemptions
@MINPAY$	Gets the current net pay (using @GETNET), determines the minimum pay from the self.MIN_PAY factor and calculates the remaining (defvar.remaining) from the self.MIN_PAY factor.
@MINPAY%G	Gets the current gross pay (using @GETGRS) determines the minimum pay from the self.MIN_PAY_% factor and calculates the remaining (defvar.remaining) from the self.MIN_PAY factor. Note: This macro is not used in baseline formulas.
@MTDLIM	Compares self.MTD (including the current deduction) to self.MTD_LIMIT factor (if it exists). If there is no MTD limit factor, or if it's zero, it leaves self.cur untouched. Otherwise it assures that the self.cur does not push the MTD to exceed the limit. Note: This macro is not used in baseline formulas.
@OVRPAY	Override payment logic. Takes the override over self.PAYMENT factor without any limit checking.
@PRMPT>NET	Prompts user for an action if self.cur exceeds the current Net Pay (from @GETNET) Note: This macro is not used in baseline formulas.
@PYCHKLIM	Compares self.cur to self.CHK_LIMIT factor (if used), makes sure self.cur cannot exceed limit. Note: This macro is not used in baseline formulas.
@QTDLIM	Compares self.QTD (including the current deduction) to self.QTD_LIMIT factor (if it exists). If there is no QTD limit factor, or if it's zero, it leaves self.cur untouched. Otherwise it assures that the self.cur does not push the MTD to exceed the limit. Note: This macro is not used in baseline formulas.
@STOP>NET	Stops processing (returns a status code of 9) if self.cur exceeds the current net (from @GETNET). This macro is typically used in troubleshooting, added to formulas during testing and removed before implementation. Note: This macro is not used in baseline formulas.
@WARN>50%	Warns the user if self.cur exceeds 50% of the current net (from @GETNET) This macro is typically used in Child Support and Garnishment calculations.
@WARN>NET	Warns the user if the self.cur exceeds the current net (from @GETNET)
@WEEK	Used to see if a deduction is active in the current week. Zeroes out self.cur if it shouldn't be active. Note: Overrides will always ignore this test!

Definition-dependent formulas

The following formulas have hardcoded Definition IDs in them. Please review all of these formulas carefully before using!!

MACRO	USAGE
*ADVANCE	Used in conjuction with the ADVPAY Income Definition, this formula is for handling payroll advances (loans).
*PERREM	Used in conjunction with the PERHRS Income Definition. This formula is used to track Personal Hours taken and remaining by comparing the Personal Hours balance (as a non-monetary loan) to the Personal Hours being taken. If an employee exceeds his earned Personal Hours, a warning is issued but the payroll will calculate to completion.
*SUTAVALID	This formula is used to validate the SUTA basis numbers. You must edit this formula and change the SUTA definition.
*TAXBEN	Used in conjunction with the TAXBEN Income Definition, this formula increases an employee's taxable gross wages. Income in TAXBEN is included with the gross income when taxes are calculated. This formula is then used in a deduction Definition PRIOR TO ALL OTHER DEDUCTIONS to remove this "income" from an employee's pay so the employee does not actually receive the monies which are treated as taxable income. This is most commonly applied to employees with company cars, company-paid life insurance, etc.
*VACREM	Identical to *PERREM, except uses the VACHRS Income Definition.