Kuali HR System Administration Guide


Table of Contents

1. Basic Setup
Introduction
Institution
Location
Location Role Member
Group Key
Organization
Department
Department Role Member
Department Affiliation
Work Area
Work Area Task
Work Area Role Members
Set up Calendars for leave and pay periods
Calendar
Calendar Entries
Earn Codes with Earn Code Security
Earn Code
Earn Code Security
Earn Code Group
Earn Code Group Definition
Pay Type
Core Position Management
Salary Group
Pay Grade
Position
Job
Assignment
Assignment Accounts
2. Timekeeping Configuration
Grace Period Rule
Weekly Overtime Rule
Daily Overtime Rule
Shift Differential Rule
Time Collection Rule
Clock Location Rule
Department Lunch Deduction Rule
3. Leave Management Configuration
Leave Management Configuration
Leave Plan
Accrual Category Configuration
Accrual Category Rule
System Scheduled Time Off
Leave Blocks and Earn Codes
Leave Block Types
Leave Earn Codes
4. Leave Management Administrative Tools
Balance Transfer
Employee Override
Leave Adjustment
Leave Donation
Leave Payout
5. Batch Jobs
Basic Setup
Available Batch Jobs
Calendar Entry Jobs
Leave Plan Jobs
Cron Expression Jobs
Quartz Implementation
KPME Quartz Job and Trigger Example
Spring Configuration

List of Tables

1.1. Institution Fields
1.2. Location Fields
1.3. Location Role Member Fields
1.4. Group Key Fields
1.5. Organization Fields
1.6. Department Fields
1.7. Department Role Member Fields
1.8. Department Affiliation Fields
1.9. Work Area Fields
1.10. Work Area Task Fields
1.11. Work Area Principal Role Member Fields
1.12. Work Area Position Role Member Fields
1.13. Calendar Fields
1.14. Calendar Entries Fields
1.15. Earn Code Fields
1.16. Earn Code Security Fields
1.17. Earn Code Group Fields
1.18. Earn Code Group Fields
1.19. Pay Type Fields
1.20. Salary Group Fields
1.21. Pay Grade Fields
1.22. Position Base Fields
1.23. Job Fields
1.24. Assignment Fields
2.1. Grace period rule
2.2. Weekly Overtime Rule Document fields
2.3. Daily Overtime Rule Document fields
2.4. Shift Differential Rule
2.5. Time Collection Rule Document Fields
2.6. Clock Location Rule Document Fields
2.7. Department Lunch Deduction Rule Document fields
3.1. Leave Plan Fields
3.2. Accrual Category Fields
3.3. Accrual Category Rule Fields for configuring Accrual Rate
3.4. Accrual Category Rule Fields for configuring Max Balances
3.5. Accrual Category Rule Fields for configuring Transfer at Max Balances
3.6. Accrual Category Rule Fields for configuring Transfer at Max Balances
3.7. SSTO Fields :
4.1. Balance Transfer fields :
4.2. Employee Override fields :
4.3. Leave Adjustment fields :
4.4. Leave Donation fields :
4.5. Leave Payout fields :
5.1. Batch Job Configuration Parameters
5.2. Calendar Entry Job Dates and Times

Chapter 1. Basic Setup

Introduction

This chapter will cover the administration of CORE KHR business objects, located in the HR/Payroll link grouping found on the left hand side of the page. We will also need to create an object linked in the Administrative grouping located at the bottom left of the maintenance portal.

In-depth Leave Management and Timekeeping administration are covered in subsequent guides, however, will require understanding of concepts and objects presented in this chapter. This chapter also makes a few assumptions on readers knowledge and existence of basic rice objects and components. For instance, Person Maintenance, documented within the Kauli Identity Management guide.

With the application server running, proceed to the KHR Maintenance Portal:

The KHR Maintenance Portal

Institution

Institution is required by Group Key which is required for a number of HR/Payroll related objects.

Table 1.1. Institution Fields

FieldDescription
Effective DateThe date the institution record takes effect
Institution CodeAlpha-numeric code used to identify the institution. Ex: ISU
DescriptionOptional long description of Institution
ActiveIndicator specifying whether the institution will turned active or inactive on the given effective date.

Location

Location, like Institution, is also required by Group Key. Location can be used to define multiple locations associated with an institution.

Table 1.2. Location Fields

FieldDescription
Effective DateThe date this Location will go into effect. This date should be on or before any role members defined for the location.
LocationAlpha-numeric code used to identify the location. Ex: IA
TimezoneThe timezone in which this location resides.
DescriptionLong description of Location
ActiveIndicator used to activate or deactivate the location.

Location Role Member

This Role Member consists of a principal paired with a role. Depending on the role, the principal may be given elevated permissions not otherwise available to them, such as availability of specific earn codes, or the ability to view calendar documents across all departments the location encompasses.

Table 1.3. Location Role Member Fields

FieldDescription
Effective DateThis date should be on or after the effective date of the Location object to which it is attached.
Principal IdThis field selects the person to receive the role for the location
Principal NameRead-only field populated from Principal Id
Role NameSpecifies which role to give to the principal for the location. Roles are divided between "Time Location" and "Leave Location" and further divided by Administrator and View Only Permissions
Expiration DateOptional field to specify a date for which the role is to be removed from the princpal. If left blank, the role will not automatically expire.

Group Key

Group Key defines combination of location, campus and institution and used by several core objects such as Department, Position, Job, etc... Large KHR implementations can use Group Key to define data by their unique institutions/campuses/locations combinations. Group Key is used through out KHR to define different rules and business logic applied throughout the system.

Table 1.4. Group Key Fields

FieldDescription
Effective DateThe date the Group Key record will go into effect.
Group KeyAn alpha-numeric code used to identify the Group Key
LocationThe Location to associate with the Group Key
DescriptionLong description of Group Key
Campus CodeThe Campus to associate with the Group Key
InsititionThe Insitition to associate with the Group Key
ActiveIndicator for activity

Organization

Organization is used to define organizational divisions within an institution.

Table 1.5. Organization Fields

FieldDescription
ChartField to specify an Administrative Chart
Organization CodeAn alpha-numeric code used to identify the Organization.
OrganizationLong description of Organization
OrganizationOptional field to specify an Organization
ActiveIndicator for activity

Department

A Location is partitioned into Department(s). Department may be given additional properties not applicable to the broader location, and Work Areas are defined within a Department.

Table 1.6. Department Fields

FieldDescription
Effective DateThe date the Department record will go into effect.
Group KeyThe Group Key (Institution and Location) to which this department belongs
DepartmentAn alpha-numeric code used to identify the department
DescriptionLong description of Department
ChartOptional field to specify an Administrative Chart
OrganizationOptional field to specify an Organization
Payroll ApprovalFlag indicating whether specific documents for Leave and Timekeeping will go through the second level of payroll approval. If Payroll Approver is checked then a Payroll Processor role needs to be assigned.
ActiveIndicator used to activate or deactivate the Department

Department Role Member

This Role Member consists of a principal paired with a role. Depending on the role, the principal may be given elevated permissions not otherwise available to them, such as availability of specific earn codes, or the ability to view calendar documents across all work areas the department contains. Users assigned the Payroll Processor role will the second and final route level for specific Timekeeping and Leave Management documents.

Table 1.7. Department Role Member Fields

FieldDescription
Effective DateThis date should be on or after the effective date of the Department object to which it is attached.
Principal IdThis field selects the person to receive the role for the department
Principal NameRead-only field populated from Principal Id
Role NameSpecifies which role to give to the principal for the department. Roles are divided between Payroll Processor, "Time" and "Leave" Departments and further divided by Administrator and View Only Permissions
Expiration DateOptional field to specify a date for which the role is to be removed from the princpal. If left blank, the role will not automatically expire.

Department Affiliation

Define different types of affliations that an institution may associate with departments. Position Management allows a Position to have multiple affilationations with departments beyond a primary department affliation. Examples of department affiliations may be funding, rank, leave reporting.

Table 1.8. Department Affiliation Fields

FieldDescription
Effective DateThe date the department affiliation record is to become effective
Department Affiliation TypeDescriptive code to identify the type of department affiliations.
Primary IndicatorFlag used to indicate the affiliation type for the primary department and can be used to require at least one primary department.
Role NameSpecifies which role to give to the principal for the department. Roles are divided between Payroll Processor, "Time" and "Leave" Departments and further divided by Administrator and View Only Permissions
Expiration DateOptional field to specify a date for which the role is to be removed from the princpal. If left blank, the role will not automatically expire.

Work Area

The Work Area maintenance page is used to define areas within a department where employees can record their work. Work area is associated with an employees job. Approvers are assigned by work area, therefore the work area drives routing for employee timesheets. Additionally, multiple rules within the system are definable down to the work area level. Examples of rules definable by work area include - Time Collection Rule - designates whether the user will clock in / out or manually record time blocks and Clock Location Rule - designates the IP location where the user is expected to clock in / out from.

Work Area numbers are unique and assigned by the system. When creating a new work area the description is important because that is what the employee sees when choosing the assignment to clock into.

The “Approver” role is assigned on the work area maintenance document. The work area must have at least one valid approver to route a timesheet for approval.

Table 1.9. Work Area Fields

FieldDescription
Effective DateThe date the work area record is to become effective
Work AreaAuto-generated, read-only field used to uniquely identify the work area
DescriptionLong Description of the work area
Overtime Edit RoleDefines role that can edit the overtime code
Default Overtime Earn CodeDefines the default earn code for overtime earnings. Only earn codes that are designated as an Overtime Earn Code can be used (see Earn Code Maintenance Document). If no earn code is submitted then overtime rule's earn codes will apply to the overtime hours.
DepartmentThe department this work area is associated with
Admin DescriptionAdditional description field. This could be longer since it is not going to be displayed on the timesheet assignment drop down.
HR DistributionUsed to allow employees to clock in and out of a single assignment and then distribute hours at the end of the day to multiple assignments. Hours distribution is only available for time blocks created by the clock.
ActiveIndicator used to activate or deactivate the Work Area

Work Area Task

Task is a further designation within work area that can optionally be defined and used for tracking time. Together, the work area and task are referred to as "assignment" with specific funding associated with the assignment. Employees clock in / out or record their time against an assignment.

Table 1.10. Work Area Task Fields

