Here is a list of common errors and scenarios experienced with the 360 integration to UKG.
Error: Invalid Deduction. (Deduction Code: detamoov 401k Loan)
Error: Invalid Deduction. (Deduction Code: [Invalid Code Name])
A new employee loan was created instead of updating the existing loan in UKG
A Deduction Update report was received but no changes were made in UKG
A deduction was updated/ended in UKG and there are two separate deductions showing in UKG
The Deduction update report shows an ended percent deduction as a Flat Amount
Error: Invalid Deduction. (Deduction Code: detamoov 401k Loan)
This error occurs when the employee already has active loans in UKG for all the deduction codes you entered in the Loan Deduction Codes list. Since no deduction codes are available for detamoov to create a new loan, no update is made in UKG. Please check the configuration for your client and ensure that all possible Loan Deduction Codes are available on the UKG Retirement 360 step configuration.
Error: Invalid Deduction. (Deduction Code: [Invalid Code Name])
This error occurs when the deduction codes you entered in the Loan Deduction Codes list are invalid. Please edit your client's configuration for the 360 moov and ensure that any loan deduction codes entered on the UKG Retirement 360 step are valid and entered correctly.
This error occurrs when there are no deduction codes entered in the Loan Deduction Codes list. Please edit your client's configuration for the 360 moov and ensure that any loan deduction codes entered on the UKG Retirement 360 step are valid and entered correctly.
This error occurs when the Scheduled Deductions Report System ID has not been provided on the UKG Retirement 360 step configuration. If you have not yet generated this report, please see the Scheduled Deductions Report for 360 Retirement Integrations article.
A new employee loan was created instead of updating the existing loan in UKG
This will occur when the retirement provider does not send the Loan ID value in the deduction feedback feed, or when the Loan ID does not match the existing loan deduction's Memo field in UKG.
When a loan deduction record is included in the feedback file from the retirement provider, the Loan ID is required to map to the Memo field in UKG. This is important when an existing loan deduction is either modified or a request to end the loan is sent. If the Loan ID does not match the existing loan deduction's Memo field in UKG, a new loan deduction will be created instead of modifying or ending the existing loan deduction. If the loan deduction record creates a new loan deduction in UKG, the deduction will be created, but the Memo field will be blank.
In the event that no Loan ID is sent on a loan deduction record, the UKG 360 moov will validate if the Loan ID sent from the retirement provider exists and generate a notification email.
An example of the validation report generated when a loan deduction has no Loan ID:
This shows that the first record in the deduction feedback file is a 401k Loan and that no Loan ID was found for this record.
A Deduction Update report was received but no changes were made in UKG
The UKG Retirement 360 step is a "all or none" process. This means that if any of the deduction updates fail during the UKG Retirement 360 import, none of the changes are made in UKG.
For example, if the deduction feedback sent from the retirement provider has three separate employee updates and one fails, all three will not be updated in UKG.
detamoov will send a Premier Integration email with details on the moov and the reason why it failed to import:
In the event that a deduction UKG Retirement 360 step fails, we suggest that you download the UKG format file, correct any issues, and upload the file manually through UKG.
To download the UKG format file in detamoov, click on the moovs section on the left and then click on the related UKG deduction feedback moov.
Then scroll down to the execution history and click on the execution that failed to update UKG.
On the moov execution page, locate the Action - UKG Retirement 360 step and click on the file icon to the right.
Then click the cloud icon to download a copy of the deduction feedback file.
A deduction was updated/ended in UKG and there are two separate deductions showing in UKG
The only way the UKG API can update an existing deduction is if the Begin Date and Deduction Code match in the feedback file. In most cases, the retirement provider will not send an Effective Date that matches the Begin Date in UKG.
detamoov will use the Effective Date from the feedback file to end the current deduction. The End Date of the current deduction will be updated in UKG using the Effective Date minus one day. Then, a new deduction will be created with the Begin Date set as the Effective Date from the feedback file. Here is an example of a Roth 401k deduction update:
The first row shows that the current deduction's End Date was changed using the Effective Date (11/15/2024) minus one day.
The second row shows the updated deduction where the Begin Date is the Effective Date in the feedback file.
The Deduction update report shows an ended percent deduction as a Flat Amount
When an employee has a % Of Earnings List deduction in UKG and detamoov receives a feedback file to end the deduction, the UKG API does not allow the Amount field to be set to zero or null. detamoov will use the Effective Date in the feedback file and change the existing & Of Earnings List deduction's End Date. Then a new Flat Amount deduction is created where the Effective Date in the feedback file is set to the Begin Date and End Date. This allows detamoov to set the Amount field to null, effectively ending the deduction. Here is an example of how an ended % Of Earnings List deduction will appear in UKG:
