Absence-Based Accrual Adjustment

The Absence-Based Accrual Adjustment integration extension is an automated process that adjusts employee accrual balances based on the number of calendar days that the employee is absent in a month.

Note: This integration is an extension that is developed outside the normal release schedule to meet specific customer needs; it must be installed by an Integration Consultant. To request one of these extensions, you must submit a request by way of the Gateway Request Portal for BITS, accompanied by a change order.

In organizations where employees earn accrual days by working, this extension supports a policy that reduces earned accruals when employees are absent for a period of time. The extension works for only day-based accruals.

Combined paycodes identify the penalizing hour- and day-based absences that are used to compare absent calendar days with the total number of calendar days in the month. Prorated adjustments are made directly to the accrual balance on the grant date, and then an indicative paycode and comment are added to the timecard, identifying the adjustment.

Grant adjustments are performed by looking back to previous months for unplanned absences, and forward to future months for planned absences. Calculated adjustment amounts are truncated to two digits after the decimal point; for example, 0.469 truncates to 0.46 days. Corrections are made in signed-off periods, when editing is enabled.

Use case

In an organization, full-time employees earn 25 vacation days each year. The entitlement is divided into 12 segments, granted on the first day of each month. In other words, over the year, full-time employees accrue 2.08 days each month. The extension processes accrual adjustments by comparing the number of calendar days with qualifying absences in the month.

An employee's monthly vacation grant is awarded on the first of the month. The grant assumes that the employee does not incur absences during the month. However, during a 31-day month, the employee incurs 5 days of qualifying absences. Calculations are performed as follows:

Initial grant: (31/31)*2.08 = 2.08 days.
Adjusted grant: ((31-5)/31)*2.08 = 1.74 days.
Adjustment amount: 2.08 — 1.74 = 0.34 days.

The accrual adjustment of -0.34 days is inserted on the grant date, and the timecard displays an indicative paycode with comment on the adjusted day.

Before you start

Before you configure the Absence-Based Accrual Adjustment integration, you must do the following:

Configure Access to Integrations.
Configure the following:
- Comments: Configure a comment, such as Adjusted by Integration, that has a selected category of Pay Codes. See the Comments topic.
- Combined paycodes: Configure day-based and hour-based combined paycodes identifying the qualifying absences. See the Combined Paycodes topic.
Get the URL, User, and Password for the APIGatewayServer.

Configure the Absence-Based Accrual Adjustment integration

Deploy the Absence-Based Accrual Adjustment integration
For more information, see the Deploy Integration Packs to your Atom 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.
4. From the list in the left column, search for and select the Pro WFM Absence Based Accrual Adjustment Extension integration.
  Note: If the integration does not display, select Browse Integration Packs to search for and select the iPack.
5. Click Tap Install.
6. From Unattached Environments, select the environment in which to deploy the integration process for the selected integration. Click Tap the double-left arrows button .
Configure the Absence-Based Accrual Adjustment integration settings
1. Select the environment
  1. Select the Manage tab > Atom Management.
  2. Select your environment.
2. 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: Absence Based Accrual Adjustment > AbsenceBasedAccrualAdjustment_iPack_v2.

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.

Select Connection Settings.

From the Connection dropdown list, select and configure the following:

Connection Settings

Connection Settings for the integration

Setting	Required	Actions
AbsenceBasedAccrualAdjustment_iPack_v2_APIGatewayServer	Required	To change the default API gateway server: Clear Use Default. Enter the URL to the server. Example: `<tenantURL>/api`
AbsenceBasedAccrualAdjustment_iPack_v2_AccrualPolicy_CRT	Required	Enable Override.
AbsenceBasedAccrualAdjustment_iPack_v2_Locale_CRT	Required	Enable Override.

Setting

Required

Actions

AbsenceBasedAccrualAdjustment_iPack_v2_APIGatewayServer

Required

To change the default API gateway server:

Clear Use Default.
Enter the URL to the server.
Example: <tenantURL>/api

AbsenceBasedAccrualAdjustment_iPack_v2_AccrualPolicy_CRT

Required

Enable Override.

AbsenceBasedAccrualAdjustment_iPack_v2_Locale_CRT

Required

Enable Override.

Configure process properties

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.