FieldDescription
Effective DateThe Effective date for which the task will be effective. This date needs to be on/prior to the date the rule to takes effect. When editing, it will determine the date the new values go into effect.
TaskNumeric value for the task that is autogenerated
DescriptionText field used to identify the task. This description is presented to the employee when selecting the assignment to clock in or manually record their time.
Administrative DescriptionAdditional description field. This could be longer since it is not going to be displayed on the timesheet assignment drop down.
ActiveIndicator used to activate or deactivate the Task

Work Area Role Members

A Work Area Role Member may be added via Position or Principal. A Role Member added for a Position may contain more than one principal if more than one employee is allowed to hold a single position.

Work Area Principal Role Member

3 types of roles can be assigned to a work area

  1. Work Area Approver is the first stop for timesheets and leave calendars to be approved. This role also is the only approval needed for missed punch documents, leave requests, and any payouts or balance transfers triggered by leave accrual category reaching a maximum balance limit.

  2. Approver Delegate can be designated if an Approver is not available to approve KHR documents during a short period of time. Assigning Delegate role requires an Expiration Date that cannot be greater than 6 months from the effective date or into the future. During the period of time the Delegate role is active the user will have similar access to the work area approver and is the primary approver for that work area.

  3. Reviewer role has access to view and edit the work area's timesheets and leave calendars, but are unable to approve timekeeping or leave calendar documents.

When creating or editing a Work Area maintenance document, any of the work area roles can be assigned and at least one active work area approver is required to submit the document.

Table 1.11. Work Area Principal Role Member Fields

FieldDescription
Effective DateThe date which the Role Member becomes effective
Principal IdThe principal to which the role will be given.
Principal NameRead-only field auto-populated from principal id.
Role NameApprover, Approver Delegate and Reviewer. Time and Leave documents may be routed to, and specific actions can be requested of each of these roles.
Expiration DateThe date on which this role member will be removed from the Work Area.

Work Area Position Role Member

Work Area roles can also be assigned to a Position Number and the principal id with a job that has that Position Number is an approver for the work area.

Table 1.12. Work Area Position Role Member Fields

FieldDescription
Effective DateThe date on which this Position Role Member will become effective
Position NumberThe position to which this role will be given.
Role Name>Approver, Approver Delegate and Reviewer. Time and Leave documents may be routed to, and specific actions can be requested of each of these roles.
Expiration DateOptional date which will remove the position role member from the Work Area.

Set up Calendars for leave and pay periods

Calendar

The system supports multiple pay and leave cycles that are definable by start date/time and end date/time. Institutions can define multiple pay and leave reporting calendars such as monthly, semi-monthly, biweekly, or weekly. For example, an institution may define a pay period beginning at Noon on a Thursday which runs 2 weeks to Noon the following Thursday.

Calendars are assigned to an employee determining the length and frequency of their individual timesheets and leave calendars. Calendars are categories by Pay and Leave. These Calendars will be furthered defined by the Calendar Entries maintenance document with the reporting periods and also associated with employees on the Principal HR Attributes Maintenance Document.

Table 1.13. Calendar Fields

FieldDescription
Calendar NameText field used to defined the calendar entry for Pay or Leave reporting periods.
Calendar DescriptionsText field used to describe the calendar.
Calendar TypeIndicate calendar is to be used for Pay or Leave reporting periods.
FLSA Begin DayFor Pay Calandars, this determines the FLSA period for overtime calculations.
FLSA Begin TimeFor Pay Calandars, time of day when FLSA period begins.

For each employee that will report time and/or leave they will have an Principal HR Attribute record. If a user has a Pay Calendar value, their timesheet will be determined by the Pay Calendar's Calendar Entries (see next section). If the user has a Leave Calendar value, their leave calendar reporting period will be determine by the Leave Calendar's Calendar Entries. Shift Differential Rules can be applied to employees timesheet timeblock with a Pay Calendar qualifier

Calendar Entries

The system can define calendars for Pay or Leave. The Calendar Entry maintenance page defines the time period pay calendars (timesheet) andr leave reporting period.

Entries must be created for a time period before a timesheet and/or leave calendar can be created.

Table 1.14. Calendar Entries Fields

FieldDescription
Calendar NameCalendar to be associated with Calendar Entries.
Begin Period Date/TimeDate period starts. This drives what calendar days show on the timesheet and/or leave calendar.
End Period Date/TimeDate period ends. This drives what calendars days show on the timesheet and/or leave calendar.
Batch Initiate Date/TimeDate batch should run to create timesheets and/or leave calendars for the reporting period. For Pay Calendar, this date/time should occur prior to the Batch End Pay Period Date/Time.
Batch End Pay Period Date/Time For Pay Calendar, date batch job should run to end all timeblocks for this pay period. This inserts clock outs at the end of the pay period, and clock ins at the beginning of the subsequent pay period. If the system supports clock employees in different timezones this job needs to be set to run after midnight of the latest timezone.
Batch Employee Approval Date/TimeDate batch job should run to employee approve timesheets (i.e. payroll deadlines) and/or leave calendars.
Batch Supervisor Approval Date/TimeDate batch job should run to supervisor approve timesheets (i.e. payroll deadlines) and/or leave calendars. Timesheets and leave calendars documents for Departments that DO NOT have a Payroll Processor role will be final.
Batch Payroll Approval Date/TimeDate batch job should run to payroll approve timesheets (i.e. payroll deadlines) and/or leave calendars. Timesheets and leave calendars documents for Departments that DO have a Payroll Processor role will be final.

Note

To learn more about how to configure the batch Date/Time fields, please see the Batch Jobs documentation.

Earn Codes with Earn Code Security

Earn Code

The Earn Code maintenance page is used to define codes to categorize employee’s hours/earnings and time off. Earn codes define how the employees records time and leave blocks on timesheets and leave calendars. Most earn code attributes are defined in the payroll system, but there are a few codes which need to be modified on the timesheet prior to the data being extracted to payroll. An inflation factor and inflate minimum hours value are definable on the earn code document. These actions occur on the recorded hours in the timesheet, therefore would NOT need to be done in the payroll system. These codes may or may not be attached to an accrual category for tracking time against available balances or simple reporting. Additionally there are numerous flags on the earn code to limit availability and determine eligibility for accrual and scheduling leave.

Table 1.15. Earn Code Fields

FieldDescription
Effective Date The Effective date for which the earn code will be effective. This date needs to be on/prior to the date the rule to takes effect. When editing, it will determine the date the new values go into effect.
Earn CodeAlpha/Numeric code used to identify the earnings code. This value will appear on the calendar's time and leave blocks.
DescriptionLong description of earnings classification. This value will appear after Earn Code when adding time and leave blocks.
Roll up to Earn Code This field allows earn codes to be associated with another for payroll extract. For example, you could associate all the Sick codes with the regular sick earn code and not extract the detail into your payroll system. (Sick family leave, sick injury, etc. could all be extracted.)
Record Method Determines the value that will be entered for the earn code. The Time earn code requires in/out times, The Hours earn code will require a hours amount, the Days earn code will require a days amount, and the Amount earn code will require a dollar amount.
Active Status of the category, checked indicates Active, unchecked indicates Inactive. If the rule is being eliminated, insert a new effective dated row and uncheck the active box.
Overtime Earn Code Checked box indicates this may be used for overtime earn code. Codes with this checkbox are not available for entry on the timesheet.
Inflate Min Hours Hours incurred will be inflated to this minimum hours value. For example, Call Back Time rules specify the employee earns a minimum number of hours, regardless of the time worked. Set an inflate minimum hours on the earn code and the employee will see the number of hours correctly on the timesheet, instead of assuming it will be inflated later.
Inflate Factor The hours incurred will be multiplied by this factor. For example, Compensatory Time Earned (in lieu of overtime) is earned at a factor of 1.5. When the employee earns comp time, this setting will inflate the hours by a factor of 1.5 and all hours shown on the timesheet will be the inflated value. The employee will know the exact number of hours earned.
Counts as Regular Pay Use this field to cacluate the "Worked Hours"" in the Time Summary. This flag can be used by implementing institutions to develop payroll extracts
Leave PlanEmployees with the indicated Leave Plan may have access to this Earn Code on their Leave Calendar and Time Sheet
Accrual CategoryIf a category is entered the usage is validated against the employee’s balances.
Accrual Balance Action Supports validating against the Accrual Category associated with the Earn Code and instruct if it adjusts the balance of that category. Usage should validate against the available balance subtract from the total. Adjustment would work without validation and add/subtract the entry. Earn codes for timekeeping should have None selected.
Rounding OptionTraditional or Truncated rounding method is used when calculating leave accruals and reporting.
Fractional time allowedDefine fractional unit of time used for reporting leave. Indicate number of decimals.
Usage LimitInclude/Excluded indicates what effect time or leave reported with this earn code has on the Accrual Category's usage limits.
Eligible for Accrual Flag indicating this type of leave is eligible for accrual. This applies to all accrual categories the employee is eligible for. When a time or leave block is reported on a calendar with an earn code flagged as No, a negative accrual leave block will be calculated.
Affect Pay Earn codes with Yes flag will affect the employee's pay and can be used by schools who are extracting data to their payroll system. When earn code is used, a notification is sent to approver and department admin.
Allow Scheduled LeaveEarn codes with Yes flag will be available to user role on future leave calendars based Earn Code Security.
FMLAFLMA Earn Code indicator. If Principal HR Attributes is flagged for FMLA, the user role may have option to select this Earn Code based Earn Code Security.
Workman’s Comp Workman's Comp Earn Code indicator. If Principal HR Attributes is flagged for Workman’s Comp, the user role may have option to select this Earn Code based Earn Code Security.
Default Amount of Time Optional amount can be entered to provide user a default amount of hours (earn code method of hours) when adding a new leave block to a calendar. When a user selects earn code the specified amount of time will appear in the amount of leave taken. User can change the hours as needed once populated.
Allow Negative Accrual BalanceAllows usage to take the balance of the Accrual Category to a negative value.

Note

Earn Codes must have an Earn Code Security entry to appear on the calendars. If an Earn Code does not have an Earn Code Security entry it will not be displayed by default.

Earn codes used with several business objects within KHR Timekeeping and Leave Management.

  • Pay Type Regular Earn Code attribute will define the earn code used for timeblocks reporting time worked.

  • Earn Code Group defines set of earn codes that maybe used in timekeeping or leave rules.

  • Earn Code Security determines the availability of earn codes on the timesheet and leave calendar based on the user's role for the timesheet or leave calendar

  • Accrual Category has a default earn code that will be used for accrual leave blocks and attributes of that earn code will determine how leave balances are calculated.

  • System Scheduled Time Off requires the earn code for the Accrual Category used to accrue time off for university holidays.

  • Weekly Overtime Rule designates an earn code value to be assigned the calculated overtime hours unless a Work Area has a default overtime earn code defined.

  • Shift Differential Rule designates an earn code value to be assigned any qualifying shift differential time.

  • If Department Lunch Rule is going to be used, a simple LUN earn code needs to be defined for the auto lunch deduction is attached to qualifying timeblocks.

