Add GUI Reporting Option – Result Forms per Form State

[JohnMwashuma]

Context

System administrators and operations managers have highlighted the need for a dedicated reporting option that displays the number of result forms grouped by their processing state. Currently, while the system tracks each form’s state using the form_state (an EnumIntegerField based on the FormState enum), there is no GUI report that summarizes how many forms are in each state (e.g., Intake, Data Entry, Corrections, Quality Control, Archiving, Audit, etc.). This reporting gap makes it difficult to monitor workflow progress, identify processing bottlenecks, and optimally allocate resources.

Current Issues Identified:

• Lack of Visibility:
  Administrators cannot quickly ascertain the distribution of result forms across different states, hindering real-time monitoring of the processing pipeline.
• Bottleneck Identification:
  Without state-specific counts, it's challenging to pinpoint stages that are experiencing delays or backlogs.
• Inefficient Resource Allocation:
  The absence of aggregated state data makes it hard to assign clerks effectively across the various stages.
• Operational Oversight:
  There is no straightforward dashboard or report that reflects the current state of result forms, making proactive management difficult.

To address these issues, a new reporting option must be added to the GUI that aggregates and displays the number of result forms per state using the form_state field.

---

Proposed Changes

• Develop a dashboard that displays the number of result forms in each processing state (e.g., Intake, Data Entry 1, Data Entry 2, etc.).

• Implement filtering options to view counts by date range, center, or other relevant parameters.

• Allow users to drill down into each state to see a list of forms currently in that state

• Provide export functionality to download the data in CSV format

---

Proposed Implementation

1️⃣ Create a Backend Report View for Result Forms by State

✅ Develop a new class-based view (FormsPerStateReportView):

• Aggregate result forms using Django’s ORM by grouping on the form_state field.
• Annotate each group with a count of result forms.
• Convert the numeric form_state values into human-readable labels via the FormState enum.
• Pass the aggregated data to the report template.

2️⃣ Implement a New Template for the Report

✅ Design a new template (e.g., reports/forms_per_state.html) that:

• Displays a table with two columns: Form State and Count.
• Is styled consistently with the existing application themes.

3️⃣ Update URL Configuration

✅ Add new URL patterns to expose the report:

• Define a URL (e.g., /reports/forms-per-state/) that maps to the new report view.
• Ensure the URL is discoverable via the main navigation or reporting dashboard.

4️⃣ Navigation and Frontend Integration

✅ Integrate the new report into the existing system:

• Update navigation menus or dashboard widgets to include a link to the “Result Forms by State” report.
• Ensure seamless access for authorized users.

---

Acceptance Criteria

✅ A new report view is implemented that aggregates result forms by the form_state field using Django’s ORM.
✅ The aggregation query groups by form_state and translates integer state values into human-readable labels based on the FormState enum.
✅ A new template renders a table (and optionally a chart) displaying each form state and its corresponding count.
✅ A dedicated URL endpoint (e.g., /reports/forms-per-state/) is available and integrated into the system’s navigation.
✅ Unit tests are added to verify the correctness of the aggregation logic and the template rendering.
✅ The new report is reviewed in QA/UAT to ensure it meets user expectations and design standards.

---

Estimated Level of Effort (LOE)

Task	Complexity	Estimated Time
1. Develop the Report View with Aggregation Logic	🟡 Medium	4-6 hours
2. Create the Report Template	🟡 Medium	3-5 hours
3. Update URL Configuration & Navigation Integration	🟢 Low	2-3 hours
4. Write Unit Tests & Update Existing Tests	🟡 Medium	3-5 hours
5. QA & UAT (User Testing & Validation)	🟠 High	4-6 hours
6. Deployment & Documentation Updates	🟢 Low	2-3 hours

Total Estimated LOE: ~18-28 hours (~2-4 working days)

🚀 Effort Level: 🟡 Medium Complexity