Select AbsenceBasedAccrualAdjustment_iPack_v2_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
_AbsenceBasedAccrualAdjustment_iPack_v2_AccrualPolicy_CRT	Accrual Profile,Accrual Code,Grant Date(mm/dd),MonthlyGrant(Y/N)
_AbsenceBasedAccrualAdjustment_iPack_v2_Locale_CRT	Parameter Name,Locale Policy,Value,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.
Note:
- If more than one row matches a reference value, the first match is the output value.
- If no match is found, the output value can be null, or the integration can produce errors.
1. Select Cross Reference.
2. From the Cross Reference dropdown list, select the AbsenceBasedAccrualAdjustment_iPack_v2 table.
3. Select Override, which allows you 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 AbsenceBasedAccrualAdjustment tables.

AbsenceBasedAccrualAdjustment_iPack_v2_AccrualPolicy_CRT: Identifies the accrual profiles and codes that will be processed by the extension.

Absence-Based Accrual Adjustment — Accrual Policy CRT

Column name	Description
Accrual Profile	The accrual profile, assigned in the people record, to which the adjustment applies. The value must adhere to the same locale as the user who initiates the integration. Caution: The value must adhere to the same locale as the user who initiates the integration.
Accrual Code	The accrual code adjusted by the extension. The value must adhere to the same locale as the user who initiates the integration. Caution: The value must adhere to the same locale as the user who initiates the integration.
Grant Date(mm/dd)	The accrual grant date, represented in mm/dd format.
Monthly Grant Date(Y/N)	The frequency of the grant. Enter Y for monthly or N for yearly.

Note:

Values must be entered in each column of every row.
The extension supports only monthly and yearly grants.
When a monthly grant falls on the last day of the month, and the grant date has been entered as 31, the integration will automatically use the last day of the month when the month contains fewer than 31 days. For example, when the monthly grant date is configured as 31, the integration will automatically check the grant on day 30 for April.

AbsenceBasedAccrualAdjustment_iPack_v2_Locale_CRT: Allows translation of messages into different languages.

Absence-Based Accrual Adjustment — Locale CRT structure

Column name	Description
Parameter Name	Key for which localization is defined.
Locale Policy	Locale Policy. Note: You can use an asterisk ( `*`) as a wildcard, but put the less-restrictive locale policy names at the bottom of the table because the integration scans cross-reference tables from the top.
Value	Message shown in Additional Details, or value of the label defined in the Run Summary section. Example: `Comment was not provided.`
Description	The description that is shown in Additional Details. Example: `The employee is not assigned a shift.`

Note:

Localization of integration extensions remains optional, but is supported.
The cross-reference table (CRT) holds all messages represented with standard English labels; these apply to all locales when the Locale is set to a wildcard (*).
Some or all messages can be translated by adding lines to the table in their preferred translation for specific locales. Messages for the most commonly used Locale Policy should be defined at the top of the CRT.
Names of the parameters in the CRT column "Parameter Name" must be used as is. If any parameter value needs to be localized for a different Locale Policy, copy the "Parameter Name" with the * Locale Policy, add a new row to the CRT with the appropriate Locale Policy, and then add the localized values in the Message (or Value) and Description CRT columns.
Do not enter values in the CRT column "Description" if it is blank.
Do not modify placeholders (<>) or the configurable values that are included in the CRT column "Message" (or "Value").

Sample Locale CRT content

Parameter Name	Locale Policy	Value	Description
Label_DisqualifiedEmployees	*	Disqualified employees
Label_FailedEmployees	*	Failed employees
Label_IntegrationExecutionId	*	Integration execution ID
Label_IntegrationType	*	Integration type
Label_IntegrationTypeValue	*	Import
Label_PartiallyUpdatedEmployees	*	Partially updated employees
Label_ProcessedEmployees	*	Processed employees
Label_UpdatedEmployees	*	Updated employees
Message_AbsencePaycodeBlank	*	Hourly- or day-type paycodes must be configured.
Message_AbsencePaycodeNotCombined	*	Absence paycode must be a combined paycode type.
Message_AccrualUpdate	*	An error occurred while updating the accruals.
Message_AdjustmentDuration365	*	The total adjustment period cannot exceed 365 days.
Message_AllEmployeeInvalid	*	All provided person numbers are invalid.
Message_BothLookBackForwardBlank	*	The Lookback Period or Look Forward Period must be configured.
Message_InvalidDayDuration	*	The Number of days passed exceeds 365-day threshold limit.
Message_CommentBlank	*	The indicative comment must be completed.
Message_CRTDataNullError	*	No data was received from the CRT.
Message_CRTDataNullErrorDesc	*	Accrual code <AccrualCode> configured in the CRT is not assigned to Accrual profile <AccrualProfile>.
Message_CRTDataValidationError	*	Error retrieving CRT data. Please check Grant Date format and monthly grant value.
Message_DefaultErrorMessage	*	Process completed with transaction errors. If Transaction Assistant is enabled, failed records can be resubmitted through Transaction Assistant.	Default error message.
Message_DefaultError	*	An error occurred while executing the integration. Please contact the system administrator.
Message_DisqualifyPersonExt	*	No accrual profile found.	The given date range does not contain Person, Accrual Profile, or Employment Terms.
Message_EmptyHyperfind	*	There are no results for the selected Hyperfind.
Message_ErrorWhileFetchingGrantAPI	*	Failed to retrieve grant.
Message_IndicativePaycodeBlank	*	Indicative paycode must be configured.
Message_InvalidDayAbsencePaycode	*	Invalid day absence paycode.
Message_InvalidAdjustmentPaycode	*	The indicative paycode was not found.
Message_InvalidComment	*	The indicative comment was not found.
Message_InvalidCommentCategory	*	The pay codes category is not assigned to the indicative comment value.
Message_InvalidHourlyAbsencePaycode	*	The hourly absence paycode was not found.
Message_InvalidIndicativePaycode	*	The indicative paycode was not found.
Message_InvalidPersonNumber	*	Invalid person number provided.	The given person number does not exist in the system.
Message_LookBackForwardIncorrectValue	*	You must enter a value between 0 and 12 for the Lookback and Look Forward Period integration parameters.
Message_NoMonthlyAccrualProfile	*	The selected employee does not have a valid accrual profile for this month.
Message_NullHyperfind	*	A Hyperfind must be selected.
Message_ParameterException	*	A parameter validation error occurred.
Message_PaycodeEdit207Error	*	An error occurred retrieving paycode edits.
Message_PaycodeNotFound	*	Paycode does not exist in the system.
Message_PaycodeUpdate	*	An error occurred when updating or adding comments to the paycode on the timecard. Use the transaction assistant to resubmit.
Message_PersonExtension400-207Error	*	No details about this person exist in the system.
Message_RetrievePaycodeTimecard207	*	An error occurred while retrieving timecard data.
Message_Threshold	*	<threshold> must be configured with a valid value.
Message_TranslatedDayValue	*	Day
Message_TranslatedHourValue	*	Hour
Message_SignedOff	*	The data for this month has been discarded because the timecard is signed-off.
Message_WithErrorsWithAdditionalDetails	*	Process completed with transaction errors. Transaction Assistant is enabled, and failed records can be resubmitted through Transaction Assistant. Additional details, such as disqualifications, may be accessible using the button below.
Message_WithoutErrors	*	Integration completed without errors.
Message_WithoutErrorsWithAdditionalDetails	*	Integration completed without transaction errors. Additional details, such as disqualifications, may be accessible using the button below.

Install the Absence-Based Accrual Adjustment integration

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.

Note:

An integration template is the configured integration that you deploy to an Atom and then install to make available for running or scheduling.
An installed integration is a single instance of an integration that is based on an integration template. When you install an integration, you can define parameters or set parameters to be defined when the integration is run.

