Average Absence Calculation

Exclude absences

Multiple averaging rules

The required amount for a day of absence is calculated from 2 averaging periods:

• The Standard Time-Off rule looks back 4 weeks. It uses the time-off rule in the employee’s default employment terms.
• The Secondary Time-Off rule looks back 12 weeks. It uses the employment terms in the employee's person record. When a secondary rule is configured, the integration performs an additional calculation, compares both results, and uses the lowest average as the amount for the absence.

Exclude absences, no minimum or maximum time-off configured

Exclude absences, minimum time-off configured

Exclude absences, maximum time-off configured

Note: This integration can apply both the exclusion of absences and multiple averaging rules.

Before you configure this integration, you must do the following:

1. Configure Access to Integrations.
2. Configure the following:

• Comment: Create a comment, such as Adjusted by Average Absence Integration. Select the paycode category during configuration. See the Comments topic.

• Contributing paycodes: Create contributing paycodes that distribute hours to count toward a contributing shift. During configuration, select Make this set available in Contributing Shifts. See the Contributing Paycodes topic.

Note: Contributing paycodes are always in hours, so this integration averages absence or vacation only in hours.

• Paycode Data Access Profiles (DAP): Create DAPs that act as containers for the contributing paycodes. See the Paycode Data Access Profile topic.

• Contributing shifts: Configure a holiday credit rule to determine which shifts before a holiday are used to calculate average shifts or average wages. See the Contributing Shifts topic.

• Time-off rules apply an average of recently contracted, scheduled, or worked time as the amount of a paycode edit for part-time employees who typically work varying-length shifts.

Normal processing is replaced with the amount computed by the employee’s time-off rule when both of the following conditions occur in the timecard or the Scheduler:

• The edit is Full Contract Day, First Half Contract Day, or Second Half Contract Day.
• The employee's employment-term assignment contains a time-off rule.

Create time-off rules for each of the following averaging types:

• Use recent shifts - Contract
• Use recent shifts - Scheduled
• Use recent shifts - Worked
• Use number of - Qualified shifts
• Use number of - Qualified days
• Use number of - Fixed number

See the Time-off rules topic.

When configuring each of the Time-off rules,

• Employment terms: Add employment terms and assign them to the employees whose averaging must be calculated. During configuration, select a Time-Off Rule that you configured. See the Employment Terms topic.

Example: 12-week Average Qualified Longest Shifts - Scheduled

• Hyperfind: Configure a public Hyperfind query for the employees who are subject for averaging. See the Hyperfind queries topic.

• Custom fields: Create custom fields in the employees' people information to define the name of secondary employment terms. See the Custom Field Labels topic.

3. Get the URL, User, and Password for the APIGatewayServer.

Deploy the Average Absence Calculation integration

For more information, see the Deploy Integrations topic.

1. Open the Integration Template Designer: Select Main Menu  > Administration > Application Setup > Integrations Setup > Design Integration Templates.

   Note: If prompted, enter your Username and Password. Click Tap Log in.

2. Make sure that the Account is correct. If not, select the right account.

3. Select the Deploy tab > Integration Packs.

1. From the list in the left column, search for and select the Pro WFM Average Absence Calculation Extension integration.

2. From Unattached Environments, select the environment in which to deploy the integration process for the selected integration. Click Tap the double-left arrows button .

1. Configure Access to Integrations

Configure the Average Absence Calculation integration settings

Select the environment

1. Select the Manage tab > Atom Management.
2. Select your environment.

Select environment extensions

1. In Administration, click tap Environment Extensions.
2. In Process Filter, click tap the magnifying glass . It can take several seconds before the button becomes active.

3. Scroll to and select the integration pack: Average Absence Calculation > AverageAbsenceCalculation_iPack_v3.

Configure connection settings

Caution: If you select Use Default for the connection settings and process properties, ensure that Value is blank. If Value is not blank, that value overrides the default value whether or not Use Default is selected or cleared. Example: If the default value is abc, but Value shows xyz, the integration uses xyz regardless of the setting of Use Default.

1. Select Connection Settings.

2. From the Connection list, select and configure the following:

   Connection Settings

   Setting	Required	Actions
   AverageAbsenceCalculation_iPack_v3_APIGatewayServer	Required	To change the default API gateway server: Clear Use Default. Enter the URL to the server. Example: <tenantURL>/api
   AverageAbsenceCalculation_iPack_v3_Lookup_CRT	Required	Enable Override.
   AverageAbsenceCalculation_iPack_v3_Locale_CRT	Required	Enable Override.

Configure process properties

