Forms Engine & Management
Relevant source files
The following files were used as context for generating this wiki page:
The Forms Engine & Management system is a core component of the RoundingWell frontend, responsible for rendering, managing, and processing patient-related forms. It acts as a bridge between the clinical workflow and data collection, supporting complex features such as auto-saving drafts, pre-filling data from previous submissions, and handling multi-version response histories.
The engine utilizes an iframe-based architecture (specifically Form.io) to isolate the form rendering logic while maintaining tight integration with the application's state and entity services. This ensures that clinical data is captured accurately and persists even in the event of network interruptions or browser refreshes.
Sources: src/js/apps/forms/form/form_app.js, test/integration/forms/action.js:145-155, packages/care-ops-forms/index.js
Architecture and Data Flow
The system follows a modular architecture where the FormApp coordinates between the UI views and the backend services. Data flows from the API through Entity Services into specific views, which then communicate with an iframe-based form renderer.
Component Relationship
The diagram above illustrates the hierarchy of components within the Forms module. The FormApp initializes the lifecycle, while the FormContentView manages the actual iframe interaction.
Sources: src/js/apps/forms/form/form_app.js:20-50, src/js/views/forms/form/form_views.js:150-200
Form Submission Sequence
The following sequence diagram describes the process of submitting a form, including the handling of drafts and final submission.
Key Features
Draft Management & Auto-save
The system automatically captures unsubmitted work to prevent data loss. Drafts are stored both in the browser's localStorage and synced periodically to the server as "draft" status responses.
| Feature | Description | Key Path/Reference |
|---|---|---|
| Local Storage Key | unique identifier using clinician, patient, form, and action IDs | form-subm-{cId}-{pId}-{fId}-{aId} |
| Auto-save Frequency | Managed via debounce in the UI layer | test/integration/forms/action.js:155 |
| Discard Workflow | Allows users to clear local work and reload from server | src/js/i18n/en-US.yml:forms.form.formViews.storedSubmissionView |
Sources: test/integration/forms/action.js:145-160, src/js/i18n/en-US.yml:180-190
Form Prefilling Logic
Forms can be configured to pre-fill data based on various criteria to reduce manual entry.
- Flow Prefill: Uses the latest submission within the same clinical flow.
- Form ID Prefill: Pulls data from a specific previous form ID regardless of the flow.
- Action Tag Prefill: Filters for submissions associated with specific action tags (e.g.,
prefill-latest-response).
Sources: test/integration/forms/action.js:250-320
Version History
Users can view and navigate through the history of responses for a specific action.
- Read-only Mode: Historical versions are rendered in a read-only state.
- Comparison: Users can toggle between the "Current Version" and older entries via a history droplist.
Sources: src/js/views/forms/form/form_views.js:800-850, src/js/i18n/en-US.yml:165-175
Entity and API Structures
The forms system interacts with several key entities defined in the service layer.
Form Response Statuses
Responses move through several states defined in the application's static constants:
- Draft: In-progress work, not yet finalized.
- Submitted: Finalized data entry.
- Updated: A previously submitted response that has been edited.
Sources: test/integration/forms/action.js:335-345, src/js/entities-service/entities/forms.js
Configuration Options
The Form entity contains an options attribute that dictates engine behavior:
| Option | Type | Description |
|---|---|---|
read_only | Boolean | Disables all inputs and submit buttons. |
submit_hidden | Boolean | Hides the submit button even if the form is editable. |
prefill_form_id | String | ID of the form to source prefill data from. |
is_report | Boolean | Flags the form as a reporting-only tool. |
Sources: test/integration/forms/action.js:45-55, test/integration/forms/action.js:1150-1160
User Interface Components
Form Actions Sidebar
A persistent sidebar provides context and secondary actions:
- Activity Log: Shows who worked on the form and when.
- Attachments: Managed through the sidebar, allowing for PDF and image uploads associated with the form.
- Comments: Clinicians can leave notes regarding the specific form submission.
Sources: src/js/i18n/en-US.yml:330-400, test/integration/patients/patient/patient-flow.js:110-150
Responsive Layout
The FormActionsView allows users to toggle the width of the form content to accommodate different screen sizes or to focus on the form fields by hiding the sidebar.
Sources: src/js/views/forms/form/form_views.js:300-330, src/js/i18n/en-US.yml:160-170
Conclusion
The Forms Engine & Management module is a robust system designed for clinical data integrity. By combining local storage for persistence, flexible prefilling logic, and a clear versioning system, it provides a seamless experience for clinicians while ensuring that patient data is accurately captured and stored.
Sources: src/js/apps/forms/form/form_app.js, src/js/views/forms/form/form_views.js