Earn Code Security

The Earn Code Security maintenance page is used to define which roles (employee, approver, payroll processor) see specific earn codes on the timesheet and/or Leave Calendar. This is definable at the department, salary group or group key value. These fields are accept wild cards (%).

When adding time or leave blocks to a calendar, an assignment must be selected before the earn code options are displayed. Available earn codes will be determined by the selected Assignment's department, work area, salary group and the user's role.

Table 1.16. Earn Code Security Fields

FieldDescription
Effective Date The Effective date for which the earn code security rule will be effective. This date needs to be on/prior to the date the rule to takes effect. When editing, it will determine the date the new values go into effect.
Group KeyIf a group key is defined, only entries associated with a job record in this group key will be subject.
DepartmentIf a department is defined, only entries associated with a job record in this department will be subject.
Salary GroupIf a salary group is defined, only entries associated with a job rcd in this salary group will be subject.
Earn CodeThis is the code to define values for earn code.
Earn Code TypeDetermines if Earn Code should be displayed on Timesheet, Leave Calendar, or Both.
Employee/Approver/Payroll ProcessorThe role checked can select the specified code on the time/leave entry box.
Active Status of the Earn Code Security, checked indicates Active, unchecked indicates Inactive. If the rule is being eliminated, insert a new effective dated row and uncheck the active box.

Note

Overtime Earn Codes must have an Earn Code Security record if the Work Area allows for the Overtime Earn Code to be edited (i.e. changed from Comp Time to Overtime).

Earn Code Group

The Earn Code Group maintenance page is used to define groupings of earn codes. Earn Code Groups are used for defining timekeeping rules, displaying the time summary, and displaying warnings or additional information regarding the earn codes used for timeblocks on the timesheet or leave calendar.

Table 1.17. Earn Code Group Fields

FieldDescription
Effective Date The Effective date for which the department code rule will be effective. This date needs to be on/prior to the date the rule takes effect. When editing, it will determine the date the new values go into effect.
Earn Code GroupText field used to identify the group.
DescriptionText which describes the purpose of this grouping of earn codes.
Show on SummaryIn the Time Detail summary, the sum of timeblocks with earn codes in the Earn Code Group will be displayed as a row. The Earn Code Group's description text will display in the summary to description to the summarizied hours.
Active Status of the earn group, checked indicates Active, unchecked indicates Inactive. If the earn group is being eliminated, insert a new effective dated row and uncheck the active box.
Warning TextText entered into this field will display on calendars and approval pages when an employee uses an earn code belonging to this group

Note

Warning messages that display timesheets and leave calendars are also available for approvers to see from the Time Approval and Leave Approval grids

Earn Code Group Definition

The Earn Code Group Definition Collection belonging to Earn Code Group Maintenance is used for associating specific earn codes with the group.

Table 1.18. Earn Code Group Fields

FieldDescription
Earn Code In the Earn Group Definitions section, add the earn codes to be included in this group.
DescriptionRead-only field that auto-populates with the description of the earn code

Note

An Earn Code can only be in one Earn Code Group that is flagged to display in the Time Detail Summary.

Timekeeping's Shift Differential Rule and Weekly Overtime Rule used Earn Code Groups to identify qualifying Earn Codes. For example, all the pay type regular earn codes would be include the Earn Code Groups defined for both rules.

Pay Type

The Pay Type maintenance page defines a classification of position / job used to divide groups of employees according to payroll attributes. This attribute is associated with an employees job and is further used to qualify for timekeeping rules such as Time Collection, Shift Differential, and Daily Overtime. Pay Type will likely be defined off an existing payroll attribute and created at implementation time to designate different rules for different populations of employees.

Table 1.19. Pay Type Fields

FieldDescription
Effective DateThe date on which this Pay Type is to go in effect.
Pay TypeCode used to identify the Pay Type
DescriptionOptional long description
Regular Earn CodeThe Earn Code that will be used to report time worked. Assignments will use the Job's Pay Type to determine the regular earn code for timeblocks that will record regular time worked.
FLSA StatusPayroll attribute
Pay FrequencyPayroll attribute
ActiveIndicator used to activate or deactivate the Pay Type

Core Position Management

With KHR's modulations you can turn on and off modules for your implementations. Salary Group, Pay Grade and Position are required for all KHR modules. Depending on the module being implemented the required information may vary. For example with Position Management, position has several data attributes that may not be required for a Timekeeping implementation. If Position Management is not being implemented then the system administrator can access Salary Group, Pay Grade and Position Base from the Time & Leave Admin

Salary Group

Salary Group is a high-level HR/Payroll object that can span multiple institutions and locations (Group Keys). It contains a number of properties useful for reporting and in the execution of KHR's business logic.

Table 1.20. Salary Group Fields

FieldDescription
Effective DateThe date on which this Salary Group is to go in effect.
Salary GroupCode used to identify the Salary Group
DescriptionOptional long description
Group KeyThe Group Keys (Institution and Location) to which this Salary Group belongs
Percent TimeMaximum percentage of time worked for the salary group. When defining individual positions and jobs, the percent time will be less than the Salary Group's Percent Time. Used for leave accrual and payroll calculations, Full Time Engagement reporting, etc. Steps in increments of whole numbers. Positive amounts only, less than 100.
Benefit EligibleYes or No field indicating whether entities within this salary group are benefit eligible.
Leave EligibleYes or No field indicating whether entities within this salary group are eligible for leave.
Leave PlanUnless Leave Eligible = "Y" (Yes), this is a required field. It is not required if the salary group is not leave eligible.
ActiveIndicator used to activate or deactivate the Salary Group

Pay Grade

Defines detailed pay and hiring ranges for Salary Groups.

The Pay Grade maintenance page is used to define a classification of position / job to divide groups of employees for the purposes of defining rules within the Time and Attendance system. Pay grade can be used to define specific shift differential rules for the employees in the identified pay grade.

Table 1.21. Pay Grade Fields

FieldDescription
Effective DateThe date on which this Salary Group is to go in effect.
Pay GradeCode used to identify the Pay Grade
Salary GroupThe Salary Group to which this Pay Grade belongs
DescriptionOptional long description
ActiveIndicator used to activate or deactivate the Pay Grade

Note

Shift Differential Rule has Salary Group and Pay Grade qualifiers

Position

Position records are created with a unique position number that can be assigned to Job.

A Work Area approver role can also be assigned by Position Number. Employees with Job record that has the Position Number will be the approver for Work Area.

Table 1.22. Position Base Fields

FieldDescription
Position NumberAuto generated unique Position Number that will be assigned a Job
Effective DateThe date on which this Position is to go in effect.
DescriptionOptional long description
ActiveIndicator used to activate or deactivate the Position

Note

If the KHR implementation that does not include the Position Management Module, Position document is a simplified document called Position Base

Job

The Job maintenance page is used to associate a person with job attributes and utilized by KHR Timekeeping and Leave Management. A single person may have multiple jobs and each job can have only one pay rate. Each job for a given employee is assigned a unique job number. Attributes on the job maintenance page are used to determine timekeeping rules to apply and which jobs are eligible for leave. It is likely that these attributes will be mapped to an existing payroll/HR system.

Table 1.23. Job Fields

FieldDescription
Effective DateThe date on which this Job is to go in effect.
Group KeyThe Group Key (Institution and Location) to which this Job's Department belongs
Principal IDPrincipal ID for the employee the job belongs
NameRead only field that populates when Principal ID is provided
Job NumberSequential number which uniquely identify the employees job occurrence for this employee. Number is automatically generated and is unique for each job record for an employee.
 The department the job is associated with. This drives the available work areas when setting up assignments for this job.
PositionPosition associated with the job.
Pay TypeThe pay type value appropriate for this job.
Salary GroupThe salary group value appropriate for this job.
Pay GradeThe pay grade value appropriate for this job.
Compensation RateThe hourly rate for this job. Only one rate per job is supported.
Standard HoursThe standard hours for this job. This drives accrual proration and “ready to approve criteria” for the timesheet (only timesheets meeting standard hours can be approved). Hourly jobs can have 0 standard hours.
FTERead only FTE that is calcuated from standard hours and 40 hours work week. Used by the accrual service for calculating leave accrued by on FTE.
Eligible for LeaveFlag indicating the job is eligible for leave benefits. If checked, the accrual service will use the calculated FTE for prorated Accrual Categories.
FLSA StatusIndicates if Job is FLSA exempt or non-exempt. This field along with Eligible for Leave and a defined leave plan on the employee's Principal HR Attributes will determine what timekeeping and leave calendars are displayed for the employee.
ActiveIndicator used to activate or deactivate the Job

Assignment

TODO: Provide field mapping for Assignment, define basic object

Table 1.24. Assignment Fields

FieldDescription
Effective DateThe date on which this Assignment is to go in effect.
Group KeyThe Group Key (Institution and Location) to which this assignment's Department belongs
Principal IDPrincipal ID for the employee the assignment belongs
NameRead only field that populates when Principal ID is provided
Job NumberSequential number which uniquely identify the employees job occurrence for this employee. Number is automatically generated and is unique for each job record for an employee.
DepartmentThe department the assignment is associated with. The Principal ID's Job and the Work Area must be the same Department.
Work AreaThe work area the assignment is associated with
TaskThe work area's Task the assignment is associated with. Task is not required.
ActiveIndicator used to activate or deactivate the Assignment

Assignment Accounts

Assignment accounts will associated the designated funding account with the time reported for the assignment on a timesheet. Funding for an assignment can be associated with multiple accounts and distributed by percentages. Also funding can be designated for earn codes for the time reported on the timesheet.

Chapter 2. Timekeeping Configuration

This chapter discusses all rules and configurations for Timekeeping module of KHR. All rules and configurations can be accessed through maintenance documents listed under the Timekeeping section on the Time & Leave Admin tab.

Timekeeping section on the application's Time & Leave Admin tab.

Please note that most of the configurations in Timekeeping module rely heavily on configurations made in the HR and payroll module and therefore cannot be completed without setting those up properly. (Basic Setup in Administrator Guide)

Grace Period Rule

