Forma Admin: File Manager Guide - Testing Files

If you need help registering or logging into your Forma Admin for the first time, follow How do I access Forma Admin?

Forma Admin → File Manager > Test Files

The 'Test Files' tab under File Manager displays all files uploaded for testing. It shows the file name, processed date, number of successful records, number of errors, etc., to help you monitor each file your team has uploaded for manual testing. 

You can upload the following file types for testing, depending on what programs you offer through Forma: 

• Employer-sponsored demographics file
• Pre-tax demographics file
• Pre-tax elections file
• Pre-tax contributions file

On the summary table, you can review the following:

• File information
  • name
  • product (employer-sponsored, pre-tax)
  • date processed
  • file type (demographics, elections, contributions)
  • number of records
• Number of Successful records
• Number of Warnings
• Number of Errors

You can also download a copy of the original file by clicking the down arrow next to the file name, upload a new test file, and review file issues.

Why do I need to test files?

Testing is a crucial step before sending production data, allowing your team to verify that files:

• Meet basic file requirements
• Are in .csv format
• Is encrypted (if applicable)
• Is armored (if applicable)
• Is not empty
• Meet formatting requirements
  • Required fields are populated
  • Header names are not missing, misnamed, or duplicated
  • Data is in the correct format (ex: date, boolean, number)
• Are checked for potential errors
  • More information, refer to the following articles: Pre-tax file errors: Demographics files; Pre-tax file errors & warnings: Elections files; Pre-tax file errors & warnings: Contributions files, Employer-sponsored/HRA demographics file errors

It's important to provide accurate pre-tax plan information when testing and to send dummy data, not real employee data, in test files. 10-20 rows per file are sufficient. You may send a large file, but we only accept up to 10MB file size for better system performance

Test file data is not validated against production data, so errors may appear in production files that were not detected during testing. The primary goal of test file validation is to ensure that the file schema aligns with Forma's data specifications. However, testing does not account for every possible scenario that may arise throughout the program.

What files am I required to test?

• Pre-tax and Employer-sponsored Demographics files
• Pre-tax Elections files unless:
  • You're providing only commuter pre-tax benefits and commuter elections will be done on Forma
• Pre-tax Contributions files unless:
  • All plans have auto-deposit enabled and you do not offer an HSA
  • You are only offering FSA/LPFSA
  • In other words, if you (1) offer an HSA or (2) offer a DCFSA, Transit, or Parking without auto-deposit, a Contributions File is required.

Upload a test file 

To get started, log in to Forma Admin and select “File Manager” on the left-hand side.

1. Go to “Test files” on File Manager tab
2. Select “Test a file” and select the type of file you want to test.
3. Select the encryption and/or armored settings when applicable. If selected, please ensure the test file is properly encrypted or armored. Click “Test for issues.”
   •  Encryption is only applicable to pre-tax test files. Employer-sponsored test demographics file cannot be encrypted.
   • You will only see this option when your file encryption settings are on. 
   • It is recommended to follow the same settings for your test files for consistency.

4. Once the file is successfully uploaded, you should see the file in the Test Files table processing. Typically, a test file will be processed within 5-10 minutes, but it may take up to 1 hour.

5. Once the processing has completed, you will see the results on the table:
   • If the file is processed successfully with no issues, no action is required. You will see the number of successful records in a green bubble under the “Successful” column.
   • If there are warnings to be reviewed and/or updated, you will see the number of records in a yellow bubble under the "Warnings" column
   • If there are errors to be reviewed and updated, you will see the number of records in a red bubble under the “Errors” column.
     • You may see more errors than the number of records in the file. This is because a row might have more than one type of error. 
6. Sometimes, an uploaded file can completely fail to process. If the file fails, the system will display a failure message. If this is the case, please upload a new file. Common reasons a file would fail include:
   • The file should be encrypted but is not
   • The file should not be encrypted but is
   • The file should be armored but is not
   • The file is empty

Review issues

When there are issues in the test file, you will see a “Review issues” button in the table. Click the link for more information.

On the review page, you can preview the issues from the test file. 

Next Steps

1. When a test file has issues, follow the guide to correct the issues and upload a new test file. Continue testing until the file has zero issues. Your Forma team will work closely with you during file testing.
2. On the Review Issues page, please mark the file as 'Reviewed' to indicate that it has been thoroughly assessed and corrected, and no further action is required.
3. If further assistance is needed, reach out to [e-mail] or your designated Forma team.
4. Once the test file has been successfully processed with no issues, work with Forma to schedule a production file upload.

What if I don’t have access to the File Manager?

You can use SFTP to upload test files in your SFTP > test_to_twic folder

• Please notify Forma when files are uploaded to the SFTP folder
• Your Forma team will process the test files and share the 'Issues File' with you to review