1. Select Process Properties.

   Caution: Do not edit the default values of the AuthenticationProperties. By default, cookies are enabled and set the values for authentication properties.

2. Select AverageAbsenceCalculation_iPack_v3_CRTConfig to set process properties that must be configured before the integration can run. This main process starts the integration process and handles errors..

Process properties

Process property name	Column header value
AverageAbsenceCalculation_iPack_v3_Lookup_CRT	Time-off Rule Name,Lookback Period Type (Weeks/Days),Lookback, Averaging Type (Worked/ Scheduled /Contract),Lookback Limit,If more than one shift exists on a day (use sum/use longest),Averaging Type Number (Fixed number/ Qualified days/ Qualified shifts),Averaging Number,Average Shift Rounding (hh:mm),Average Shift Grace (hh:mm),Minimum Time-Off Value (hh:mm),Maximum Time-Off Value (hh:mm)
AverageAbsenceCalculation_iPack_v3_Locale_CRT	Parameter Name,Locale Policy,Message,Description

Configure cross-reference tables

Cross-reference tables (CRT) are the look-up tables that the integrations use to translate parameter values. One or more data values from the source system can be used to assign one or more parameters in the destination system.

1. Select Cross Reference.
2. From the Cross Reference dropdown, select an AverageAbsenceCalculation table.

3. Select Override to:

   • Download the tables when you run the integration
   • Edit the table cells in Extensions
4. When you finish, click tap OK.

Repeat the steps for each of the AverageAbsenceCalculation tables.

AverageAbsenceCalculation_iPack_v3_Lookup_CRT: Defines how the extension extends a time-off rule.

Average Absence Calculation - Lookup CRT structure

Column name	Description
Time-off Rule Name	The name of the time-off rule as defined in the source system.
Lookback Period Type (Weeks/Days)	Whether the look-back periods are in weeks or days.
Lookback	The number of periods to look back. Example: 12 for 12 weeks.
Averaging Type (Worked/Scheduled/Contract)	The type of hours to average over recent shifts: Worked, Scheduled, or Contract hours.
Lookback Limit	The maximum number of periods to look back for data. Longer limits slow the integration runs.
If more than one shift exists on the day (use sum/use longest)	The action to take if multiple shifts are on the same day: Use Sum or Use Longest.
Averaging Type Number (Fixed Number/Qualified Days/Qualified Shifts)	Specify the averaging type of the time-off rule: Qualified shifts, Qualified days, or Fixed number. See the Time-off rules topic.
Averaging Number	Only if the averaging type is Fixed number, the Divide by number. See the Time-off rules topic.
Average Shift Rounding (hh:mm)	The rounding in the time-off rule for the calculated averages. See the Time-off rules topic.
Average Shift Grace (hh:mm)	The grace in the time-off rule for the calculated averages. See the Time-off rules topic. Example: If a calculation is 8:23, the rounding is 0:15, and the grace is 0:07, the calculation is rounded to 8:30.
Minimum Time-Off Value (hh:mm)	The value to use when the computed average absence falls below the minimum. Note: Enter the same value configured in the Minimum Time-off parameters in the Time-Off Rule.
Maximum Time-Off Value (hh:mm)	The value to use when the computed average absence falls above the maximum. Note: Enter the same value configured in the Maximum Time-off parameters in the Time-Off Rule.

AverageAbsenceCalculation_iPack_v3_Locale_CRT: Allows translation of labels and messages into different languages.

Average Absence Calculation - Locale CRT structure

Column name	Description
Parameter Name	Key for which localization is defined.
Locale Policy	Locale policy.
Message	The message that shows in the Additional Details or value of the label defined in the Run Summary section.
Description	The value shown in Additional Details.

Sample Locale CRT content

