Employer-sponsored and HRA demographics file errors

Process

• Files uploaded to the /to_twic SFTP folder will be processed within 1-2 hours.
• Employee records not included in the demographics file will lose access to Forma.
• Automatic notifications are not available when a file is processed, with or without errors. Forma's Customer Operations Team will reach out separately to confirm or assist you with troubleshooting. 
• Log in to Forma Admin to monitor the processing status of files. To learn more, see File Manager Guide

Troubleshooting

• There are two types of errors:
  1. File Processing Error causing the entire file to fail.
  2. Employee Update Error leading to the failure of specific rows within the file.

Work with Forma's Customer Operations Team to reload a new file as soon as possible to avoid any delays. Make sure to update the data or format in your HRIS as well to prevent errors from recurring.  

File Processing Errors & Requirements

When uploading employee demographic files to Forma, ensure the following criteria are met to avoid errors and ensure smooth processing:

1. Missing Required Columns

• All files must include 5 Required Fields as outlined here.
• Omitting any required columns will result in the file failing to process.

2. Invalid or Blank Header Names

• Header names must match the standard names listed in Appendix 1 of the File Integration Guide.

Examples of common errors:

• "Country " (extra space at the end) → Correct: "Country"
• "Legal Name-First Name" (missing spaces around hyphen) → Correct: "Legal Name - First Name"

3. Missing Data in Required Columns

• Required data must be present in each row for each required column (except Employee Email).
• Employee Email:
  • If missing, the file will be marked as Partially Processed.
  • However, the employee record will not be created or updated if the email is blank.

4. Excessive Employee Terminations (>10%)

• If more than 10% of employees are marked as terminated in the file:
  • Forma will hold the file for review to prevent unintentional terminations.
  • Example:
    • If 100 employees are currently active, and the uploaded file lists only 80, the system will assume 20 employees are terminated.
    • The file will be paused until you confirm the changes.

5. Hidden or Garbled Characters

• Files must be uploaded in .csv format and UTF-8 encoding.
• Using other encodings like UTF-7 may introduce hidden or garbled characters.
• Contact your IT team if encoding issues occur.

Employee Update Errors

1. Incorrect Country Code

• Must follow the ISO3361 Alpha-2 code or Short Name format.
• Refer to Appendix 2 > String > Country for valid entries.

2. Invalid Email Format

• A valid email must contain:
  • Display name
  • An @ symbol
  • Domain name
• See Appendix 2 > String > Email for correct formatting.

3. Incorrect Boolean Values

• For custom fields requiring Boolean values, follow formatting rules in Appendix 2 > Boolean.

4. Incorrect Date Format

• For custom fields or optional fields using dates, refer to Appendix 2 > Date for required formats.

5. Invalid Custom Field Headers

• Custom field headers must start with the word “Custom”.

Example:

• Incorrect: "Intern"
• Correct: "Custom Intern"

Note:

• Invalid custom field headers will not cause the file to fail.
• However, incorrect headers prevent Forma from ingesting the data, potentially affecting downstream processes such as funding if the field is used for benefit eligibility.

Need Assistance?

For help correcting file errors, contact your Customer Success Manager or Forma Support at [e-mail].