You are using an unsupported browser. Please update your browser to the latest version on or before July 31, 2020.
close
You are viewing the article in preview mode. It is not live at the moment.
Home > moovs > How to configure a moov - Retirement to Payroll > Retirement To UKG > How to configure the Fidelity Deduction Feedback to UKG moov
How to configure the Fidelity Deduction Feedback to UKG moov
print icon

This article describes how to configure a client for the Fidelity 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 Fidelity 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.

 

Create an SFTP Account in detamoov

 

Fidelity will send the deduction feedback file to detamoov via SFTP.  To create an SFTP account, make sure you are logged in with an administrator level account. Click on your initials in the top right corner and select the Admin Console link.

 

 

Within the Admin Console, select the Settings tab and click on the SFTP row. Once the SFTP area expands, click the Add button to add a new SFTP account.

 

 

The side sheet will be where you'll enter information on your new SFTP account. All fields are required. Here's some information on each field:

 

  • Username: required, cannot contain spaces and must be unique across all SFTP accounts.
  • Password: required and must adhere to the standard detamoov password requirements.
  • Confirmation password: required and must match the password field exactly (case sensitive).
  • Description: required and used to describe why you're creating this account.

Once you've entered all the information above, click Save and your account will be created.

 

Provide Fidelity with the SFTP credentials created above to allow them to send the deduction feedback files for your client.

 

Host: sftp.prod.detamoov.com

Port: 22

Username: username created above

Password: password created above

 

Adopt the moov

 

After the UKG Premier Integration has been activated on your account and the SFTP account has been created, please add the Fidelity Deduction Feedback to UKG moov to your account by following these steps.

 

Once the Fidelity Deduction Feedback to UKG moov has been added to your account, access the moovs section on the left side menu and click on the Fidelity Deduction Feedback to UKG moov.

 

 

Send File Settings

 

The Fidelity 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.

 

Configure a client

 

In the moov configuration section, click the Add button to add a new client to the moov.

 

 

Complete the ID and source

 

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 - odc[Fidelity Plan ID]

File Name Contains - def

 

Note: make sure that the File Name Starts with field matches as this can cause issues pulling the Fidelity feedback file and updating UKG.

 

 

Click Next once you have completed the ID and source section.

 

Fidelity Deduction Feedback File Format

 

The Fidelity Deduction Feedback file is sent in a fixed-length format where each deduction is identified by a Record Identifier. Below is a table showing the Fidelity Record Identifiers and the corresponding deduction type:

 

Record Identifier    Deduction Type  Notes
01  Participant Identification   
02  PreTax/AfterTax Percent  Supported
02R  Roth Percent  Supported
04  PreTax/AfterTax Dollar Amount    Supported
04R  Roth Dollar Amount  Supported
05  Status Code  
06  Spillover Percent  Not supported in detamoov 
06C  Catch Up Percent  Supported
06R  Roth Catch Up Percent  Supported
07  Spillover  Not supported in detamoov 
07C  Catch Up Dollar Amount  Supported
07R  Roth Catch Up Dollar Amount  Supported
TT1  Trailer Record  

 

Certain records are automatically sent for a participant when your client's plan has an available election, even if the participant has not made an election.  For example:

 

If Roth elections are available in the plan, the Pre-Tax/After-Tax records and Roth records will always be sent together.

 

If Roth Catch Up elections are available in the plan, the regular Catch Up records and Roth Catch Up records will always be sent together.

 

Also, Fidelity sends a changes-only file which means that if a participant changes one or more of their deferral elections, all of their deferral elections will be fed back on the feedback file.

 

Filter Override

 

The Pre-Tax and After-Tax deductions exist on the same record in the Fidelity Deduction Feedback file.  detamoov needs to create both of these deductions from the record as we have no way of knowing if your client's plan has one or the other, or both.  So we create a filter to remove the After-Tax record by default and allow you to override the default settings.

 

Remove the After-Tax filter

 

If your client's plan has an After-Tax contribution then you will need to remove the default filter rule to allow detamoov to send the appropriate deduction.

 

To create a filter override locate the Action - Filter step, expand the Filter Overrides section and click ADD.

 

 

Next, select Filter 2: Deduction Code and click Add Override.

 

 

Then on the right-hand side, hover over the Deduction Code | STRING field and click the trash can icon.

 

 

Then click OK.

 

 

Add a Pre-Tax filter

 

If your client's plan has an After-Tax contribution, but doesn't have a Pre-Tax contribution, then you will need to change the default filter rule to allow detamoov to send the appropriate deduction.

 

To create a filter override locate the Action - Filter step, expand the Filter Overrides section and click ADD.

 

 

Next, select Filter 2: Deduction Code and click Add Override.

 

 

Then on the right-hand side, replace the text "401k PostTax" with the text "401k" and click OK.

 

 

UKG Deduction Code Transformation Override

 

Fidelity records are transformed by detamoov and the deduction code is set by default for the 401k and 401k Roth deductionsIf your UKG deduction codes for your client are different than the default values in the table below, or the plan has a deduction that detamoov does not set a default for, you will need to create a transformation override to update the mappings. 

 

The table below shows the Fidelity deduction code for the employee, the code detamoov maps the Fidelity code to, and the default UKG deduction code. 

 

Deduction Code Table

 

Fidelity Record Identifier   Fidelity Deduction  detamoov Code UKG Deduction Code (default)
02  Pre-Tax Percent   401k  401k
02  After-Tax Percent    401k PostTax  
04  Pre-Tax Dollar Amount   401k  401k
04  After-Tax Dollar Amount     
02R  Roth Percent  401k Roth  Roth401k
04R  Roth Dollar Amount  401k Roth  Roth401k
06C  Pre-Tax Catch Up Percent   401k Catch Up  
06R  Roth Catch Up Percent  401k Roth Catch Up    
07C  Pre-Tax Catch Up Dollar Amount    401k Catch Up  
07R  Roth Catch Up Dollar Amount  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 Fidelity Record 02 for the Pre-Tax contribution 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 Fidelity Deduction Feedback to UKG moov contains 4 separate Transform steps.  The following information relates to step 7 Action - Transform only.

 

To provide a transformation override, locate step 7 - 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 Fidelity Record 06C for the Pre-Tax Catch Up contribution 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 Fidelity Deduction Feedback to UKG  moov contains 4 separate Transform steps.  The following information relates to step 7 Action - Transform only.

 

To provide a transformation override, locate step 7 - 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.

 

Note: this field is case-sensitive, so make sure that the Replacement group matches the detamoov code and your UKG deduction code exactly.

 

 

Repeat this process for any other Fidelity deduction codes that your client's plan uses.

 

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 Fidelity Deduction Feedback to UKG moov contains 4 separate Transform steps.  The following information relates to step 7 Action - Transform only.

 

To provide a transformation override, locate step 7 - 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.

 

 

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:

 

 

  1. Company Short Name - the company short name in UKG
  2. 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
  3. Loan Deduction Codes - this field can be left blank as Fidelity sends loan deduction changes in a separate 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.

 

Send File Step Override

 

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.

 

Plans with Fidelity Loans

 

Principal sends the updates to loans in a separate file and requires that you configuration the Fidelity Loan Deduction to UKG moov.  If your client's plan has loans, please see the How to configure the Fidelity Loan Feedback to UKG moov article.

scroll to top icon