Parameter Name	Locale Policy	Message	Description
Error_AbsencePaycode	*	No Schedule or Paycode data found for absence.
Error_APIEmployees	*	Failed to Retrieve Person Number.
Error_AverageCalculated	*	Average cannot be calculated for -
Error_AveragingTypeMismatch	*	Primary and Secondary averaging type mismatch.
Error_CallBack	*	General unsuccessful response code received from API when executing call back -
Error_CustomDetails	*	Unsuccessful response code received from API when submitting custom integration details.
Error_CustomField	*	Unsuccessful response code received from API when generating non-dynamic cache when calling get custom field name by key.
Error_EmployeeTimecard	*	Unsuccessful response code received while performing Get Employee Timecard operation.
Error_EmployementTerm	*	Unsuccessful response code received from Employee Terms Multi-Read.
Error_ExcludedAbsences	*	Excluded Absences not found on -
Error_ExecuteHyperfind	*	Non-successful response code received when executing Hyperfind. Please validate Hyperfind details.
Error_Invalid_Emp_Status	*	Invalid Employment Status (Not Applicable).
Error_InvalidEmployees	*	Invalid person numbers.
Error_LocaleAPI	*	Unsuccessful response code received from API when generating non-dynamic cache when calling get Locale API.
Error_LookBackReached	*	Lookback maximum reached or New Hire. Average cannot be calculated for
Error_MaximumLookBackReached	*	Lookback maximum reached or New Hire. Average cannot be calculated for
Error_MaximumOverdrawLimit	*	Maximum Overdraw limit: Adjustment cannot be added for -
Error_MinimumMaximum	*	Please provide minimum value less than maximum value.
Error_MinimumMaximumFormat	*	Please provide valid input of minimum and maximum.
Error_No_Emp_Terms_Found	*	Unknown Employment Terms.
Error_NoAbsence	*	No Absences found from <AbsenceStartdate> to <AbsenceEnddate>.
Error_NoAdjustmentRequired	*	No Adjustment required for absence -
Error_NoEmployeeFound	*	Person Number not found.
Error_NoTimeOffRule	*	Time-Off Rule is not available to process Absence on <Dates>.
Error_PaycodeAbsence	*	Neither Schedule nor Paycode Data found for absence.
Error_PaycodeAccessProfile	*	Unsuccessful response code received from API when generating non-dynamic cache when calling get pay code access profile.
Error_PaycodeEditAPI	*	Unsuccessful response code received from API when performing paycode edit.
Error_PaycodeEditDelete	*	Unsuccessful response code received from Restore Old TopUp Values PaycodeEdit Delete.
Error_PayPeriodVacation	*	Unsuccessful response code received while Get Pay Period For Vacation.
Error_PersonExtension	*	Unsuccessful response code received while calling Retrieve Persons Extensions API.
Error_RetrieveSchedule	*	Unsuccessful response code received while retrieving schedule.
Error_ScheduleAPI	*	Unsuccessful response code received while retrieving schedule.
Error_SecondaryTimeOffRule	*	Secondary Time-Off Rule unavailable.
Error_TimeOffRuleUnavailable	*	Time-Off Rule unavailable.
Error_TimePeriodAPI	*	Unsuccessful response code received while retrieving time period dates.
Label_AdditionalDetails	*	Process completed with record-level errors.  Further details can be viewed by navigating to the Additional Details screen using the button below.
Label_CommentNote	*	Reason for Adjustment: <TYPE> New Average - Initial Average = Adjustment (<NEW_AVERAGE> - <OLD_AVERAGE> = <ADJUSTMENT>)
Label_CommentNotePrefix	*	Adjustment Reference
Label_CompletedMessage		Integration completed without errors.
Label_Disqualified	*	DISQUALIFIED
Label_DisqualifiedTransactions	*	Disqualified Transactions
Label_Failed	*	FAILED
Label_FailedTransactions	*	Failed Transactions
Label_IntegrationStarted	*	Integration started.
Label_IntegrationType	*	Integration Type
Label_IntegrationTypeValue	*	Integration Type Value
Label_ProcessedSourceRecords	*	Processed Source Records
Label_QualifiedTransactions	*	Qualified Transactions
Label_Success	*	SUCCESS
Label_SuccessRecord	*	Record updated successfully.
Message_NonActive	*	Current Pay Period signed off after status change to Invalid/Terminated, its Employment Status code is <CURRENT_STATUS>.
Message_SignOffStatus	*	Previous Pay Period signed off after status change to Invalid/Terminated, its Employment Status code is <CURRENT_STATUS>.
Messsage_EntryRemove	*	Entry removed due to changes required.

Custom tags available for use in messages and labels include: <AbsenceStartdate>, <AbsenceEnddate>, <Dates>, <TYPE>, <NEW_AVERAGE>, <OLD_AVERAGE>, <ADJUSTMENT>, <CURRENT_STATUS>.

After the integrations are deployed and the connection settings and process properties are configured, install the integrations to make them available for running or scheduling.

1. Select Main Menu  > Administration > Application Setup > Integrations Setup > Install Integrations.
2. Click Tap Create .
3. In Integration Name, enter a unique name, such as AverageAbsenceCalculation_iPack_v3.
4. (Optional) Enter a Description.

Note: Do not select API Integration.

