Patient Outreach System
Relevant source files
The following files were used as context for generating this wiki page:
The Patient Outreach System is a specialized module designed to facilitate secure, external communication with patients. It provides a mechanism for patients to opt into services and verify their identity via One-Time Passwords (OTP) to access protected health resources, such as clinical forms and surveys. This system is distinct from the internal clinician-facing application, prioritizing high-accessibility UI/UX for mobile devices.
The system is architected around two primary workflows: Patient Opt-In, which registers patient contact details and consent, and Secure Verification, which authenticates a patient before they can interact with sensitive clinical data.
Sources: src/js/outreach/index.js, test/integration/outreach/outreach.js:14-16
Architecture and Components
The outreach system is built using the project's standard stack of Backbone, Marionette, and Marionette.Toolkit. It is modularized into sub-applications that manage specific states of the patient journey.
Component Overview
| Component | Description | Relevant Files |
|---|---|---|
| Outreach Router | Handles URL routing for /outreach/opt-in and /outreach/:id. | src/js/outreach/index.js |
| Opt-In App | Manages the state and logic for new patient contact confirmation. | src/js/outreach/apps/opt-in_app.js |
| Verify App | Orchestrates the identity verification process via SMS OTP. | src/js/outreach/apps/verify_app.js |
| Outreach Views | Provide responsive layouts for mobile viewport interaction. | src/js/outreach/views/ |
Sources: src/js/outreach/index.js, src/js/outreach/apps/opt-in_app.js, src/js/outreach/apps/verify_app.js
Patient Opt-In Workflow
The Opt-In workflow allows a patient to confirm their identity and contact information. This is typically the first point of contact where a patient provides their name, date of birth, and phone number.
Data Validation and Submission
The system requires specific fields to be filled before the submit button is enabled:
- First Name & Last Name: Basic identity markers.
- Date of Birth: Used for identity verification (Month, Day, Year selection).
- Phone Number: A valid 10-digit number is required to receive future SMS communications.
Sources: test/integration/outreach/outreach.js:25-95, src/js/outreach/views/opt-in_views.js
Opt-In Request Flow
The following diagram illustrates the interaction between the patient UI and the backend API during opt-in.
Explanation: The UI prevents submission until all fields meet the criteria, then triggers a POST request to register the patient.
Sources: test/integration/outreach/outreach.js:31-140
User Verification System
Once a patient is registered, accessing a specific health resource (like a shared form) requires verification. This process uses a two-factor authentication pattern via SMS.
Verification Steps
- Request Code: The system informs the patient that a code will be sent to their masked phone number (e.g., XXX-XXX-1234).
- SMS Delivery: The backend sends an OTP.
- Code Entry: The patient enters a 4-digit code. The UI typically provides four individual input fields that automatically advance focus as the patient types.
- Authentication: The system validates the code and provides a temporary
patient-tokenfor resource access.
Sources: src/js/outreach/views/verify_views.js, test/integration/outreach/outreach.js:142-200
Security and Sequence
The sequence below details the OTP exchange.
Outreach States and Error Handling
The system tracks various sharing states for outreach actions. These states are reflected in the clinician dashboard and determine the patient's experience when clicking an outreach link.
Sharing States
| State Key | UI Label | Description |
|---|---|---|
responded | Response Saved | The patient has completed the outreach action. |
canceled | Form Sharing Canceled | The clinician revoked access to the resource. |
error_no_phone | Missing Mobile Phone | Cannot send OTP due to missing data. |
error_opt_out | Recipient Opted Out | Patient has explicitly declined outreach. |
error_sms_failed | Mobile Phone SMS Failed | Technical failure in delivery. |
Sources: src/js/i18n/en-US.yml:careOptsFrontend.patients.patient.sidebar.action.formSharingTemplate
Error Conditions
- 404 Not Found: Occurs if a form is no longer shared. The patient sees: "This form is no longer shared. Nothing else to do here."
- 409 Conflict: Occurs if the form has already been submitted. The patient sees: "This form has already been submitted."
- 500 Unknown Error: Occurs on server failure. The system redirects to
/outreach/unknown-error.
Sources: test/integration/outreach/outreach.js:315-360
API Reference Summary
The Outreach System relies on a set of dedicated endpoints for external authentication.
| Endpoint | Method | Purpose | Key Parameters |
|---|---|---|---|
/api/outreach | POST | Patient Opt-In | first_name, last_name, birth_date, phone |
/api/outreach/otp | POST | Request OTP SMS | type (action), id (action_id) |
/api/outreach/auth | POST | Validate OTP | code, id (outreach_id), patient_id |
/api/outreach | GET | Check link status | filter[action] |
Sources: test/integration/outreach/outreach.js:86-89, test/integration/outreach/outreach.js:168-171, test/integration/outreach/outreach.js:231-236
Conclusion
The Patient Outreach System provides a secure gateway for patients to interact with their healthcare providers outside of a logged-in clinician environment. By utilizing identity verification via DOB and SMS-based OTP, it balances security requirements with the need for a low-friction user experience on mobile devices. The system's robustness is reinforced by comprehensive error handling for expired links and already-submitted resources.