Applies to versions: 4.0

Advanced Modifications and Accruals using Expressions

Accruals and Modifications can be configured to calculate with an expression for special rules not covered by the built-in settings and options.

Accruals

The accrual expression should return the amount of the accrual in hours.

The following variables are available to the expression when calculating the accrual amount:

• usersID - The ID of the user benefit accruals are being calculated for
• benefitTypeID - The ID of the benefit type being calculated
• begTimestamp - The timestamp of the beginning of the accrual range
• endTimestamp - The timestamp of the end of the accrual range
• workedhours - The number of hours worked between the start and end of the accrual. Includes benefits/holidays that count toward accruals
• accrualStartDate - The timestamp of the most recent (prior to the end of the accrual range) benefit start date set under the employee's pay history. 
• accrualAnniversary - The timestamp of the anniversary of the most recent (prior to the end of the accrual range) benefit start date set under the employee's pay history.
• intervalCode - The interval type, i.e. one of the following: week, month, year, semimonth, quarter, never, day
• intervalCount - The number of interval. Usually 1, but for accruals that happen periodically, the number of the period.  i.e. For accruals every two weeks: 2. For accruals every 10 days: 10. For accruals every 4 months: 4, etc.

Example 1:

An accrual policy grants 50 hours a year on Jan 1st each year.  And, for employees who where hired between Jan and June, an additional 8 hours is granted on Jul 1st.

• This is a special rule because the amount accrued on Jul 1st is different than on Jan 1st and depends on the hire date of the employee.
• To accommodate this, accruals would be set to run twice a year
• The accrual amount would be set to Expression
• The expression would be
  =if(utcdate("m",[begTimestamp])=1,50, /* this gives 50 hours if it is the Jan accrual */
  if(substr(employeeInfo([usersID], 'payrollSyncStartDate'),6,2)<7,8,0)) /* this looks at the month of the start date and, if it's less than 7 (Jan->Jun) then give 8 hours, otherwise none */

Example 2:

An accrual policy grants employees .025 hour of vacation per hour worked (i.e. 1 hour for 40 hours), but the total amount for the calendar year, starting Jan 1st, is limited to 32 hours earned (no limit on how much is available).

• This is a special rule because the amount accrued has an earnings limit for the year.
• To accommodate this, accruals could be set to run every day, week, month, etc.
• The accrual amount would be set to Expression:
• ==hourlimit=32
  ==bentype='vacation'
  ==rate=.025
  ==earned=[workedhours]*[rate]
  ==startofyear=strtoutctime(utcdate("Y",[endTimestamp])."-01-01 12:00:00 AM")
  ==maxearned=[hourlimit]-(getBenefitAccrued([usersID], [startofyear], [endTimestamp], [bentype])/3600)
  =if([earned]>[maxearned],[maxearned],[earned])

Example 2A:

An accrual policy grants employees .05 hour of sick per hour worked (i.e. 2 hours for 40 hours), but the total amount for a year, starting July 1st at 8am, is limited to 56 hours earned (no limit on how much is available).

• This is a special rule because the amount accrued has an earnings limit for the year.
• To accommodate this, accruals could be set to run every day, week, month, etc.
• The accrual amount would be set to Expression:
• ==hourlimit=56
  ==bentype='sick'
  ==rate=.05
  ==earned=[workedhours]*[rate]
  ==benefityear="07-01 8:00:00 AM"
  ==startofyear=strtoutctime(utcdate("Y",[endTimestamp])."-".[benefityear])
  ==startofyear=strtoutctime(utcdate("Y",[endTimestamp]-if([startofyear]>[endTimestamp],365*86400,0))."-".[benefityear])
  ==maxearned=[hourlimit]-(getBenefitAccrued([usersID], [startofyear], [endTimestamp], [bentype])/3600)
  =if([earned]>[maxearned],[maxearned],[earned])

Example 3:

