WikiAdmin: 1 revision imported

2023-07-14T13:00:34Z

1 revision imported

← Older revision

Revision as of 13:00, 14 July 2023

Intra>Chanson: /* System Variables */

2021-04-26T18:35:09Z

System Variables

New page

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

=== '''P'''ayroll '''OP'''erations (POP) ===

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

{| border="1" cellspacing="0" cellpadding="5" align="center"
! 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. <PRE>Current value for [DEF_ID] is [self.cur]</PRE>
|-
| 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==
{| border="1" cellspacing="0" cellpadding="5" align="center"
! 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
|-
|}

 
{| border="1" cellspacing="0" cellpadding="5" align="center"
! VALUE
! DESCRIPTION (TIMECARD)
|-
| "PAY"
| Total of all PAY definition types.
|-
| "HOURS"
| Total of all HOURS definition types.
|-
|}

== Commonly used MACROS ==
 
{| border="1" cellspacing="0" cellpadding="5" align="center"
! 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 '''N'''et '''A'''fter '''T'''axes, 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!!

{| border="1" cellspacing="0" cellpadding="5" align="center"
! 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.
|-
|}

Payroll: Editing formulas - Revision history

WikiAdmin: 1 revision imported

Intra>Chanson: /* System Variables */