Error handling for CSV upload


As an EPI Manager, I want to get an error message (and reason for error) when I try to upload a CSV that does not fit the CCE catalog parameters so that I can edit my CSV to ensure that it can be uploaded to the system and become the CCE Catalog.

A good starting point to error handling scenarios would be in v2's upload code, notably the CSVParser's process() method and the UploadController's upload() method.

The contents of the errors (sting and conditions) are outlined in this ticket

Acceptance criteria

  • follow the current error handling patterns

  • We should leverage the mechanism for showing backend errors on the fronted to the user - CSV errors will be coming from the backend

  • The UI should not allow creating the upload request without providing a CSV file (file field should be mandatory on the UI) (should already be done, but check)

  • For files with wrong format (xls, pdf, whatever) we should get an error explaining that we are unable to parse the file because the format is incorrect

  • Follows OpenLMIS style guide for error messaging. (Modal pop up first with error description and then description of error on page above file input.)

  • Create test case in Zephyr that documents all validation error scenarios when uploading a file. Add link for test case to this ticket. Example step in test case: Validate file format is correct, if incorrect error stating "Incorrect file format...." is displayed. Another example: If there are errors with the file, the file is not uploaded and records are not updated.

  • Backend should follow v2 validation methods and rethrow CSV errors as ValidationMessageExceptions

  • Make sure the SuperCSV parsers for fields are handling mandatory/invalid data as constraint violations (see v2 code above)

  • If error occurs, file input is cleared.

  • If upload is successful (upload.file.successful), show user Alert Success with text "upload.file.successful = File uploaded successfully. “Number of records processed: <number of line items processed>"

  • UI follows OpenLMIS style guide for error messaging.

  • UI follows attached mockups upload UI conventions.

  • The following errors should be shown to the user when that upload error occurs:


error text

Error for if no file or empty file is uploaded

File is empty

File uploaded is not .csv

"Incorrect file format. Please upload catalog as a ‘.csv’ file."

Error in record

"Error found in row <line item number>"

Headers are incorrect

“Invalid Headers in upload file: <name of incorrect header>”

Missing mandatory column

“Missing Mandatory column in upload file: <name of missing column header>”

Header is missing

“Header for column <number of column> is missing.”


Brandon Bowersox-Johnson
August 3, 2017, 7:55 PM

This functionality was demonstrated in this Video Showcase available on YouTube:

The error-handling features look good to me!

Mateusz Kwiatkowski
August 2, 2017, 9:46 AM

I've fixed clearing input after upload because it was a quick change, probably it will be changed to something else later on if we want to be redirected to catalog item list page.

Nick Reid
August 1, 2017, 2:51 PM

Yes, the change in AC and how the error handling behaves feels right

The only part that seems odd is that there is a input/focus area around the select file button — ideally the error icon and focus area would be the button

I'd be happy fixing this as a minor bug later — but it should work/look like the adjustment reasons button in stockmanagement physical inventory — and it might be easiest to fix it and establish a component/pattern rather than doing a hack here

Joanna Bebak
August 1, 2017, 1:06 PM

I made a re-test. Now everything works correctly.

Mateusz Kwiatkowski
August 1, 2017, 12:40 PM

1. This is how our forms are behaving, in code we cannot serve empty field error, because form cannot be submitted with empty required field. I think that AC should be changed.
2. Same as above
3. I guess that I could check on the UI side if file is empty. Also adding event.preventDefault(); should not break nothing, so I will add it.
4. ^
5. I think it is correct behavior, you can clear selection with gray cross on the right side of input, left to the red circle with exclamation mark.
6. Changelog is not required in CCE modules yet because they were not released.
I think that after 3 + 4 are fixed we can close this one (not sure about 1 + 2 but I think it is OK). If you disagree please add some comments and reopen if we manage to close it earlier.



Mateusz Kwiatkowski


Rachel Powers

Story Points


Time tracking


Time remaining


Epic Link




Fix versions