The Grace Period Rule is an optional rule that results in the system rounding clock in/outs times based on the chosen factor. This rule rounds up and down based on the clock action time. The benefit of having a grace period rule is that it eliminates small fractions of time and makes calculations less complicated for those employees trying to reach standard hours for the week. It also alleviates the rush to clock in or out right on the hour.

Grace Period Rule Maintenance document

Procedure 2.1. Setting up a grace period rule

  1. Put in a short description of the grace period you are creating.

  2. Pick a date that you want your new grace period to be effective from.

  3. Enter the minutes that will define the grace period. As you can see in the table below, the minute entered will become the fourth value in a range of six minutes that comprise the grace period.

  4. Check the box if you want your grace period to be active. Unchecked means that the rule is not active. You can still create the rule, even if you leave it as inactive.

  5. Submit the document after filling out all required fields.

Note

Grace Period Rule is a system wide rule so only one rule will exist and be applicable for the whole system.

When installing KHR, a configuration parameter can be used to determine which time blocks the grace period rule is applied too. The Grace Period Rule configuration parameter, kpme.grace.period.rule.configuration, options include

  • TIME: Default option apply rule to all timeblock with earn codes with record method of Time.

  • REG: Rule is applied to all assignments regular timeblocks (assignment -> job -> pay type -> regular earn code).

  • CLOCK: Rule is applied only to timeblocks that have been created via the clock/missed punch.

Table 2.1. Grace period rule

Rounded TimeActual Clock in time
:00:57, :58, :59, :00, :01, :02
:06:03, :04, :05, :06, :07, :08
:12:09, :10, :11, :12, :13, :14
:18:15, :16, :17, :18, :19, :20
:24:21, :22, :23, :24, :25, :26
:30:27, :28, :29, :30, :31, :32
:36:33, :34, :35, :36, :37, :38
:42:39, :40, :41, :42, :43, :44
:48:45, :46, :47, :48, :49, :50
:54:51, :52, :53, :54, :55, :56

Weekly Overtime Rule

The Weekly Overtime Rule defines the steps necessary to calculate weekly overtime. This maintenance document page allows the user to establish which earn codes count towards the calculation of overtime hours, what overtime earn code to use and where the overtime hours should be applied. This maintenance document is different because there is only one Weekly Overtime rule in effect at a time.

Note

There is no create new link, the link directs straight to the page to add steps to or edit the existing steps.

Weekly Overtime Rule Maintenance Document

Table 2.2. Weekly Overtime Rule Document fields

fielddescription
Effective DateEffective date for which the Weekly Overtime Rule will be effective. This date needs to be on or prior to the date the rule is to take effect. When editing, it will determine the date the new values go into effect.
Max Hours Earn GroupThe earn code group (using the Earn Code Group maintenance document) that includes all the earn codes that count towards the calculation of overtime.
Convert from Earn GroupThe earn code group that includes the earn codes to be converted to overtime.
Convert to Earn CodeThe default earn code which other earnings will be converted to (ex: OVT). Only earn codes that are designated as an Overtime Earn Code can be used (see Earn Code Maintenance Document). This earn code is used for overtime hours unless the Work Area for the Assignment has a designated Default Overtime Earn Code (see Work Area Maintenance Document).
Apply to Earn GroupDefines the earn codes of the timeblocks that can have the Convert to Earn Code overtime hours applied.
Override Work Area's Default OvertimeIf this flag is checked, the Convert to Earn Code designated for the step cannot be changed. If a Work Area has default overtime earn code defined, a designated Work Area role (employee, approver, payroll processor) will have the ability to change that overtime earn code.
StepThis enables the definition of multiple steps in the hours conversion for overtime. Max Hours Earn Group and Max Hours should be the same for all weekly overtime steps.
Max HoursDefine the maximum hours in an FLSA period for overtime calculation (For example: 40)

Procedure 2.2. Setting up a weekly overtime rule

  1. Put in a short description of the weekly overtime rule you are creating.

  2. Pick a date that you want your new rule to be effective from.

  3. Enter the earn code group you have defined to use for this rule using earn code group maintenance document. You can use the lookup widget to find the right earn code group.

  4. In "Convert from Earn Group", select an earn code group which contains the list of earn codes to be converted to overtime.

  5. In "Convert to Earn Code" specify the earn code which hours will be converted to as overtime.

    Important

    Only earn codes that are designated as an Overtime Earn Code can be used

  6. Another Earn Code Group will be need to be created that includes all the timeblock earn codes that are the "Convert to Earn Code" should appear on. Earn Codes used for leave should not be included in this Earn Code Group.

  7. This flag will override ability to allows certain work areas to change the overtime earn code.

  8. Enter the step number. Multiple steps maybe used to allow specific earn codes to be applied towards overtime. Example: Overtime for Leave Hours maybe be converted towards overtime in first step with a second step being qualifying Regular earn code. Different Convert to Earn Codes can be used to track the steps that earn overtime using the flag that would prohibit allowing specific work areas from changing the earn code.

  9. Enter the maximum number of hours you want to allow for overtime calculation in each FLSA period.

  10. Check the box if you want your rule to be active. Unchecked means that the rule is not active. You can still create the rule, even if you leave it as inactive.

  11. Route your rule document by clicking submit button at the bottom of the page.

Important

If there is only one step in weekly overtime calculation, the Convert from Earn Group will be the same as Max Hour Earn Group. If there are multiple steps in overtime calculation, the 'convert from earn group' will be an earn code group which is a subset of the 'max hours earn group'.

An overtime block is created on this timesheet on Friday. The Maximum hours was set to 40 so any extra hours after 40 are converted to Overtime.

An FLSA week may span more than one timesheet (i.e. semi monthly pay periods). The calculated overtime will include qualifying timeblocks from the previous and current timesheet that is part of the FLSA week (see Calendar maintenance document)

Daily Overtime Rule

The Daily Overtime Rule is used to define the parameters by which daily overtime is calculated. This calculation runs prior to the weekly overtime calculation and can be limited to specific populations by pay type, location, dept, and work area. All of these parameters can be replaced by a wild card value (%) allowing the user to designate a rule at different levels.

Daily Overtime Rule Maintenance Document

Procedure 2.3. Setting up a Daily Overtime Rule

  1. Put in a short description of the daily overtime rule you are creating.

  2. Pick a date that you want your new rule to be effective from.

  3. Select a Location for your rule. If a location is defined, only jobs in that exact location will be subject to daily overtime rule.

  4. Select a pay type. If a pay type is defined, only entries associated with a job of this pay type will be subject to the defined overtime rule.

  5. Select a Department. If a department is defined, only entries associated with a job in this department will be subject to the this rule.

  6. Select a work area. If a work area is defined, only entries associated with a job that has this work area will be subject to this rule.

  7. Enter a maximum gap of time in minutes that is allowed before daily overtime is considered invalid. This field is explained in more detail later in this document.

  8. Enter the number of hours which, if exceeded, result in daily overtime.

  9. Check the box if you want your rule to be active. Unchecked means that the rule is not active. You can still create the rule, even if you leave it as inactive.

  10. In "Convert to Earn Code" you specify the earn code which hours will be converted to as overtime.

    Important

    Only earn codes that are designated as an Overtime Earn Code can be used

  11. In "Convert from Earn Group", select an earn code group which contains the list of earn codes that are summed to the daily max hours to be converted to overtime.

  12. Route your rule document by clicking submit button at the bottom of the page.

The table below lists all fields on the Daily Overtime Rule Document along with their descriptions.

Table 2.3. Daily Overtime Rule Document fields

fieldsdescription
Effective DateEffective date for which the daily overtime rule will be effective. This date needs to be on/prior to the date the rule to takes effect. When editing, it will determine the date the new values go into effect.
LocationIf a location is defined, only entries associated with a job in this location will be subject to the defined rule. Validates against the location table.
DepartmentIf a department is defined, only entries associated with a job in this department will be subject to the defined rule. Validates against the department table.
Work AreaIf a work area is defined, only entries associated with a job that has this work area will be subject. Validates against the work area table.
Max Gap MinutesUsed to identify a maximum gap of time in minutes that is allowed before daily overtime is considered invalid. For example, a rule that states daily overtime is given for working over 8 hours with a max gap of 30 minutes implies that employee must work a total of 8 hours in the day and have a gap of no more than 30 minutes in the reporting of those hours to be eligible.
Shift HoursThe number of hours which, if exceeded, result in daily overtime.
Convert to Earn CodeThe earn code which hours will be converted to as overtime. Only earn codes that are designated as an Overtime Earn Code can be used (see Earn Code Maintenance Document).
Convert from Earn GroupThe earn code group defined (using the Earn Code Group maintenance doc) which contains the list of earn codes that are summed to the daily max hours to be converted to overtime.
ActiveStatus of the rule, checked indicates Active, unchecked indicates Inactive. If the rule is being eliminated, insert a new effective dated row and uncheck the active box on the existing row.

Shift Differential Rule

The Shift Differential Rule defines rules for assigning shift differentials. This rule applies shift automatically to earn codes when clock times are specified. If an earn code is entered with an hours amount (ex: Sick), the rule would not assign shift. Rules can be set system wide, or on specific populations (most specific rule for that assignment will be enforced). The rule will add a specified earn code to the eligible shift hours. Different earn codes are needed to result in different shift amounts (e.g. each earn code attached to a shift rule has its own associated rate for payment in Payroll). The shift differential rule only assigns the additional earnings codes to shift hours within the specified shift time period. Any hours outside of the shift period will not be assigned shift.

Shift Differential Rule Maintenance document

Table 2.4. Shift Differential Rule

fielddescription
Effective DateThe effective date which the shift differential rule will be effective. This date needs to be on or prior to the date the rule is to take effect.
LocationIf a location is defined, only entries associated with a job in this location will be subject to the shift rule. Wild card of (%) is acceptable as input.
Salary GroupIf a salary group is defined, only entries associated with a job in this salary group will be subject to the shift rule. Wild card of (%) is acceptable as input.
Pay GradeIf a pay grade is defined, only entries associated with a job in this pay grade will be subject to the shift rule. Wild card of (%) is an acceptable input.
Earn CodeThe earn code that will be applied to the eligible shift.
From Earn GroupThe earn code group defined to represent the earn codes to be converted to Shift Differential Earn Code.
Begin TimeThe beginning time of the eligible shift.
End TimeThe end time of the eligible shift. This could be on the following day if the eligible shift is overnight.
Minimum HoursThe minimum number of hours a shift must be in order to qualify for shift differential. A zero in this field would mean that there is no minimum shift requirement.
Sun-Sat check boxesCheck which days are eligible for shift differential.
Maximum Gap MinutesThe maximum number of minutes which can separate time blocks and still qualify as an eligible shift.
User Principal IDUser that set up the shift rule.
ActiveStatus of the shift differential rule, checked indicates Active, unchecked indicates Inactive.
Pay CalendarIf a pay Calendar is defined, only entries associated with a Person with this pay calendar will be subject to the shift rule. Wild card of (%) is an acceptable input.