An accrual policy grants employees 16 hours of vacation per month worked, but limited to 80 hours per year every year from their hire date anniversary.

• This is a special rule because the amount accrued has an earnings limit for the year, and the year is different for each employee.
• To accommodate this, accruals could be set to run every month with an expression:
• ==hourlimit=80
  ==rate=16
  ==alreadyAccruedThisYear=(getBenefitAccrued([usersID], [accrualAnniversary], [endTimestamp], 'vacation')/3600)
  =if([workedhours]>0 && [alreadyAccruedThisYear]<[hourlimit],[rate],0)

Example 4:

An accrual policy grants employees 30 hours of vacation per year until 2024, then changes to 40 hours of vacation per year.

• This is a special rule because the amount accrued changes after a certain year
• To accommodate this, accruals could be set to run every year with an expression:
• =if(utcdate("Y",[begTimestamp])<2024,30,40)

Modifications

The following variables are available to the expression when calculating the modification amount:

• usersID - The ID of the user benefit accruals are being calculated for
• benefitTypeID - The ID of the benefit type being calculated
• begTimestamp - The timestamp of the beginning of the accrual range
• endTimestamp - The timestamp of the end of the accrual range
• workedhours - The number of hours worked between the start and end of the accrual. Includes benefits/holidays that count toward accruals

Special Rules Expressions (Benefit Use Rules)

The use (and request) of benefits can also be controlled with special rules set by expression. This works as follows:

• If the expression evaluates to nothing, the benefit use is allowed.
• If the expression evaluates to a message without the word "error" in it, it will be shown as a warning. The employee will have the option to continue anyway.
• If the expression evaluates to a message that contains the word "error" it will be shown as an error.  The error must be corrected before continuing.

The following variables are available to the expression when checking the rule:

• [user] - Information about the employee to which the benefit applies. See this article for the user variables table.
• [editor] - Information about the employee administrator who is making the change. See this article for the user variables table. Note that instead of, for example, [user][usersID], it is [editor][usersID] in this case.
• [subclass] - The name of the benefit subclass (if one is selected) or an empty string (if one is not selected)
• [benefitStart] - The UNIX timestamp of the start date and time of the benefit
• [benefitDuration] - The amount of benefit time (in seconds)
• [job] - Information about the job that is associated with the benefit usage/request. See the [user][defaultJob] part of the user variables table here for all of the variables available for a job. Note that instead of, for example, [user][defaultJob][jobID], it is [job][jobID] in this case.
• [note]  - The note connected with the benefit request or use
• [mode] - Either "use" or "request" to indicate if this is a benefit use or just a request

Examples:

• Warn on benefit requests (but not benefit usages) more than 14 days into the future, prevent if more than 30 days into the future.
  • =if([benefitStart]>time()+30*86400 && [mode]="request", "Error: Can not request benefits more than 30 days in the future.", if([benefitStart]>time()+14*86400 && [mode]="request", "Warning: You are requesting benefits more than 2 weeks into the future.", ""))
• Warn on benefit requests or usages more than 10 days in the past.
  • =if([benefitStart]<time()-10*86400, "Warning: You can not request/use benefit time further than 10 days ago.", "")
• Don't allow benefit use or requests between November 1st and November 15th unless employee is in the "Administration" organizational unit.
  • =if(utcdate("F", [benefitStart])="November" && utcdate("j", [benefitStart])>=1 && utcdate("j", [benefitStart])<=15 && [user][orgUnit][name]!="Administration", "Error: You are not an administrator and you are not allowed to use/request benefit time between November 1st and November 15th.", "")
• Only allow benefit use or requests between July 1st and July 31st each year.
  • =if(utcdate("F", [benefitStart])="July", "", "Error: You can only use/request benefit time between July 1st and July 31st, inclusive.")
• Don't allow any requests for more than 8 hours of benefits at once.
  • =if([mode]="request" && [benefitDuration]>8*3600, "Error: A single benefit request can not be longer than 8 hours.", "")