5. In File Access, select None to not select a connection.
6. (Optional) If the person who runs the integration doesn't have full access to integrations, select Execute Integration with System Account. This allows the integration access to all APIs in the FAP, and the relevant permissions and data, regardless of the FAP and GDAP of the person who runs the integration.

7. (Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.

8. Email Notifications

   (Optional)

   1. Select Yes to send email and control center notifications for integration runs.
   2. Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces:

      In Progress — The integration run started and has not finished.

      Completed — The integration ran successfully without errors.

      Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.

      Completed with Errors — The integration run has errors or could not run.

9. In Skip Configuration, select None (default) to allow multiple integrations to run at the same time or with the same data without restrictions.

Note: Do not select Allow Minute Interval.

10. Integration template and parameters
    1. In Integration Template, select AverageAbsenceCalculation_iPack_v3.
    2. Click Tap Assign .
    3. In Integration Parameters, you can override default settings. Click Tap Create.

    4. Complete the configuration for each integration parameter value.

    5. Click Tap Save.

Repeat this step for each integration parameter that supports the Average Absence Calculation process.

Integration parameters

Parameter name	Description / User prompt / Mandatory	Template parameter	Parameter type
Custom Field Number for Multiple Averaging	The number of the custom field that defines the name of the secondary employment term in the employee’s people information. Default = 4. User prompt = No Mandatory = Yes, for multiple averaging cases.	CustomFieldNumberForMultipleAveraging	Number
Hyperfind And Location	Hyperfind or Location query for which the integration will run. Default = 1 (shown as blank) which indicates All Home and includes all active employees. User prompt = Yes Mandatory = Yes Note: Ad-hoc Hyperfinds are not supported. All Home does not include terminated and inactive employees even if they have totals during the period. To include these totals, configure a Hyperfind that includes terminated and inactive employees and select that Hyperfind in this process property. The maximum number of employees in a Hyperfind is 3500. To process more employee records, divide the population into smaller Hyperfinds to run sequentially.	HyperfindAndLocation	HyperFind
Maximum Lookback for Contract Days	The maximum number of days that the integration looks back for the contract day absences. Default = 180 days. User prompt = No Mandatory = Yes	MaximumLookbackForContractDays	Number
Pay Code Comment	The comment that identifies the adjustment reference note. Default = Adjusted by Average Absence Integration. User prompt = No Mandatory = Yes	PayCodeComment	Text
Pay Code DAP — Excluded Absences	The Data Access Profile (DAP) that includes all absence paycodes which are excluded from the average calculation. Default = Exclusion Hours. User prompt = No Mandatory = Yes	PayCodeDAPExcludedAbsences	Text
Pay Code DAP — Other Absences	The Data Access Profile (DAP) that includes all other absence paycodes to determine whether the weeks is excluded. Default = Other Absence. User prompt = No Mandatory = Yes	PayCodeDAPOtherAbsences	Text
Pay Code DAP— Worked Hours	The Data Access Profile (DAP) that includes the paycode that holds all worked time to include in the average calculation. Default = Worked Hours. User prompt = No Mandatory = Yes	PayCodeDAPWorkedHours	Text
Employee ID	Comma-separated list of employee IDs for which the integration will run. When no value is entered, the integration defaults to the Hyperfind And Location parameter. To process the integration for only a limited group of employees, enter the person numbers as defined in the source system, each separated by a comma (,) but not spaces. User prompt = Yes Mandatory = No	EmployeeIDs	Text
Use Highest Average	Specify whether to use the highest or lowest value when Multiple Averaging is enabled. Default = False: Do not use the highest or lowest value. User prompt = Yes Mandatory = Yes, for multiple averaging cases.	UseHighestAverage	Boolean

11. Ensure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations. See Configure Access to Integrations.

Run integrations to test that the configuration is set up correctly.

Run the integration

1. Select the integration:
   1. Select Main Menu  > Maintenance > Integrations. 
   2. Click Tap Run an Integration . 
   3. Select the AverageAbsenceCalculation_iPack_v3 integration from the list. Click Tap Select. 
   4. (Optional) Enter a unique Integration Run Name to make it easier to identify the run of the integration. Otherwise, the default name ends with a date and time stamp.
2. Set parameters as follows:
   • Use Highest Average: Specify whether the highest or lowest value is used when Multiple Averaging is enabled.
   • Hyperfind Name: Select a Hyperfind query of employees.
   • Person Numbers: To process data for only a limited group of employees, enter the person numbers, as defined in the source system, each separated by a comma (,) but no spaces.

     Example: For 3 employees, enter 13997,15556,20012

3. Select the following:

   • Run Integration: If this is the first time this integration is being run.
   • Re-Run: If this integration has been run before, and the status is not In-Progress, you can run the integration again without entering the parameter values again. Click Tap Yes to continue, or No to not run the integration and to return to the parameter settings.

4. Wait for the confirmation that the integration completed or failed. Close the panel.
5. Click Tap Refresh . 
6. To see details, select the integration run. Select Run Summary.

Check the results

Status indicators

•  In-Progress: The run of this integration has not yet completed.
•  Completed: The integration ran successfully without errors.
•  Scheduled: This integration is scheduled to run later or repeatedly.
• (Grayed out) Scheduled but Deleted: This integration is scheduled to run, but the integration template has been deleted. When it runs, it will generate an error. To prevent this error, delete the scheduled integration run.
•  Completed with Errors: The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
•  Failed: The integration run has errors or could not run.
• To troubleshoot and resolve errors, do the following:

  Check the Run Summary for details.

  • To troubleshoot all types of errors, or if the Run Summary shows a large number of errors, click tap Go to Additional Details (if available), or click tap the Source File to open and examine the input source file.
  • (Only for import integrations) To troubleshoot and resubmit integrations that have transactional or data errors, click tap Go to Transaction Assistant.

To check the results in more detail, do the following:

1. To see detailed results, click tap the tile for the integration run.
2. Click Tap Run Summary to see the results of the integration run.

   Example Run Summary details

   Note: The available details vary by integration and configuration.

   • Integration Run Name: Name of this run of the integration.
   • Process Name: Name of any integration set that includes this integration.
   • Integration Name: Name of the installed integration.
   • Integration Reference ID: Unique identifier for this integration run (to help in troubleshooting errors).
   • User: The person or user account that ran the integration.
   • Integration Type: Import, Export, or None
   • Start Date: Date and time when the integration run started.
   • End Date: Date and time when the integration run finished.
   • Status: In-Progress, Completed, Completed with Errors, or Failed.
   • Records Processed: Number of records that were processed.
   • Records Created: Number of records that were created.
   • Errors: Number of records that failed.
   • Source Files, Output File, and Error Files: For file-based import integrations, use Manage SFTP to access the source and output files on the inbound (source) and outbound (destination) SFTP folders. See the Manage SFTP topic.

3. Log in to the destination system and ensure that the data has been correctly updated.

Note: You can schedule integrations and integration sets to run once later or at a recurring frequency. See the topic.

API details

API name	Type	Resource path	Description
Retrieve employment terms	POST	/v1/timekeeping/setup/employment_terms/multi_read	Retrieves one or more employment terms by object references.
Retrieve All Paycode Data Access Profiles	GET	/v1/timekeeping/setup/pay_codes/data_access_profiles	Retrieves a list of all Paycode Data Access Profiles.
Update Integration Execution Details	POST	/v1/platform/integrations/update_status	Updates and returns the callback instance against the provided integration execution details.
Retrieve Persons	POST	/v1/commons/persons/extensions/multi_read	Retrieves multiple person records based on search criteria.
Execute Hyperfind Query	POST	/v1/commons/hyperfind/execute
Update Timecard as Manager	POST	/v1/timekeeping/timecard	Updates an employee timecard as a manager.
Bulk Delete Paycode Edits	POST	/v1/timekeeping/pay_code_edits/multi_delete	Performs a bulk delete of paycode edits for multiple employees using a list of paycode edit IDs.
Retrieve Schedule	POST	/v1/scheduling/schedule/multi_read	Retrieves a schedule pertaining to a set of employees or locations within a specified date range.
Retrieve Timecard as Manager	POST	/v1/timekeeping/timecard/multi_read	Retrieves a list of timecards based on the employees or Hyperfind details provided.
Retrieve Employee Employment Terms	POST	/v1/scheduling/employment_terms_schedule/multi_read	Retrieves the employment terms, group shifts, group paycode edits and memberships according to the specified parameters: employee, Hyperfind, location, or schedule employment term.
Retrieve Data Element Definitions by Keys	POST	/v1/commons/data_dictionary/data_elements/multi_read	Retrieves the Data Element definitions by keys.
Retrieve Locale Policy	GET	/v1/commons/user_preferences/locale_policy?userCurrent=true	Retrieves user preferences for the current user.
Retrieve Locale Date Span	POST	/v1/commons/symbolicperiod/read	Retrieves a locale date span, or symbolic period, according to the data provided.
Retrieve Pay Period Timespans	GET	/v1/commons/pay_period	Retrieves a pay period timespan based on the pay period ID, pay rule ID, user, date, and period type.