This article describes how to configure a client for the Merrill Lynch (Bank of America) Deduction Feedback to UKG moov definition used for 360 integration. Each client configuration will vary based on their plan specification and will need to be configured accordingly.
Configuring the UKG API with a Service Account
Before you can configure your client for the Merrill Lynch (Bank of America) 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.
Merrill Lynch Feedback File Format
The Merrill Lynch feedback file is a fixed length format where multiple deductions appear on a single record. For example, the Pre-Tax, Post-Tax and Catch Up deductions are all on the a single 10 Record. The positions for each deduction will include either the amount/percent the employee elected, or the position will be zero-filled. detamoov cannot determine if a zero-filled position denotes the employee ending a deduction, or that they have not opted into the deduction. Because of this detamoov will send zero-filled records to payroll as an ended deduction. You have the ability to filter out certain deduction codes during the moov. These directions are available in the Filter Step further on in this article.
After the UKG Premier Integration has been activated on your account, please add the Merrill Lynch (Bank of America) Deduction Feedback to UKG moov to your account by following these steps.
Once the Merrill Lynch (Bank of America) Deduction Feedback to UKG moov has been added to your account, access the moovs section on the left side menu and click on the Merrill Lynch (Bank of America) Deduction Feedback to UKG moov.
Merrill Lynch (Bank of America) may send a 11 Record which includes bonus deduction changes. detamoov doesn't send these updates and they are filtered out of the file send to payroll. During the validation step, we will notify you if an 11 Record is found on the feedback file. To ensure that you receive the notification, configure the Validation Step and provide an email address and reply to address.
To configure the 11 Records validation step, click the cog icon on Step 3: Action - Validate File and toggle the 'Use default parameters' switch off. Then enter one or more email addresses into the 'Send results to email addresses (comma separated) field, and one email address in the 'Reply To' field. Then click Save Changes.
Validate file for 65 Record - Roth Bonus
Merrill Lynch (Bank of America) may send a Roth Bonus on the 65 Record which includes bonus deduction changes. detamoov doesn't send these updates and they are filtered out of the file send to payroll. During the validation step, we will notify you if an a Roth Bonus amount is found on the 65 Record within the feedback file. To ensure that you receive the notification, configure the Validation Step and provide an email address and reply to address.
To configure the Roth Bonus validation step, click the cog icon on Step 7: Action - Validate File and toggle the 'Use default parameters' switch off. Then enter one or more email addresses into the 'Send results to email addresses (comma separated) field, and one email address in the 'Reply To' field. Then click Save Changes.
The Merrill Lynch (Bank of America) 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 - SR[ML Plan Id]
File Name Contains -
Note: make sure that the File Name Starts with field matches as this can cause issues pulling the Merrill Lynch feedback file and updating UKG.
Click Next once you have completed the ID and source section.
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.
Click OK once you have created your SFTP configuration.
Understanding How Merrill Lynch Deductions Are Sent to UKG
Because the Merrill Lynch feedback file is a fixed-length format, detamoov cannot determine if a zero-filled position indicates that the employee is ending a deduction, the employee is not participating, or the plan is not participating. Any time a zero-filled deduction is received, detamoov will create a deduction in UKG where the Start Date and End Date are set to the Effective Date from the feedback file with no amount value.
For example, if an employee is creating a new Pre-Tax of %5 Merrill Lynch will send a deduction feedback record that includes the following deductions:
Pre-Tax = 5%
After-Tax = zero-filled
Pre-Tax Catch Up = zero-filled
detamoov will then transform these into a UKG deduction and send them as follows:
The ended deductions are a result of the After-Tax and Pre-Tax Catch Up being received from Merill Lynch as zero-filled. This will occur any time detamoov receives an update for an employee where the client's plan participates in a deduction.
To limit the number of ended deductions sent to UKG (as described above), you can filter out deduction codes for deductions that your client's plan does not participate in.
To create a filter override, locate the 10 Step - Filter, expand the Filter Overrides panel, and click ADD.
The select 'Filter 1:' from the dropdown and click ADD OVERRIDE.
Click 'ADD Rule' and select 'Deduction Code' from the Input Fields dropdown. Then select the 'Value In List Of Values' Filter rule.
Using the list below, enter a comma-separate list of the deduction codes you do not want sent to UKG:
401k
401k Catch Up
401k Roth
401k Roth Catch Up
401k PostTax
For example, if you do not want 401k Catch Up and 401k PostTax sent, enter them in the 'Compare value list' field and click OK.
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 Merrill Lynch (Bank of America) deduction code for the employee, the code detamoov maps the Merrill Lynch (Bank of America) code to, and the default UKG deduction code.
Deduction Code Table
| Record Identifier | detamoov Code | UKG Deduction Code (default) |
| 10 | 401k | 401k |
| 10 | 401k Catch Up | |
| 10 | 401k AfterTax | |
| 65 | 401k Roth | Roth401k |
| 65 | 401k Roth Catch Up |
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 Merrill Lynch (Bank of America) 401k PreTax record 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 Merrill Lynch (Bank of America) Deduction Feedback to UKG moov contains 3 separate Transform steps. The following information relates to step 11 Action - Transform only.
To provide a transformation override, locate step 11 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.
Override to Add Contribution Code Mapping
Example 2: detamoov receives the Merrill Lynch (Bank of America) 401k Catch Up record and converts it to 401k Catch Up. Since we don't set a default for this code when converting to UKG, you will need to provide a transformation override to include the replacement group 401k Catch Up|[your UKG Code].
Note: The Merrill Lynch (Bank of America) Deduction Feedback to UKG moov contains 3 separate Transform steps. The following information relates to step 11 Action - Transform only.
To provide a transformation override, locate step 11 - 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, add a new group: 401k Catch Up|[your UKG Code]. If your UKG deduction code, for example, is CatchUp, then we would include the following and 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 Merrill Lynch (Bank of America) Deduction Feedback moov contains 3 separate Transform steps. The following information relates to step 11 Action - Transform only.
To provide a transformation override, locate step 11 - 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.
Skip Step - UKG Retirement 360
Merrill Lynch (Bank of America) will send deduction feedback files even if no deductions or loan changes were made. This will result in a blank deduction feedback file. When this occurs, detamoov can skip the UKG Retirement 360 step. To activate the skip step, locate the Action - UKG Retirement 360 step and select "Skip step if no data to process" from the Skip Step dropdown.
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 - This field can be left blank as Loan deductions are sent in a separate feedback file
You can also enter in one or more email addresses in the Error Messages Email. If left blank, all detamoov users on your account with administrator rights 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.
Merrill Lynch (Bank of America) will send deduction feedback files even if no deductions or loan changes were made. This will result in a blank deduction feedback file. When this occurs, detamoov can skip the Send File step. To activate the skip step, locate the Action - Send File step and select "Skip step if no data to process" from the Skip Step dropdown.
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.
