This article describes how to configure the Betterment Deduction Feedback Split by Employee ID moov. This moov is intended for Betterment plans where there are multiple UKG Company Short Names within a single plan. If your client's plan does not have multiple Company Short Names, please see How to configure the Betterment Deduction Feedback to UKG moov.
To adopt the Betterment Deduction Feedback Split by Employee ID moov, click on the moovs option on the left and click the ADD button in the upper right.
Then expand the 'Retirement - Retirement to Payroll' section, click on the 'Betterment Deduction Feedback Split by Employee ID' moov and click USE THIS MOOV by scrolling down to the bottom of the right sidenav.
In the moov configuration section, click the Add button to add a new client to the moov.
Client/Entity - either select an existing client or click the + sign to create a new client.
Status - Set to Active
Expected Frequency - the client's payroll frequency
File Name Starts With - [your client's Betterment Plan ID]
File Name Contains - deferral
Note: make sure that the File Name Starts With and File Name Contains fields match as this can cause issues pulling the Betterment feedback file and updating UKG.
To automate the 360 integration, configure the SFTP schedule. Click the SFTP banner under the Trigger - SFTP Pull Data Trigger step and click Add.
On the New SFTP Configuration section on the right, select the SFTP Pull option from the Premier Integration menu. Then select either "Every X weeks" or "On certain days of the month", depending on how often you would like detamoov to check for new deduction files. We recommend that you check for feedback files at least twice a week. In the example below, we have set up a schedule to check for files twice a week on Tuesdays and Fridays.
Proper Configuration for each Company Short name in UKG
Each Company Short Name in UKG requires a Filter step override and a Name File step override. The table below describes which Filter and File Name steps need an override for the number of Company Short Names expected in the Betterment feedback file.
| Companies in File | Filter Step to Override | File Name Step to Override |
| Company Short Name 1 | Step 3 | Step 5 |
| Company Short Name 2 | Step 8 | Step 10 |
| Company Short Name 3 | Step 13 | Step 15 |
| Company Short Name 4 | Step 18 | Step 20 |
| Company Short Name 5 | Step 23 | Step 25 |
Overrides for Filter Step for each Company Short Name in UKG
To properly split the Betterment Deduction Feedback file for each Company Short Name in UKG, you will need to provide filter overrides for each Company Short Name. For example, if our client's Betterment plan has three clients that we expect in the feedback file, then we need to set filter overrides for the first three filter steps. If there are four clients, then four filter overrides are needed, and so on.
Note: the payroll company is responsible for the maintenance of the list of the External Employee ID to ensure employees are sent to the correct Company Short Name in UKG. This includes adding to the list of External Employee IDs for any recently hired employees. If an employee is not added to the list, their deduction and loan updates will not be sent to UKG.
To set a filter override, click on the Filter Overrides panel, click the ADD button.
Then select Filter 1: External Employee ID and click ADD OVERRIDE.
The default filter is set to filter out any record where the value is not 'EE_ExternalID'. You will need to replace the value 'EE_ExternalID' with a comma-separated list of the Employee IDs of the employees to be sent to a single Company Short Name in UKG and click OK.
The above filter override will remove any Employee where their External Employee ID sent from Betterment does not equal 01, 02, 03, or 04.
In the next step you will override the Name File step to ensure these employees are sent to the correct Company Short Name in UKG.
To ensure the correct employees are sent to their Company Short Name in UKG, override the Name File step to provide the Company Short Name. Locate the Name File step associated with the Filter override for the employees in the UKG client and toggle the 'Use default parameters' switch Off. Then replace the text '[Client - Override]' with the Company Short Name.
Once you have created a Filter and Name File override for each Company Short Name expected in the Betterment feedback file, scroll to the bottom of the page and Click Next. Then click Save on the summary page.
Configuring the UKG API with a Service Account
Before you can configure your client for the Betterment Deduction Feedback to UKG moov, you will need to create a UKG Premier Integration. Please review the Configuring the UKG API with a Service account article.
Create a UKG Scheduled Deduction Report
detamoov uses a Scheduled Deductions saved report that is called through the UKG API. Each company will need to have this report created before the 360 integration can be configured. See the Create the Scheduled Deduction Report for 360 Retirement Integrations article for steps on how to create this report.
Configure the client for the Betterment Deduction Feedback to UKG moov
Each Company Short Name in UKG will now need to be separately configured for the Betterment Deduction Feedback to UKG moov. To configure the Company Short Names, click on moovs and click ADD. Then expand the 'Retirement - Retirement to Payroll' and select the Betterment Feedback to UKG moov, then click USE THIS MOOV.
Once the Betterment Deduction Feedback to UKG moov has been added to your account, access the moovs section on the left side menu and click on the Betterment Deduction Feedback to UKG moov.
Importance of the Memo field on the UKG Loan Deduction
When a loan deduction record is included in the feedback file from Betterment, 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 from Betterment. 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.
In the event that no Loan ID is sent on a loan deduction record, the Betterment Deduction Feedback to UKG moov will validate if the Loan ID sent from Betterment exists and generate a notification email. If the loan deduction record creates a new loan deduction in UKG, the deduction will be created, but the Memo field will be blank.
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.
To edit the validate file step, click on the cog icon under the Action - Validate Files step on the left. Then toggle the "Use default parameters" off and enter in the email addresses you would like to receive the notification. If you would like to enter multiple email addresses, separate them with a comma. A Reply to email is also required in the event that a recipient of the notification replies to the email.
To save your parameters click on the Save Changes button.
The Betterment Deduction Feedback to UKG moov provides a notification once the moov is complete with a summary of the deduction changes that were made in UKG. The notification can be sent to any email address you wish and can also be configured to send to multiple email addresses.
To edit the send file step, click on the cog icon under the Action - Send File step on the left. Then toggle the "Use default parameters" off and enter in the email addresses you would like to receive the notification. If you would like to enter multiple email addresses, separate them with a comma. A Reply to email is also required in the event that a recipient of the notification replies to the email.
Note: these settings apply to any client configuration you set up for this specific moov. You also have the ability to configure the send file step for each client configuration if you wish to add or remove email addresses per client.
To save your parameters click on the Save Changes button.
In the moov configuration section, click the Add button to add a new client to the moov.
Client/Entity - either select an existing client or click the + sign to create a new client.
Status - Set to Active
Expected Frequency - the client's payroll frequency
File Name Starts With - [UKG Company Short Name]-[Betterment Plan Id]
File Name Contains - deduction
Note: make sure that the File Name Starts with field matches as this can cause issues pulling the Betterment feedback file and updating UKG.
Click Next once you have completed the ID and source section.
UKG Deduction Code Transformation Override
If your UKG deduction codes for your client are different than the default values in the table below, you will need to create a transformation override to update the mappings.
The table below shows the Betterment deduction code for the employee, the code detamoov maps the Betterment code to, and the default UKG deduction code.
Deduction Code Table
| Betterment Deduction Code | detamoov Code | UKG Deduction Code (default) |
| Traditional | 401k | 401k |
| Roth | 401k Roth | Roth401k |
Below is an example of a UKG Deduction. detamoov uses the value in the Code field as shown below:
Override Existing Deduction Code Mapping
Example 1: detamoov receives the Betterment deduction code Traditional and converts it to 401k. A transformation is then performed to convert 401k to the UKG code. By default, this value would be 401k. If your client's deduction code is different in UKG, say your UKG deduction code is PreTax instead of 401k, then you will need to provide a transformation override for the Deduction Code field.
Note: The Betterment Deduction Feedback to UKG moov contains 3 separate Transform steps. The following information relates to step 5 Action - Transform only.
To provide a transformation override, locate step 5 - Action Transform, expand the Transformation Overrides panel and click ADD.
Then select field 6: Deduction Code and click ADD OVERRIDE.
On the side panel that appears, in the Replacement Groups field, replace the right side of 401k|401k with your client's deduction code.
In our example, we will replace 401k with PreTax and then click OK.
UKG Earnings List Transformation Override
detamoov has a default value of "401k Earnings" set as the Earning Lists sent to UKG. If your client's plan has a different value, you will need to create an override to set this value.
Note: The Betterment Deduction Feedback to UKG moov contains 3 separate Transform steps. The following information relates to step 5 Action - Transform only.
To provide a transformation override, locate step 5 - Action Transform, expand the Transformation Overrides panel and click ADD.
Then select field 16: EE Amount Earnings List and click ADD OVERRIDE.
On the side panel that appears, replace "401k Earnings" with your Earnings List value and click OK.
If detamoov receives a Loan Goal Amount from Betterment the GoalEnabled setting will automatically be set to "Y". If you do not want GoalEnabled to be set, a transformation override is required.
Note: The Betterment Deduction Feedback to UKG moov contains 3 separate Transform steps. The following information relates to step 5 Action - Transform only.
To provide a transformation override, locate step 5 - Action Transform, expand the Transformation Overrides panel and click ADD.
Then select field 21:GoalEnabled and click ADD OVERRIDE.
Then delete the Nested-IF-THEN-ELSE rule.
Then uncheck the Deduction Goal Amount Input Field and click OK.
Configure the UKG Retirement 360 Step
To configure the UKG Retirement 360 step for you client, locate the Action - UKG Retirement 360 step, expand the UKG API panel and click ADD.
On the side panel that appears, select your UKG API Premier Integration and enter in the following parameters:
- Company Short Name - the company short name in UKG
- The Scheduled Deduction Report System ID - If you have not created this report, refer to the Create the Scheduled Deduction Report for 360 Retirement Integrations article
- Loan Deduction Codes - any loan deduction codes for this company. This field can be left blank if your client does not participate in loans
You can also enter in one or more email addresses in the Error Messages Email. If left blank, all detamoov users on your account will receive emails if the UKG API import fails.
Click OK to complete the UKG Import configuration.
At the beginning of this article you configured the send file step for the moov to send a notification once the moov had completed. You also have the ability to configure the send file step for each client configuration if you wish to add or remove email addresses per client.
To override the send file step, locate the Action - Send File step and toggle the "Use default parameters" off and enter/remove email addresses from Email Address and Reply To fields. If you would like to enter multiple email addresses, separate them with a comma.
To complete the configuration for your client, click the Next button at the bottom of the page and then the Save button on the moov summary page.