Procedure 2.4. setting up a shift differential rule

  1. Put in a short description of the shift differential rule you are creating.

  2. Pick a date that you want your rule to be effective from.

  3. Enter a Location for your rule. If a location is defined, only jobs in that exact location will be subject to shift differential rule. You can also use a wildcard character (%) to cover all locations.

  4. Enter a salary group to limit this rule only to this salary group. You can also use a wildcard character (%) to cover all salary groups.

  5. Enter a valid pay grade. If it is defined, only jobs with this pay grade will be subject to this rule. You can also use a wildcard character (%) to cover all pay grades.

  6. Enter the earn code to be applied to an eligible shift.

  7. Enter the earn code group that represents earn codes that will be converted to Shift Differential Earn Code.

  8. Enter the begin time for an eligible shift.

  9. Enter the end time for an eligible shift.

  10. Enter the minimum number of hours a shift should be in order to qualify for shift differential.

  11. Check the week days that are eligible for shift differential.

  12. Enter the maximum number of minutes which can separate time blocks and still qualify as an eligible shift.

  13. Check the box if you want your rule to be active. Unchecked means that the rule is not active. You can still create the rule, even if you leave it as inactive.

  14. Enter the Pay Calendar record that defines the pay calendar where the shift rule should be applied.

  15. Submit the document after filling out all required fields.

An example of a shift differential time block can be seen on this Timesheet.

Time Collection Rule

The Time Collection Rule maintenance page is used to define how employees record time, via clock entry or manual entry. This rule can be defined at various levels including at a system level for a specific Pay Type. The timesheet shows the clock tab for entry if the most specific rule for that assignment is marked as a clock user. If no rule is found, then by default the employee will be a clock user.

Time Collection Rule Maintenance document

Table 2.5. Time Collection Rule Document Fields

FieldDescription
Effective DateThe Effective date for which the time collection rule will be effective. This date needs to be on or prior to the date of the rule to take effect.
Group KeyGroup Key the time collection rule is associated with. A wild card (%) can be provided indicating the rule is in effect system wide for a specific pay type. If Group Key is wildcard then Department cannot be wildcarded.
DepartmentDepartment the time collection rule is associated with. A wild card (%) can be provided indicating the rule is in effect for all departments.
Work AreaWork area the time collection rule is associated with. A wild card (%) can be provided indicating the rule is in effect for all work areas.
Pay TypePay Type the time collection rule is associated with. A wild card (%) can be provided indicating the rule is in effect for all Pay Type for the specified Group Key, Department and/or Work Area.
Clock UserIf this box is checked, clock entry will be required for recording time based on the department and work area values provided above.
ActiveStatus of the Time Collection Rule, checked indicates Active, unchecked indicates Inactive.

Clock Location Rule

This feature enables administrators to restrict clock entry locations by defining approved IP addresses for Timekeeping use. Clock location rules can be set system wide, or as granular as a specific employee job record. In case of having more than one valid clock location rule for an assignment, the most specific rule for that assignment will be enforced by the system.

When installing KHR, a configuration parameter determines if the system should prevent clock users from using an invalid clock location (invalid IP) or allow the invalid clock action but a warning of the invalid action is displayed on the timesheet and the Time Approval grid for them employee. If configuration parameter, kpme.allow.clockingEmployee.from.invalidLocation, is true a warning is displayed for the invalid IP address clock action. False for this configuration parameter will prevent the employee from clocking in for an invalid IP address.

Regardless of a rule, the IP address is captured on every clock action and can be seen on the Clock Log Inquiry page.

Table below shows fields used to record and maintain a clock location rule along with their description.

Clock Location Rule Maintenance document

Table 2.6. Clock Location Rule Document Fields

fieldsdescription
Effective DateThe Effective date for which the IP address validation will be effective. This date needs to be on/prior to the date the rule to takes effect. When editing, it will determine the date the new values go into effect.
Group KeyIf a Group Key is defined, only entries associated with a job with that Group Key will be subject to IP address validation. Wild card of (%) is acceptable as input for this field.
DepartmentIf a department is defined, only entries associated with a job in that department will be subject to IP address validation. Wild card of (%) is acceptable as input for this field.
Work AreaIf a work area is defined, only entries associated with a job in this work area will be subject to IP address validation. Wild card of (%) is acceptable input.
Principal IDIf a principal ID is defined, only this specific employee will be subject to IP address validation. Wild card of (%) is acceptable as input for this field.
Job NumberIf a job number is defined, only this specific employees job will be subject to IP address validation (specific Principal ID is required). Wild card of (%) is acceptable as input.
IP AddressThe IP Address to be used for validation. A wild card can be placed at the end of a partial IP address to represent a range of IP addresses. To grant exceptions to rules in effect, wild card the IP address field.
ActiveStatus of the IP validation rule, checked indicates Active, unchecked indicates Inactive.

Procedure 2.5. Setting up a clock location rule

  1. Go to Clock Location Rule Document Page by clicking on the link in Timekeeping section on the maintenance tab.

    1. To create a new rule, click on the create new button on top right of the lookup page.

  2. On the Document Overview tab, Enter a short description of what you're going to do. For example: clock location rule for IU-UITS

    1. You can also fill out the non-required fields for a brief explanation of the work you are doing or an organization document number for reference.

  3. On the next tab, Clock Location Rule Maintenance, all fields are required, however you can skip specifying any field by entering the '%' character as wild card.

  4. Enter a date by either selecting from the small calendar widget or manually writing it in the effective date text box.

  5. Enter a Group Key to set the clock location for it. You can use the lookup to select a Group Key by clicking the magnifying glass or enter the ID manually in the input field. You can also use '%' to generalize this rule to all Group Keys.

  6. Enter a department ID to set the clock location for it. You can use the lookup to select a department by clicking the magnifying glass or enter the ID manually in the input field. You can also use '%' to generalize this rule to all departments.

  7. Enter a work area. You have the same options as in the previous step.

  8. Enter a principal ID to enforce your rule on only one employee or use '%' to cover all employees that match your other criteria.

  9. Enter a job number to enforce your rule an employee's specific job or use '%' to cover all employees that match your other criteria.

  10. Set the rule Active by checking the box. You can create a rule and leave the box unchecked. The rule will be created but will not be active and therefore will not affect employees' clock actions.

  11. On the IP address tab, you need to specify an approved IP address. You can use the '%' character wildcard in any of the IP address sections, starting from the rightmost section, to cover a progressively larger set of addresses.

    1. You can add multiple addresses by adding them one by one.

  12. At this step, you've filled in all the required fields, so you can route your document by clicking submit button at the bottom of the page.

  13. Make sure that your document is successfully submitted by looking for a message on top of the page saying Document was successfully submitted.. In case of any errors, you will see red markers appearing next to the fields that are filled correctly.

Like any other documents in the system, submitting the document will place it in the workflow for further process. You can track the status of your document by looking it up through document search.

Tip

To eliminate a clock location rule, insert a new effective dated row for that rule and uncheck the active box on the rule to be eliminated.

Department Lunch Deduction Rule

The Department Lunch Deduction rule is used to define automatic lunch deductions. This rule only applies to clock entry employees and rules can be set system wide, or as granular as a specific employee job record. The most specific rule for a given assignment will be enforced.

Department Lunch Deduction Rule Maintenance document

Table 2.7. Department Lunch Deduction Rule Document fields

fielddescription
Effective DateThe Effective date for which the automatic lunch deduction rule will be effective. This date needs to be on/prior to the date the rule is to take effect. When editing, it will determine the date the new values go into effect.
Group KeyIf a Group Key is defined, only entries associated with a job with that Group Key will be subject to the automatic lunch deduction. Wild card of (%) is acceptable as input.
DepartmentIf a department is defined, only entries associated with a job in this department will be subject to the automatic lunch deduction. Wild card of (%) is acceptable as input.
Work AreaIf a work area is defined, only entries associated with a job in this work area will be subject to the automatic lunch deduction. Wild card of (%) is acceptable as input.
Principal IDIf a principal ID is defined, only this specific employee will be subject to the automatic lunch deduction. Wild card of (%) is acceptable as input.
Job NumberIf job number is defined, only this specific employees job will be subject to the automatic lunch deduction. Wild card of (%) is acceptable as input.
Lunch Deduction MinutesThe amount of minutes to be deducted as a lunch.
Shift HoursThe number of hours which must be met in order for the deduction to occur.
ActiveStatus of the automatic lunch deduction rule, checked indicates Active, unchecked indicates Inactive.
User Principal IDUser which set up the lunch rule.

Procedure 2.6. Setting up a department lunch deduction rule

  1. Put in a short description of the lunch reduction rule you are creating.

  2. Pick a date that you want your new rule to be effective from.

  3. Select a Group Key. If a Group Key is defined, only entries associated with a job in this Group Key will be subject to the this rule.

  4. Select a Department. If a department is defined, only entries associated with a job in this department will be subject to the this rule.

  5. Select a work area. If a work area is defined, only entries associated with a job in this work area will be subject to this rule.

  6. If you want to apply this rule to only one user, enter their principal ID in the form. You can use the lookup widget to do this. To leave this field as general as possible, simply enter a wildcard character (%) as principal ID. That means all users that match your other criteria.

  7. If you are creating this rule for one specific employee's job, you can define a job number to only apply the rule to one specific job. If a principal id is not specified simply use a wildcard character (%).

  8. Next, enter the number of minutes you want the system to deduct as lunch time. (For example: 30)

  9. Enter the number of hours that the system should consider as a work shift to apply this lunch deduction rule. (For example: 6)

  10. Check the box if you want your rule to be active. Unchecked means that the rule is not active. You can still create the rule, even if you leave it as inactive.

  11. Submit the document after filling out all required fields.

This is how a lunch deduction appears on an employee's timesheet

Tip

To eliminate an existing rule, insert a new effective dated row and uncheck the active box on the existing rule.

Note

To show departmental lunch deductions on the timesheet, add a new Earn Code LUN with a Record Method of Hours.

Note

TimeHoursDetails object and corresponding table, TK_HOUR_DETAIL, contains the timeblocks values needed for a payroll extract. The values have all the calculations and rules such as Department Lunch Deduction Rule applied.

Note

The system does not handle Work Areas that has both Department Lunch Deduction Rule and allows distribution of clock timeblock hours.

Chapter 3. Leave Management Configuration

This chapter discusses the configuration of key leave management business objects. The order in which the sections are presented are important in that they generally build on each other. That is, to configure an accrual category, a leave plan should already be configured. While it is possible to configure a leave plan at the time of accrual category configuration, such a configuration would lead to documentation hopping if the reader is not already well acquainted with leave plan configuration requirements. Thus it is recommended to read this chapter in the order presented.

The reader should also be familiar with the concepts discussed in the chapter "Basic Setup" in order to test the configurations presented in this chapter.

Leave Management Configuration

This chapter discusses all rules and configurations for Leave Management module of KHR. All rules and configurations can be accessed through maintenance documents listed under the Leave Management section on the Time & Leave Admin tab.

Time & Leave Admin
Leave Maintenance Section

Leave Plan

The system supports configurable Leave Plans that can be attached to employees (Principal HR Attributes) and/or salary groups (Position Management). Leave Plans are used configuring one or more accrual categories. Employees eligible for leave will be designated an Leave Plan via the Principal HR Attributes. An employee's leave plan will be used to determine the start of their leave calendar year (year to date balances and carry over rules), the number of months into the future they can plan their leave, and earn codes that the employee is eligible to use on their leave calendars and/or timesheets.

Leave Plan Maintenance Document

Table 3.1. Leave Plan Fields

FieldDescription
Effective DateThe Effective date for which the Leave Plan will be effective.
Leave PlanText field used to identify the Leave Plan.
DescriptionText field used to describe the Leave Plan.
Planning MonthsNumber of months the accrual service will calculate into the future and allow planning and submission of leave requests
Calendar Year Start (MM/DD)Month and Day (MM/DD) of the start of the leave year (i.e. Calendar or Fiscal Year). This date will be used to calculate year to date accruals, usages, and balances in the leave summary.
Batch Prior Year Carry Over Start (MM/DD)Date batch job should run to create a carry over leave block for each accrual category balance from the prior year. This should run will all leave calendars from the previous year are final. The leave summary that includes accrual balances will use this carry over leave block to calculate available balances.
Batch Prior Year Carry Over Start Time (00:00 AM)Time batch job should run to create a carry over leave block for each accrual category balance from the prior year
ActiveStatus of the Leave Plan, checked indicates Active, unchecked indicates Inactive.

Accrual Category Configuration

The system supports the creation of accrual categories within leave plans to establish groups of benefit time that can be reported and/or accrued against. Accrual Category will define the rules used by the system’s accrual service including proration, maximum balances, and establish what happens once maximum balances are reached.

Accrual Category Maintenance Document

Table 3.2. Accrual Category Fields

FieldDescription
Effective DateThe Effective date for which the Leave Plan will be effective.
Accrual CategoryCode used to identify the Accrual Category.
DescriptionDescription of the Accrual Category
Leave PlanLeave Plan associated with the Accrual Category.
Accrual Earn IntervalTiming when accrued leave is earned. Options: Daily, Weekly, Semi-Monthly, Monthly, Yearly, Pay Calendar, No Accrual The Accrual Service will create an Accrual timeblock on the last date of the accrual period. Pay Calendar can be used for Timekeeping employees that earns accrual at the end of each pay period. No Accrual can be used for Accrual Categories used for System Scheduled Time Off.
ProrationIndicate if accrual is prorated based on partial period. For example, start date is 10th day of the month for Monthly Accrual Earn Interval would be prorated from the start date. If Off, then no leave will be accrued until the start of the next accrual period Accrual earn Interval.
Unit of TimeDefine unit of time for accruing leave. Options: Days Hours
Min Percent Worked to Earn AccrualThe start or end date must be within the minimum days of the Accrual earn Interval. If start or end date is after then no accrual is earned.
DonationIndicates the accrued leave is eligible to be donated. Leave Donation maintenance document will only Donated Accrual Categories that are flagged as eligible for donation.
Show on GridAccrual Category will be displayed on the leave summary and leave ledger.
Default Earn CodeThis earn code will be used by the accrual service and assign to accrual timeblocks. This earn code needs to be defined prior to creating the Accrual Category.
Category Has RulesFlag if accrual category has rules. Accrual Categories for transferring leave or for handling System Scheduled Time Off.
ActiveStatus of the Leave Plan, checked indicates Active, unchecked indicates Inactive.

Tip