Select Main Menu Administration > Application Setup > Integrations Setup > Install Integrations.
Click Tap Create .
In Integration Name enter a unique name, such as AbsenceBasedAccrualAdjustment_iPack_v2.
(Optional) Enter a Description.
Note: Do not select API Integration.
In File Access, select None to not select a connection.
(Optional) If the person who runs the integration does not 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.
(Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.
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.
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.

Integration template and parameters

In Integration Template, select AbsenceBasedAccrualAdjustment_iPack_v2.
Click Tap Assign .
In Integration Parameters, you can override default settings. Click Tap Create.
Complete the configuration for each parameter value.

Click Tap Save.

Repeat this step for each integration parameter that supports the Absence-Based Accrual Adjustment process.

Absence-Based Accrual Adjustment — Integration parameters

Absence Based Accrual Adjustment - Integration parameters

Parameter name	Description / Default value / User prompt	Template parameter	Parameter type
Employee IDs	A comma-separated list of specific employees for whom the integration is run. When no value is entered, the integration defaults to the Hyperfind And Location Selector 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 = Yes	EmployeeIDs	Text
Hourly Threshold (HH:mm)	Determines whether the amount of the Combined Absence Pay Code Hourly integration parameter qualifies as an absence. The value identifies the minimum time that is required in the timecard before an hourly-based paycode qualifies as an absence. Default = `00:01` User prompt = No Mandatory = Yes	HourlyThreshold(HH:mm)	Text
Hourly Rounding (HH:mm)	Determines whether the amount of the Combined Absence Pay Code Hourly integration parameter counts as a full-day or half-day absence. The value: Represents the maximum amount of time that is required in the timecard for an hourly-based paycode to qualify as a half-day absence. Must be greater than or equal to Hourly Threshold (HH:mm). Default = `04:00` User prompt = No Mandatory = Yes	HourlyRounding(HH:mm)	Text
Day Threshold	Determines whether the amount of the Combined Absence Pay Code Days integration parameter qualifies as an absence. The value identifies the minimum time that is required in the timecard before a day-based paycode qualifies as an absence. Default = `0.01` User prompt = No Mandatory = Yes	DayThreshold	Text
Day Rounding	Determines whether the amount of the Combined Absence Pay Code Days integration parameter counts as a full-day or half-day absence. The value: Represents the maximum amount of time that is required in the timecard for a day-based paycode to qualify as a half-day absence. Must be great than or equal to Day Threshold. Default = `0.5` User prompt = No Mandatory = Yes	DayRounding	Text
Indicative Pay Code	Paycode that identifies the accrual adjustment in the timecard. User prompt = No Mandatory = Yes Caution: The value must adhere to the same locale as the user who initiates the integration.	IndicativePayCode	Text
Indicative Comment	Comment attached to the Indicative Pay Code. User prompt = No Mandatory = Yes Caution: The value must adhere to the same locale as the user who initiates the integration.	IndicativeComment	Text
Lookback Period	Number of previous months for which adjustments are made. The current month is included in this value. For example, if the parameter value is set to 1, the integration processes data only for the current month. When the parameter value is set to 2, the integration processes data for the current and previous months. Default = `1` User prompt = No Mandatory = Yes	LookBackPeriod	Number
Look Forward Period	Number of future months for which adjustments are made. The current month is included in this number. For example, if the parameter value is set to 1, the integration processes data only for the current month. When the parameter value is set to 2, the integration processes data for the current and next months. Default = `3` User prompt = No Mandatory = Yes	LookForwardPeriod	Number
Hyperfind And Location Selector	Hyperfind or Location query for which the integration will run. User prompt = Yes Mandatory = Yes	HyperfindAndLocation	Hyperfind /Location
Combined Absence Pay Code Hourly	Combined paycode that controls the list of penalizing hourly-based absences. User prompt = No Mandatory = Yes Caution: The value must adhere to the same locale as the user who initiates the integration.	CombinedAbsencePaycodeHourly	Text
Combined Absence Pay Code Days	Combined paycode that controls the list of penalizing day-based absences. User prompt = No Mandatory = Yes Caution: The value must adhere to the same locale as the user who initiates the integration.	CombinedAbsencePaycodeDays	Text

Make sure 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 and test the Absence-Based Accrual Adjustment integration

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 .
  3. Select the AbsenceBasedAccrualAdjustment_iPack_v2 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 system assigns a default name, which ends with a date and time stamp.
2. Set parameters as follows:
  - Employee IDs: 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.
    For 3 employees: 13997,15556,20012
  - HyperfindAndLocation: Select a Hyperfind query of employees.
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:
1. Click Tap the tile for the integration run.
2. Click Tap Run Summary to view 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.

APIs

API Details

API Details - Absence Based Accrual Adjustment

API name	Type	Resource path	Description
Retrieve Persons	POST	v1/commons/persons/extensions/multi_read	Returns multiple person records based on search criteria.
Execute Hyperfind Query	POST	/v1/commons/hyperfind/execute	Executes a Hyperfind query by ID or qualifier, and then returns the result.
Apply Updates to Accrual Balances for Multiple Employees	POST	v1/timekeeping/accruals/updates	Updates accrual balances in bulk.
Update Timecard as Manager	POST	/v1/timekeeping/timecard	Adds, updates, or removes paycode edits.
Retrieve Timecard Data	POST	/v1/timekeeping/timecard_metrics/multi_read	Returns timecard data for a set of employees or locations.
Retrieve Timecards as Manager	POST	v1/timekeeping/timecard/multi_read	Returns a list of timecards based on the employees or Hyperfind detail provided.
Retrieve Employment Terms	POST	v1/timekeeping/setup/employment_terms/multi_read	Returns one or more employment terms by object references.
Retrieve Full Paycodes as Manager	GET	v1/timekeeping/setup/pay_codes/multi_read	Returns one or more paycodes available to the logged-in manager by object references.
Retrieve Comments as Manager	GET	/v1/commons/comments	Returns a filtered list of comments.

Version history

Version History

Version	Description
1	Initial release.
iPack_v2	The Absence-Based Accrual Adjustment integration delivery is now by way of an iPack.
iPack_v2	The Absence-Based Accrual Adjustment integration did not work as expected when locations were passed in the Hyperfind/Location Selector parameter.