Save Routine Forms
Save form, Upload & Synchronization Mechanism
1. Overview
This document describes the save form, upload, and synchronization mechanism for routine vaccination forms within the system. It is intended as a handover and reference document for development teams, third-party vendors, QA teams, and program stakeholders.
The mechanism ensures:
- Reliable offline-first data capture
- Controlled and predictable data uploads
- Error visibility and recoverability
- Prevention of unintended uploads due to network fluctuations
2. Purpose
The routine vaccination form lifecycle is designed to:
- Allow vaccinators to save incomplete or complete forms locally as drafts
- Provide vaccinators with explicit control over when data is uploaded
- Ensure data integrity by uploading only validated and user-approved forms
- Support retry mechanisms in case of upload failures
3. Scope
In Scope
- Draft saving and editing of routine vaccination forms
- Manual upload triggers (Single Upload / Upload All)
- Background upload service execution
- Error handling and reappearance of failed forms
Out of Scope
- Automatic uploads based on network state changes
- Real-time streaming of form data
- Backend data processing logic
4. Actors
| Actor | Description |
|---|---|
| Vaccinator | Primary user entering and uploading routine vaccination forms |
| Mobile Application | Client-side form handling and storage |
| Upload Service | Background service responsible for syncing data |
| Backend Server | Central system receiving and validating forms |
5. Form Lifecycle States
Each routine vaccination form transitions through the following states:
| State | Description |
|---|---|
| Draft | Form saved locally and available for editing |
| Ready to Publish | Form marked by user for upload |
| Uploaded | Form successfully synced with server |
| Error | Upload failed due to validation or server error |
6. Functional Flow Description
6.1 Saving Forms as Draft
- When a vaccinator saves a routine vaccination form:
- The form is stored locally on the device
- The form status is set to Draft
- The form remains visible in the Saved Forms screen
- The vaccinator may reopen and edit the form at any time
6.2 Manual Upload Triggers
The system provides two explicit upload actions:
- Single Upload
- Uploads the selected form only
- Changes form state from Draft to Ready to Publish
- Upload All
- Marks all eligible draft forms as Ready to Publish
- Initiates batch upload via background service
Once marked Ready to Publish:
- Forms are removed from the saved forms view
- Forms are queued for background upload
7. Background Upload Service
7.1 Trigger Mechanism
- The upload service runs periodically every 15 minutes (configurable)
- Each run scans for forms with status Ready to Publish only
- Draft forms are ignored by the service
Note: Upload timing is tentative and may be adjusted based on performance or operational needs.
7.2 Upload Logic
For each Ready-to-Publish form:
- Form data is packaged and sent to the backend server
- Server response is evaluated
- Form status is updated based on response
8. Error Handling & Recovery
8.1 Upload Failure Handling
If an error occurs during upload:
- The affected form:
- Is removed from the upload queue
- Reappears in the Saved Forms screen
- Is marked with an Error status
- Displays a user-readable error message
8.2 Error Resolution Flow
- Vaccinator reviews the error message
- Corrects the form data (if required)
- Re-initiates upload using Single Upload or Upload All
This ensures no data loss and full user control over retries.
9. Network Behavior
- Forms are not automatically uploaded on network state changes
- The system does not rely on on-network-change receivers
- Uploads occur only through:
- Manual user action
- Scheduled background upload service
This design prevents:
- Partial uploads
- Unexpected data transmission
- Upload storms during unstable connectivity
10. Process Flow Diagram
11. Use Cases
Use Case 1: Save Routine Form as Draft
Actor: Vaccinator
Description: Vaccinator saves a routine vaccination form without uploading it.
Main Flow:
- Vaccinator completes form
- Clicks Save
- System stores form locally as Draft
Outcome: Form is editable and visible in Saved Forms
Use Case 2: Upload Routine Form Successfully
Actor: Vaccinator
Main Flow:
- Vaccinator selects Single Upload or Upload All
- Form marked Ready to Publish
- Background service uploads form
- Server returns success
Outcome: Form is removed permanently from local draft list
Use Case 3: Upload Failure and Retry
Actor: Vaccinator
Main Flow:
- Upload attempt fails
- Form reappears with error message
- Vaccinator corrects data
- Re-uploads form
Outcome: Successful sync without data loss
12. Risks & Mitigations
| Risk | Mitigation |
|---|---|
| Accidental data loss | Draft-based local storage |
| Network instability | Scheduled uploads only |
| Duplicate uploads | State-based upload filtering |
13. Conclusion
This mechanism ensures a robust, user-controlled, and fault-tolerant approach to routine vaccination data synchronization, supporting field realities while maintaining data quality and system stability.