Open MSupply: Handling Invalid JSON Report Uploads

Aug 8, 2025 by ADMIN 51 views

Report Management: Handling Invalid JSON Uploads in Open mSupply

Hey guys! Let's dive into an issue we've spotted in Open mSupply's report management feature. It's all about how the system handles those pesky invalid JSON files. We're going to break down what went wrong, what should happen instead, and how you can reproduce the issue. Plus, we'll touch on why proper error handling is so important for user experience and data integrity. So, grab your favorite beverage, and let's get started!

What Went Wrong? 😲

So, here's the deal: imagine you're trying to upload a report to Open mSupply, but the JSON file you've got isn't quite right. Maybe it's missing a bracket, or a value is in the wrong format. You know, those little things that can make a computer go haywire. The problem is, when you try to upload this invalid file, the system doesn't really tell you what's up. The upload modal just kinda hangs there, and clicking the OK button feels like pressing a dead button. Frustrating, right?

Error Handling: The heart of the issue is the lack of proper error handling. When an application encounters an error, especially one as common as an invalid file format, it needs to communicate this clearly to the user. This is where error messages, or in this case, an error toast, come into play. Without this feedback, users are left in the dark, wondering what went wrong and how to fix it. This can lead to a lot of frustration and wasted time. The current behavior not only fails to inform the user but also leaves the impression that the system is unresponsive, which can erode trust in the application.

GraphQL Response: Digging a bit deeper, the GraphQL response actually does show that there's a problem. GraphQL, for those who aren't super techy, is basically a way for the front-end (what you see) and the back-end (the brains of the operation) to talk to each other. In this case, the back-end is saying, "Hey, there's something wrong with this file!" But this message isn't making its way to the user interface (UI). We need a way to surface this information in a user-friendly way.

Here’s what we observed:

No UI Indication: The most glaring issue is the absence of any visual cue or message in the UI to indicate that the JSON file is invalid. The modal window remains open, creating a sense of ambiguity and uncertainty for the user.
Non-Responsive OK Button: Clicking the OK button after selecting an invalid JSON file yields no action, further compounding the user's frustration. This lack of responsiveness makes the system appear frozen or broken.
Hidden GraphQL Error: Although the GraphQL response captures the error, this information is not relayed to the user interface. This disconnect between the back-end error detection and the front-end user experience is a critical oversight.

Check out this screenshot – it shows the GraphQL response highlighting the issue. It’s like the system knows what’s wrong, but it’s not telling us!

Expected Behavior 🤔

Okay, so what should happen when you try to upload a dodgy JSON file? Ideally, we'd want the system to be helpful and informative. That means popping up an error message – what we call an "error toast" – that tells you exactly what's wrong. Think of it like a friendly heads-up from the system, saying, "Oops! There's something not quite right with this file. Can you double-check it?"

User Experience: The expected behavior is centered around providing a seamless and intuitive user experience. Instead of leaving the user guessing, the system should proactively communicate any issues. This not only reduces frustration but also guides the user towards resolving the problem quickly and efficiently. A well-designed error message can transform a potential point of confusion into an opportunity for learning and improvement.

Immediate Feedback: The error toast should appear immediately after the system detects an issue with the JSON file. This immediate feedback is crucial for maintaining the user's workflow and preventing unnecessary delays. By providing instant validation, the system ensures that users are aware of any problems before proceeding further.

Clear and Concise Messaging: The error message should be clear, concise, and easy to understand. Technical jargon should be avoided in favor of simple language that the average user can comprehend. The message should specifically identify the issue (e.g., "Invalid JSON format") and, if possible, suggest a course of action (e.g., "Please check the file for syntax errors").

Error Toast: The most effective way to communicate these errors is through an error toast—a small, non-intrusive popup that appears briefly on the screen. Error toasts are ideal because they provide immediate feedback without disrupting the user's current activity. They are attention-grabbing but also disappear automatically after a few seconds, preventing them from becoming a nuisance.

So, the ideal scenario is this:

You select an invalid JSON file.
The system instantly recognizes the issue.
A friendly error toast pops up, telling you what's wrong.
You fix the file and try again. Success!

How to Reproduce 🔨

Want to see this issue in action? Here’s how you can reproduce it:

Head to Central Server: Fire up your Open mSupply Central Server.
Navigate to Reports: Go to the “Manage” section and then click on “Reports”.
Upload Reports: You'll see an option to upload reports. Click on it.
Select Invalid JSON: Choose a JSON file that you know is invalid. Maybe it’s missing a curly brace or has some other syntax error.
Click OK: Hit that OK button and… nothing! The modal stays open, and you're left scratching your head.

By following these steps, you can easily see the issue for yourself and understand the importance of proper error handling.

Your Environment 🌱

To help the developers squash this bug, it’s super useful to know your environment details. This includes:

Open mSupply Version: Which version of Open mSupply are you running?
Legacy mSupply Central Server Version: What version of the Central Server are you using?
Platform: Are you on Android, a browser (and which one?), desktop (Windows or macOS), or a server?
Database Type: Are you using PostgreSQL or SQLite3?

This information helps the team pinpoint the issue and get it fixed faster. Think of it as giving them the clues they need to solve the mystery!

Importance of Proper Error Handling

Guys, let’s talk about why proper error handling is super important. It's not just about making things look pretty (though that's a bonus!). It's about creating a smooth, reliable, and trustworthy system. Here’s why it matters:

User Experience: First and foremost, it’s about user experience. Imagine using an application where things go wrong, and you have no clue why. Frustrating, right? Clear error messages help users understand what’s happening and how to fix it. This keeps them happy and productive.

Data Integrity: Error handling also plays a crucial role in data integrity. By catching errors early, we can prevent bad data from entering the system. For example, if a JSON file is invalid, we don’t want to import it and potentially mess up our reports. A good error message can stop this in its tracks.

Trust and Reliability: When a system handles errors gracefully, it builds trust. Users are more likely to rely on an application that gives them clear feedback and prevents them from making mistakes. This is especially important in critical systems like Open mSupply, where accurate data is essential.

Debugging and Maintenance: Proper error handling also makes life easier for developers. When errors are clearly reported, it’s much easier to debug and fix issues. This means a more stable and maintainable system in the long run.

In short, error handling is not just a nice-to-have feature – it’s a fundamental requirement for any robust application. It ensures a better user experience, protects data integrity, builds trust, and simplifies maintenance.

Possible Solutions

Alright, let's brainstorm some ways we can tackle this issue. Here are a few ideas for how we can improve the handling of invalid JSON uploads in Open mSupply:

Implement an Error Toast: This is the most straightforward solution. When the system detects an invalid JSON file, we should display an error toast. This toast should be clear and concise, telling the user exactly what's wrong. For example, it could say, “Invalid JSON file: Please check the file for syntax errors.”
Client-Side Validation: We can add client-side validation to check the JSON file before it’s even uploaded to the server. This means the system would validate the file in the user's browser, providing immediate feedback. This approach can save time and reduce server load.
Detailed Error Messages: The error message should be as specific as possible. Instead of just saying “Invalid JSON,” it could point out the exact line and character where the error occurs. This would make it much easier for users to fix the problem.
Prevent Modal Hang: We need to make sure the modal doesn't hang when an error occurs. If there’s an issue, the modal should close, and the error toast should be displayed. This prevents the user from getting stuck in a non-responsive state.
Log Errors: It’s also a good idea to log errors on the server-side. This helps developers track down issues and improve the system over time. Logged errors can provide valuable insights into the types of problems users are encountering.
User-Friendly Guidance: Along with the error message, we could provide guidance on how to fix the issue. This could include a link to a help article or a brief explanation of common JSON errors. The goal is to empower users to resolve the problem themselves.

By implementing these solutions, we can make the report management process in Open mSupply much smoother and more user-friendly. Proper error handling is all about creating a system that’s both robust and forgiving, helping users succeed even when things go wrong.

Conclusion

So, guys, that’s the scoop on the invalid JSON upload issue in Open mSupply. We’ve seen what goes wrong, what should happen, and how to reproduce the problem. More importantly, we’ve discussed why proper error handling is crucial for a great user experience and a reliable system.

By implementing clear error messages, client-side validation, and user-friendly guidance, we can make Open mSupply even better. It’s all about creating a system that’s not only powerful but also forgiving, helping users succeed every step of the way.

Thanks for diving into this issue with me! Let’s keep making Open mSupply the best it can be!