Prior to creating a new Accrual Category, a Leave Plan and an Earn Code (Accrual Category's Default Earn Code) needs to exist.

Accrual Category Rule

This section describes the configurations necessary to implement common rules for an accrual category. To follow along with this section, the reader should complete the sections for Leave Plan and Accrual Category configuration, or the objects should already be defined in the application.

Accrual Category Rules

One accrual category rule can be used to define up to four properties for an accrual category;

  • Accrual rates

  • Maximum balance limits

  • Maximum carryover limits

  • Usage limits

Accrual Rate Configuration

Accrual Category that is flagged to have Accrual Rules are required to enter at least one rule. Accrual Rules are used to defined the amount of leave that is accrued based on lenght of service. The employee's service date found in their Principal HR Attribute record is used by the accrual service to determined which rules should be used to calculate their accrued leave for an Accrual Earn Interval.

Table 3.3. Accrual Category Rule Fields for configuring Accrual Rate

FieldDescription
Service Unit of TimeUnit of time for measuring service start and end amounts for the accrual rule
StartAccrual rule begins on the indicated service milestone.
EndAccrual rule ends on the indicated service milestone.
Accrual RateAmount accrued for each Accrual Earn Interval.

Maximum Balance Limit Configuration

Maximum Balances limits can be set for each Accrual Category rule. Configuring maximum balances for accrual category rules includes setting the max balance limit, when max balance actions are triggered, and what happens when max balance has been reached.

When max balance is reached a warning will appear on the employee's Leave Calendar.

Table 3.4. Accrual Category Rule Fields for configuring Max Balances

FieldDescription
Max Balance FlagThe Accrual Rule has a Max Balance limit
Max BalanceThe amount of accrued leave that will trigger maximum balance action.
Max Balance Action FrequencyWhen a Max Balance transaction may occur. Leave Approve: When a Leave Calendar or Time Detail is submitted for approval max balance transaction will be triggered. Year End: When the Leave Calendar or Time Detail prior begining of the Leave Plan's Calendar Start date is submitted for approval max balance transaction will be triggered. On Demand: Once maximum balance is reached the employee has the option to request the Action at Max Balance (Transfer or Payout)
Action at Max BalanceDetermines the type of transaction that will occure when Max Balance is reached and triggered by the Max Balance Action Frequency. Transfer: Triggers a Balance Transfer document. Payout: Triggers a Payout document. Lose: Leave over the max balance limit will be forfieted.

Action at Max Balance: Transfer

Employees will be prompted for a Balance Transfer document populated with the Accrual Rule's values. This document will be routed for approval to the employee's Work Area approver and Department Payroll Processor. Leave blocks for the amount of leave transfered and/or forfeited will appear on the Leave Calendar. All pending Balance Transfer documents must be approved before Leave Calendars can be approved.

Table 3.5. Accrual Category Rule Fields for configuring Transfer at Max Balances

FieldDescription
Max Balance Transfer to Accrual CategoryAccrual Category that will be be used to accrue the transfer.
Max Balance Transfer Conversion FactorThe leave can be transferred at a converted rate.
Max Transfer AmountMaximum amount of leave that can be transferred to the Transfer Accrual Category. Remaining balance over the max balance limit will be forfieted.

Action at Max Balance: Payout

Employees will be prompted for a Leave Payout document populated with the Accrual Rule's values. This document will be routed for approval to the employee's Work Area approver and Department Payroll Processor. Leave blocks for the amount of leave paid out and/or forfeited will appear on the Leave Calendar. All pending Leave Payout documents must be approved before Leave Calendars can be approved.

Table 3.6. Accrual Category Rule Fields for configuring Transfer at Max Balances

FieldDescription
Max Payout AmountMaximum amount of leave can be paid out.
Max Payout Earn CodeEarn code used for paying out leave. This earn code can be used for a feed to payroll system.

Action at Max Balance: Lose

Employees will be prompted with the amount of leave that will be forfeited so accrued balance is no longer at the max balance limit. All the forfeited amount will appear on the leave calendar.

Maximum Usage Limit Configuration

To define a usage limit, simply enter a value into the “Max Usage” field, relative to the selected Unit of Time for the accrual category.

With a maximum usage limit defined, an employee will not be allowed to add leave blocks to their calendar if the amount in the leave block, when added to the YTD usage (Leave Plan's Calendar Start Date) as of the requested leave date, exceeds this limit.

Note

Maximum usage can be overriden through the use of KHR Leave Management's Employee Override feature. Please see the Leave Management Administration documentation's section on Employee Overrides.

Maximum Carryover Limit Configuration

Maximum Annual Carryover Limit can be set for each Accrual Category rule. With a maximum carry over limit defined, the balance for an accrual category will automatically be adjusted when submitting a calendar containing the last day of the calendar year. This day is derived from the leave plan defined on the accrual category to which this rule is attached. This adjustment is achieved by placing a leave block in an amount of the adjustment on the employee’s calendar.

Note

Each leave plan has an automated batch carryover process job. Please see the Batch Jobs documentation for information on how to automate the carryover process.

Note

Maximum Carryover can be overriden through the use of KHR's Employee Overrides. See the Leave Management Administrative Documentation for Max Annual Carry Override configuration.

Conjunctive Rules

When combined with a maximum balance rule, a maximum carry over limit may vary its behavior based on the frequency of the balance transaction:

Leave-Approve Max Balance with Max Annual Carryover

When defined with a Leave-Approve Action, the adjustment amounts for both carryover and leave-approve actions are calculated relative to the same ending balance; the balance as of the last day of the leave plan’s calendar year. Up to four adjustment leave blocks are created with status requested, a maximum of three coming from the balance transaction and the fourth coming from the carryover adjustment.

If the max balance action is approved, the requested leave block containing the adjustment amount for carryover is re-calculated to reflect the resulting balance. If the max balance action is disapproved, the requested adjustment amount for carryover needs no correction.

Year-End Max Balance with Max Annual Carryover

When defined with a Year-End Action, any amount in excess of the carryover limit and up to the maximum balance limit will be included in the year-end balance transaction.

Multiple Accrual Category Rules

KHR Leave Managment allows accrual categories to be configured with multiple rules, each rule covering a non-overlapping service interval.

To define multiple rules on a single accrual category, each rule must have START and END values that do not overlap any other defined rule. There must also be no gaps between the end of one rule and the start of another.

System Scheduled Time Off

KHR Leave Management supports University Holiday designation via System Scheduled Time Off (SSTO). KHR's accrual service accrue the System Scheduled Time Off dates assocated with an employee's Leave Plan and Accrual Categories.

The System Scheduled Time Off Maintenance Document.

Tip

Leave Plans that give employee's paid time off for holiday's will need to create an accrual category and default earn code before entered System Scheduled Time Off records for the Leave Plan.

Table 3.7. SSTO Fields :

FieldDescription
Effective DateDate the scheduled time off record will go into effect
Earn CodeThe earn code associated with the scheduled time off.
Accrual CategoryRead-only field, populated from the accrual category field of the given earn code.
Leave PlanRead-only field, populated from the leave plan field of the given earn code / accrual category.
Accrued DateDate the holiday is available to use. The accrual service will place a System Scheduled Time Off accrual leave block on the employees leave calendar on this date.
Scheduled Time Off DateDate of the scheduled time off that is put on the calendar. If there is Scheduled Time Off Date, then the accrual service will create a usage leave block on this date. If no Scheduled Time Off Date, then the employee will have an available balance as of the accrual date (i.e. floating holiday).
LocationThe location in which this SSTO is applicable. Accepts wild card (%).
DescriptionText field used to describe the scheduled time off.
Amount of TimeThe amount of leave time available for this scheduled time off. Precision is based off Earn Code's Fractional Time Allowed field.
Unused TimeProvides options on how the amount of time can be used. No Unused Time Allowed, Transfer and Bank. If an employee is allowed to transfer or bank time the accrued usage leave block will display on the leave calendar or timesheet with the option to remove the leave block to have the time transferred or banked.
Transfer to Earn CodeIf Unused Time is Transfer, the converted amount of time will be made available for use by this earn code.
Transfer Conversion FactorConversion rate applied to the unused Amount of Time to be transferred
Premium HolidayFlag indicating whether this SSTO is a premium holiday. If checked, 'Y', gives certain employees a higher rate of pay when working the Scheduled Time Off Date.
Premium Earn CodeRegular hours recorded on this date for non-Exempt employee's with this SSTO will receive the premium earn code for time worked. This earn code may have inflate factor.
ActiveFlag indicating activitiy. If checked, 'Y', record will be active as of the effective date. if unchecked, 'N', record will become inactive as of the effective date.

Leave Blocks and Earn Codes

Leave blocks are placed on leave calendars to show accruals, usage and adjustments of leave through out the reporting period. The type of leave block along with the earn code determine how the leave balances are calculated.

Leave Block Types

  • Usage Leave Blocks: usage on Leave Calendar or Timesheet

  • Accrual: leave blocks generated by the Accrual Service

  • Balance Transfer: leave block created from Balance Transfer document

  • Payout: leave block created from Payout document

  • Carryover Adjustment: leave block created from Maximum Annual Carryover transaction

  • Leave Adjustment: leave blocks created from Leave Adjustment document

  • Donation: leave blocks created from Leave Donation document

Leave Earn Codes

All leave blocks on a leave calendar will have an Earn Code associated with it and the earn codes are associated with the employee's leave plan. The earn code's leave attributes, such as leave plan, defines the availablity of earn codes on the leave calendar and the impact the leave block has on the Accrual Category's balances.

Available Earn Codes for Leave

Earn Codes that are available for reporting leave on an employee's leave calendar or timesheet is driven by the leave attributes of the earn code (See Earn Code maintenance document) and Earn Code Security record for the earn code.

  1. All earn codes for user's Leave Plan (Principal HR Attribute) and Accrual Balance Action is Usage

    • Earn Code's with Allow Scheduled Leave are available on future leave reporting calendars.

  2. Earn Code Security record for the earn code determines if earn code is available on leave calendar and/or timesheet the roles that have permission to use the earn code.

  3. Earn Codes flagged as FMLA or Worker's Comp are available on leave calendars and/or timesheets of employees have FMLA and Worker's Comp indicators (Principal HR Attributes).

Calculating Accrual Category Balances

The leave summary provides the balances for leave on current and future leave calendars. Year to Date (YTD) calculations uses the employee's Leave Plan calendar start date. The earn code's Accrual Balance Action attribute will determine how the leave block impacts how the leave earned and leave usage balances are calculated.

YTD Earned calculates all the sum of all the accrual, balance transer, payout, donation, and the carryover adjustement (previous years leave balanced created via batch job) leave block types. This total also includes any leave blocks from the time calendar, leave calendar and leave adjustments that have an earn code with Accrual Balance Action of Adjustment.

YTD Usage is calculation of all the approved time calendar, leave calendar, and leave adjustment leave blocks with earn codes that have an Accrual Balance Action of Usage

Planned/Future Usage calculation includes all approved, requested, and planned leave blocks that are on future leave calendar and have an earn code with an Accrual Balance Action of Usage.

Chapter 4. Leave Management Administrative Tools

Balance Transfer

Balance Transfer Maintenance Document

The Balance Transfer Maintenance Document

Department, Location, and System Administrators have access to create and view Balance Transfer maintenance documents. Admins can access this document to perform transactions that are not triggered by the Accrual Category’s Max Balance limit. A new balance transfer record will create up to three leave blocks on the employee’s leave calendar as of the record's effective date.

Table 4.1. Balance Transfer fields :

FieldDescription
Effective DateDate the balance transfer will go into effect.
Principal IDIdentifier of the employee.
Transfer From Accrual CategoryThe Accrual Category to transfer the amount from.
Transfer AmountThe amount to transfer.
Forfeited AmountThe computed amount that will be forfeited.
Transfer To Accrual CategoryThe Accrual Category to transfer the amount to.
Amount TransferredThe final amount transferred.

Employee Override

Employee Override Maintenance Document

The Employee Override Maintenance Document

The system will allow for the ability to override the Accrual Category limits, such as usage, carryover, transfer or payout, for an individual employee. The system will check to see if the employee has an exception every time the logic is executed for

  • Max Balance – The system will use the indicated override value as the Accrual Category’s max balance.

  • Max Transfer/Payout Amount – When a balance transfer transaction is preformed the limit for the maximum amount available to transfer or payout will be the indicated override value.

  • Max Usage – On the employee’s leave calendar, when adding usage leave blocks the override value will be used to verify that the limit has not been exceeded. On the leave calendar summary grid, the override value will appear in the max usage column for the Accrual Category.

  • Max Annual Carryover – Annually, the max carryover is processed with approving the final leave calendar for the year. The override value will be used when processing the annual carry over leave block.

Note

No limit is needed for any of the override types. For example, if the override type of Max Usage and the Override Value is blank, the system will not apply a usage limit for this employee’s accrual category that typically has a usage limit.

Table 4.2. Employee Override fields :

FieldDescription
Effective DateDate the override will go into effect.
Principal IDIdentifier of the employee.
Leave PlanLeave Plan associated with the Principal ID and Accrual Category.
Accrual CategoryText field used to identify the Accrual Category the override will be applied to.
Type of OverrideAccrual Category limit that should be used for the Employee.
Override ValueThe new limit value to be used for the Accrual Category.
DescriptionText field used to describe the reason for the override.
ActiveStatus of the Override.

Note

Access will be restricted to System Admins.

Leave Adjustment

Leave Adjustment Maintenance Document

Leave Adjustment Maintenance Document

Ability to modify a employee’s earn code accrual balance. Restricted to System Admins or Department Admins with options to either create new or view existing donation records. On submit, a leave block will be generated and displayed on their leave calendar.

An employee new to the system may have existing leave time from previous service. To apply those hours to the employee’s new leave plan and accrual categories, Leave Adjustment document for each accrual category can be create to adjust the employee’s balances to reflect the existing hours.

Table 4.3. Leave Adjustment fields :

FieldDescription
Effective DateDate the adjustment will go into effect.
Principal IDIdentifier of the employee.
Leave PlanLeave Plan associated with the Principal ID and Accrual Category.
Accrual CategoryText field used to identify the Accrual Category the adjustment will be.
Earn CodeEarn Code associated with the Accrual Category and leave adjustment.
Adjustment AmountThe value of the leave adjustment, positive or negative.
DescriptionText field used to describe the reason for the adjustment.

Note

An employee will not have ability to modify their own leave balances.

Leave Donation

Leave Donation Maintenance Document

Leave Donation Maintenance Document

Employee's may donate leave to another employee. The donation transaction is done by the system admin with option to create new or view existing donation records. On submit leave blocks are generated for both recipient and donor that will display on their leave calendar. Leave donation may or may not be prorated according to the donor and recipient's salary. Amount Donated and Amount Received must be manually entered and is what will be removed/added from the designated Accrual Categories.

Table 4.4. Leave Donation fields :

FieldDescription
Effective DateDate the Donation transaction will go into effect.
Donor's Principal IDIdentifier of the employee donating leave.
Donation Accrual CategoryAccrual Category associated with the donated Leave.
Donation Earn CodeA leave block indicating the amount donated will be recorded with this earn code.
Amount DonatedThe amount of accrued leave to be donated. Subtracted from the Donated Leave Accrual Category.
Recipient's Principal IDIdentifier of the employee receiving the donated leave.
Recipient's Accrual CategoryAccrual Category the donated Leave will be accrued to.
Recipient's Earn Code The donation accrual leave block will be recorded with this earn code.
Amount ReceivedThe amount of accrued leave to be received. Added to the Recipient's Leave Accrual Category.
DescriptionText field used to describe the reason for the Leave Donation.

Leave Payout

Leave Payout Maintenance Document

Leave Payout Maintenance Document

Payout maintenance document can be used to payout earned accruals. Department, Location, and System Administrators can use this document to preform payout transactions that are not triggered by the Accrual Category’s Max Balance limit and the payout action. Example uses of this document include payout of earned accrual at time of termination/retirement. After a Payout document is submitted leave blocks that reflect the payout transaction will be created for the appropriate Accrual Category using the effective date of the payout document. The payout earn code will need to be fed to payroll for the payout to be processed.

Table 4.5. Leave Payout fields :

FieldDescription
Principal IDIdentifier of the employee.
Earn CodeEarn code that is associated with the Payout Amount and fed to Payroll.
Effective DateDate the leave payout will go into effect.
Payout From Accrual CategoryAccrual Category to pay leave out of.
Payout AmountThe amount of leave to pay out.
Forfeited AmountComputed amount of accrued leave that will be forfeited.

Chapter 5. Batch Jobs

One of KPME's more advanced features is the ability to run calculations in the background at certain times, known as batch jobs. These batch jobs can run at any time of the day, allowing large calculations to run during the middle of the night when the system does not have much load. In KPME's case, theses batch jobs include creating timesheets and leave calendars, automatically submitting and approving these documents, and performing large accrual and carry over calculations.

Basic Setup

The KPME batch system uses Quartz (http://quartz-scheduler.org) to schedule jobs. Quartz allows scheduling of both periodic and on-demand jobs, as well as providing clustering and load balancing features. The purpose of this guide is to just cover the basics of the KPME jobs; it is expected that administrators will consult the Quartz documentation to implement more advanced Quartz features.

There is no additional setup to get batch jobs to run automatically. In the basic setup, a polling program starts up five minutes after application starts to determine whether it needs to schedule any batch jobs. It will keep doing this every five minutes until the application terminates. The batch jobs are, however, highly configurable and can be overridden in kpme-config.xml. The default setup in kpme-config-defaults.xml is as follows:

Table 5.1. Batch Job Configuration Parameters

ParameterDescriptionDefault Value
kpme.org.quartz.threadPool.threadCountThe number of threads allocated to run simultaneous jobs.5
kpme.batch.user.principalNameThe KIM principal name of the batch job user.admin
kpme.batch.startDelay.millisecondsThe start delay (in milliseconds) before batch job startup.300000
kpme.batch.repeatInterval.millisecondsThe interval (in milliseconds) between polling for new jobs to schedule.300000
kpme.batch.calendarEntriesPollingWindow.daysThe number of days to poll both before and after the current date to detect whether jobs based on calendar entries need to be scheduled.30
kpme.batch.leavePlanPollingWindow.daysThe number of days to poll both before and after the current date to detect whether jobs based on leave plans need to be scheduled.30
kpme.batch.accrual.cronExpressionThe cron expression on when to run the Accrual Service.0 0 1 1 * ? 2099
kpme.batch.leaveCalendarDelinquency.cronExpressionThe cron expression on when to send out notifications that a Leave Calendar is delinquent.0 0 1 1 * ? 2099
kpme.batch.serializer.cronExpressionThe cron expression on when to serialize Time Blocks to CSV and XML.0 0 1 1 * ? 2099

Note

The Quartz cron expressions are slightly different from normal cron expressions in that they add a seconds and an optional year field. For more information, see the Quartz Cron Tutorial.

The next section of this guide will cover exactly what types of jobs these parameters control.

Available Batch Jobs

KPME currently has several batch jobs available to run. Some of them are controlled by objects in the system (like Calendar Entry or Leave Plan), while others are controlled by cron expressions. This section will cover those in greater detail.

Calendar Entry Jobs

Many of the jobs in KPME are based on the Calendar Entry object. This object not only controls when user calendars begin and end but also when batch jobs are to be run in relation to that calendar entry in the form of dates and times. These fields can be left blank for any calendar entry, causing the batch job to not run for that calendar entry. The four available dates are as follows:

Table 5.2. Calendar Entry Job Dates and Times

Batch Job Date/Time EntryDescription
Batch Initiate Date/TimeThe date and time when to initialize timesheets or leave calendars associated with this calendar entry.
Batch End Pay Period Date/TimeThe date and time when to close timesheet clock logs associated with this calendar entry.
Batch Employee Approval Date/TimeThe date and time when to approve missed punch documents and submit timesheets or leave calendars associated with this calendar entry.
Batch Supervisor Approval Date/TimeThe date and time when to approve timesheets or leave calendars associated with this calendar entry.
Batch Payroll Approval Date/TimeThe date and time when to approve timesheets or leave calendars associated with this calendar entry and to send out FYI notification to Payroll Processors.

There are six jobs associated with Calendar Entries:

  • Initiate Job

    Initiates timesheets or leave calendars for the dates associated with this calendar entry. This job is typically run a few days before the start date of this calendar entry so these documents are ready to go when the new period starts.

  • End Reporting Period Job

    Sends a notification to all users who use leave calendars that they should submit their leave calendars so they can be reviewed by their supervisor. This is automatically sent at the end date of this calendar entry and it is the only one not configurable.

  • End Pay Period Job

    Closes all clock logs belonging to any timesheets associated with this calendar entry. The clock logs are closed at the end of the pay period and then reopened immediately after (in the next calendar entry) so that clock log times are only calculated for this calendar entry. The run time of this job is determined by batchEndPayPeriodDateTime of the calendar entry. That field is typically set to the end time of this calendar entry. The Initiate Job should be ran prior to the End Pay Period Job being run.

  • Missed Punch Approval Job

    Approves all of the missed punch documents attached to any timesheets associated with this calendar entry. This job can be manually run at anytime during the pay period but typically this job should be ran right after the end date of this calendar entry.

  • Employee Approval Job

    Submits any timesheets associated with this calendar entry to the supervisors. They job should be schedule to run at a time after the last day of pay period calendar.

  • Supervisor Approval Job

    Approves any timesheets associated with this calendar entry if they have been sent to the supervisors for approval. Prior to this job being run any initiated or saved timesheets will be routed (Employee Approval Job) for supervisor approval. Missed Punch Approval Job is ran prior to the auto approval of the work area supervisors. This job is typically run a couple days after the Employee Approval Job. If the timesheet does not require a Payroll Processor approval then these timesheets will be final.

  • Payroll Approval Job

    Approves any timesheets associated with this calendar entry if they have been sent to the Payroll Processors for approval. If there are any non-approved missed punch documents belonging to these timesheets or if any of these timesheets or leave calendars are not in a state to be approved, then the job is rescheduled until these are done. A FYI notification of the automated approve will be sent to the payroll processors. This job is typically run a couple days after the Supervisor Approval Job.

Leave Plan Jobs

The Carry Over job is based on the Leave Plan object. This object not only controls when user leave plans begin but also when the Carry Over job is to be run in relation to that leave plan in the form of dates and times. These fields can be left blank for any leave plan, causing the batch job to not run for that leave plan. The fields that control when the Carry Over job is run are called Batch Prior Year Carry Over Start Date/Time.

The Carry Over job adds leave blocks for any previous leave plan years that hold the accrued leave amounts from year to year so that the Accrual Service does not have to go back to a user's beginning service date to calculate accrued leave.

Cron Expression Jobs

Some jobs are scheduled to run via cron expressions. These cron expressions are powerful in that they can be set to run and repeat to run at any interval and at any time. The most common settings are to run nightly or monthly but many combinations are possible. These cron jobs can also be "turned off" by setting them to "0 0 1 1 * ? 2099", which is the first day of the first month in the year 2099. By default, all of these jobs are turned off since there is no way of knowing reasonable values for when an institution may want to run these.

There are three jobs controlled by cron expressions:

  • Time Block Serializer Job

    Serializes all available timeblocks to both CSV and XML.

  • Accrual Job

    Runs the Accrual Service, which calculates leave amounts for employees with eligible for accrual jobs. The job runs the accrual from the current day to furturn days up to the planning month defined in the leave plan of the employee and adds needed leave blocks on to leave calendars.

  • Leave Calendar Delinquency Job

    Sends out a notification to all users who have leave calendars that have not been submitted for some time and are now considered delinquent.

Quartz Implementation

Job scheduling information is stored in the KPME database under the QRTZ_* tables that were provided by the Quartz install. By default, every single job ever run or scheduled to be run is stored in the database. In Quartz, there are two concepts necessary to understand in order to understand how the KPME Quartz system is set up:

  • Jobs

    Jobs store the necessary information to run a process. Each Job is assigned to a Job Group, which provides additional information on how the job is grouped in the system.

  • Triggers

    Triggers are what actually schedule Jobs. They store information that allows Quartz to calculate whether a particular job has been run already or not. Each Trigger is assigned to a Trigger Group, very similar as to how Jobs are assigned to Job Groups.

The most important table in the KPME database to view when trying to understand Quartz is QRTZ_TRIGGERS. Among others, it contains four fields for the Trigger Name, the Trigger Group, the Job Name, and the Job Group, that administrators can view to see what jobs have already run and what jobs are scheduled to run.

KPME Quartz Job and Trigger Example

To understand how these four fields are populated, consider the example where the system is about to schedule an Initiate Job. The poller for the Initiate Job determines that there is a person with id "user" who needs to have a timesheet initiated for the calendar entry with id "10000" starting on January 1, 2010 at midnight GMT. The four fields are populated as follows:

  • Job Name: InitiateJob-Job-principalId=user

    The Job Name only includes the principalId since that is who the Initiate Job is being run for.

  • Job Group: InitiateJob-JobGroup-hrCalendarEntriesId=10000

    The Job Group name only includes the hrCalendarEntriesId since that is the calendar entry that is currently being processed. Several Jobs for multiple principals can be associated with this calendar entry Job Group.

  • Trigger Name: InitiateJob-Trigger-date=2010-01-01T00:00:00.000-0000

    The Trigger Name only includes the date since that is what determines when it is run.

  • Trigger Group: InitiateJob-TriggerGroup-principalId=user&hrCalendarEntriesId=10000

    The Trigger Group includes both the hrCalendarEntriesId and the principalId to make sure that when the system polls the entries again, it does not schedule this particular Job again.

This means that the timesheet is initiated for user only once for calendar entry 10000 on January 1, 2010. Other users associated with calendar entry 10000 will be scheduled for a different Job but in the same Job Group. Since only one Trigger can be associated per one Job and the combination of Trigger Name and Trigger Group must be unique in the system, then each of these other users have the same Trigger Name but a different Trigger Group with both the hrCalendarEntriesId and the principalId to meet this Quartz requirement. All four of these fields can hold up to 200 characters, so there is little chance that even long principalIds will cause inserts to fail.

Spring Configuration

Quartz's main setup is in SpringBeans.xml under "kpmeScheduler". This is where KPME sets all of its Quartz defaults and plugins. Implementers may wish to override this to provide different defaults, especially in the section "quartzProperties". More information can be found in the Quartz documentation.