https://github.com/Browser-Automation-Hub/epic-ehr-browser-automation
Browser automation scaffolding for Epic EHR — API alternative for MyChart, scheduling, care gaps, and clinical workflows. Puppeteer + Playwright + AnchorBrowser.
https://github.com/Browser-Automation-Hub/epic-ehr-browser-automation
ai-agents anchorbrowser browser-automation ehr epic-ehr healthcare-automation hipaa mychart nodejs playwright puppeteer web-scraping
Last synced: 2 months ago
JSON representation
Browser automation scaffolding for Epic EHR — API alternative for MyChart, scheduling, care gaps, and clinical workflows. Puppeteer + Playwright + AnchorBrowser.
- Host: GitHub
- URL: https://github.com/Browser-Automation-Hub/epic-ehr-browser-automation
- Owner: Browser-Automation-Hub
- License: mit
- Created: 2026-03-14T12:01:54.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-14T14:38:43.000Z (3 months ago)
- Last Synced: 2026-03-14T23:04:12.286Z (3 months ago)
- Topics: ai-agents, anchorbrowser, browser-automation, ehr, epic-ehr, healthcare-automation, hipaa, mychart, nodejs, playwright, puppeteer, web-scraping
- Language: JavaScript
- Size: 35.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Epic EHR Browser Automation
[](https://www.npmjs.com/package/@browser-automation-hub/epic-ehr-browser-automation)
> Automate Epic EHR — the reliable way to interact with Epic programmatically, with or without an official API.
[](LICENSE)
[](https://nodejs.org)
[](https://pptr.dev)
[](https://anchorbrowser.io)
## What This Is
**Epic EHR** (Healthcare EHR) is notoriously difficult to automate via its official API — limited endpoints, complex authentication (Azure AD / Okta), and browser-only workflows make traditional API integration a pain.
This project gives you a **complete browser automation scaffold** for Epic EHR using Puppeteer (self-hosted, open source) or [Anchor Browser](https://anchorbrowser.io) (cloud, managed, production-ready).
This system requires **MFA** (Duo Security / TOTP). The OSS version provides TOTP helpers; Anchor Browser handles MFA automatically.
## Quick Start
```bash
git clone https://github.com/Browser-Automation-Hub/epic-ehr-browser-automation.git
cd epic-ehr-browser-automation
npm install
cp .env.example .env
# Fill in your credentials in .env
node examples/basic-login.js
```
## Two Ways to Run
| Feature | Open Source (Puppeteer) | ☁️ [Anchor Browser Cloud](https://anchorbrowser.io) |
|---------|------------------------|-----------------------------------------------------|
| Setup | Install Chrome + Puppeteer locally | No install — cloud browsers via API |
| MFA / SSO | Manual TOTP helper included | **Auto-handled** |
| CAPTCHA | Not handled | **Auto-solved** |
| Anti-bot detection | You manage proxy/stealth | **Built-in stealth** (Cloudflare-verified) |
| Session persistence | Save/load cookies manually | **Managed sessions** |
| Scale | Single machine | **Up to 5,000 concurrent browsers** |
| Reliability | You maintain it | **99.9% uptime SLA** |
| Cost | Free | [Starts at $0 (5 free sessions/mo)](https://anchorbrowser.io) |
## Supported Actions
- `schedule_appointment()` — Schedule or reschedule patient appointments
- `get_patient_info()` — Extract patient demographics and encounter history
- `fill_clinical_note()` — Auto-fill clinical notes and smartphrases
- `export_care_gaps()` — Export care gap reports to CSV/JSON
- `mychart_messaging()` — Send and receive MyChart secure messages
## Use Cases
- Healthcare IT teams automating patient workflows
- EHR data extraction without HL7/FHIR
- Care gap report automation
- Clinical trial data collection
---
## Option A: Open Source (Puppeteer)
### Prerequisites
- Node.js 18+
- Google Chrome / Chromium installed
- Epic EHR account with appropriate permissions
### Installation
```bash
npm install
cp .env.example .env
```
### Configuration (`.env`)
```env
EPIC_URL=https://your-instance.epic.com/login
EPIC_USERNAME=your-username
EPIC_PASSWORD=your-password
MFA_SECRET=your-totp-secret-if-applicable
SESSION_PATH=./session.json
```
### Basic Login Example
```javascript
const { createSession } = require('./src/auth');
const { schedule_appointment } = require('./src/actions');
async function main() {
const page = await createSession();
const result = await schedule_appointment(page, { /* options */ });
console.log(result);
}
main().catch(console.error);
```
### File Structure
```
epic-ehr-browser-automation/
├── src/
│ ├── auth.js # SSO/MFA authentication (SAML, TOTP, Duo)
│ ├── session.js # Cookie & localStorage persistence
│ ├── actions.js # All automation actions
│ ├── custom-actions.js # Fluent ActionBuilder API for custom workflows
│ └── utils.js # retry(), humanDelay(), error types
├── examples/
│ ├── basic-login.js # Minimal login example (OSS)
│ └── anchor-cloud.js # Anchor Browser cloud example
├── .env.example
├── package.json
└── README.md
```
---
## Option B: ☁️ Anchor Browser (Recommended for Production)
[Anchor Browser](https://anchorbrowser.io) provides **fully managed cloud browsers** purpose-built for AI agents and automation:
- ✅ **MFA handled automatically** — no TOTP secrets needed
- ✅ **SSO sessions managed** — persistent authenticated sessions
- ✅ **Anti-bot / CAPTCHA** — Cloudflare-verified stealth browser
- ✅ **Scale instantly** — from 1 to 5,000 concurrent browsers
- ✅ **No infrastructure** — no Chrome install, no proxy management
### Setup
```bash
npm install
export ANCHORBROWSER_API_KEY=your-api-key
# Get your free API key at https://anchorbrowser.io
```
### Anchor Browser Example
```javascript
const { withAnchorBrowser } = require('./src/auth');
const { schedule_appointment } = require('./src/actions');
async function main() {
await withAnchorBrowser(async (page) => {
// MFA, SSO, CAPTCHAs all handled automatically
const result = await schedule_appointment(page, { /* options */ });
console.log(result);
});
}
main().catch(console.error);
```
See `examples/anchor-cloud.js` for a complete working example.
### Anchor Browser Pricing
| Plan | Price | Concurrent Browsers | Best For |
|------|-------|---------------------|----------|
| Free | $0 | 5 | Prototyping |
| Starter | $50/mo | 25 | Small teams |
| Team | $500/mo | 50 | Growing orgs |
| Growth | $2,000/mo | 200 | Enterprise |
[Get started for free →](https://anchorbrowser.io)
---
## Authentication
### Auth Methods Supported
This implementation handles:
1. **Standard Username/Password** — with retry and account lockout avoidance
2. **SAML SSO** (Azure AD / Okta) — intercepts the SAML redirect and completes the IdP flow
3. **MFA / TOTP** (Duo Security / TOTP) — generates TOTP codes via `otpauth` library
4. **Session Persistence** — saves cookies to disk; reuses session to avoid re-auth
### Handling Duo Security / TOTP MFA
```javascript
// In .env: MFA_SECRET=your-base32-totp-secret
// The auth module auto-generates the OTP code
const { createSession } = require('./src/auth');
const page = await createSession(); // MFA handled automatically
```
For Duo Security push-based MFA, set `MFA_TYPE=duo_push` in .env — the automation will wait for push approval.
---
## Custom Actions
Use the `ActionBuilder` fluent API to chain custom workflows:
```javascript
const { ActionBuilder } = require('./src/custom-actions');
const result = await new ActionBuilder()
.login()
.navigate('/module/path')
.waitForSelector('.content-loaded')
.extractTable('.data-table')
.run(page);
```
---
## Error Handling & Reliability
```javascript
const { retry, humanDelay } = require('./src/utils');
// Auto-retry with exponential backoff
const data = await retry(() => extractData(page), { attempts: 3, delay: 2000 });
// Human-like delays to avoid detection
await humanDelay(1000, 3000); // random delay 1-3 seconds
```
---
## Why Not Use the Official API?
Epic EHR has limited HL7/FHIR endpoints that require expensive licenses and vendor agreements. Many workflows — scheduling, notes, messaging — are UI-only.
Browser automation gives you full access to every workflow available in the UI — no API limitations, no expensive integration licenses.
---
## Production Deployment
For production workloads, we strongly recommend [Anchor Browser](https://anchorbrowser.io):
```javascript
// One-line setup — handles auth, proxies, CAPTCHAs
const { withAnchorBrowser } = require('./src/auth');
await withAnchorBrowser(async (page) => {
// Your automation here — runs in the cloud, scales automatically
});
```
**Anchor Browser** is the easiest way to run this automation in production:
- No infrastructure to manage
- Handles Duo Security / TOTP MFA automatically
- Enterprise compliance: SOC2, HIPAA, ISO27001
- [Start free at anchorbrowser.io →](https://anchorbrowser.io)
---
## Known Selectors Reference
> These CSS selectors were observed in Epic EHR web interfaces. Enterprise applications update their UIs — verify against your specific instance and submit PRs when selectors break.
| Element | Selector | Notes |
|---------|----------|-------|
| Login: username | `#j_username` | Login form |
| Login: password | `#j_password` | Login form |
| Login: submit | `#loginButton` | Login form |
| Login: mfa code | `#duo_form input[name="passcode"]` | Login form |
| schedule appointment: container | `#scheduleAppointment` | |
| schedule appointment: slot | `.appt-slot` | |
| schedule appointment: confirm | `#confirmApptBtn` | |
| schedule appointment: provider search | `#providerSearch` | |
| get patient info: search input | `#patientSearch input` | |
| get patient info: result row | `.patient-result-row` | |
| get patient info: demographics | `#demographicsTab` | |
| fill clinical note: note editor | `#noteText` | |
| fill clinical note: smartphrase | `.smartphrase-popup` | |
| fill clinical note: sign btn | `#signNote` | |
| export care gaps: reports menu | `#reportsMenu` | |
| export care gaps: care gap report | `.care-gap-report` | |
| export care gaps: export btn | `#exportReport` | |
| mychart messaging: inbox link | `a[href*="messaging"]` | |
| mychart messaging: compose btn | `#composeMessage` | |
| mychart messaging: recipient | `#messageTo` | |
| mychart messaging: message body | `#messageBody` | |
> ⚠️ Selectors are best-effort. Run `node src/utils.js --verify-selectors` to test against your instance.
---
## More Browser Automation Projects
This is part of the **[Browser Automation Hub](https://github.com/Browser-Automation-Hub)** — a collection of open-source browser automation scaffolds for systems with poor or no API support:
- [Epic EHR Browser Automation](https://github.com/Browser-Automation-Hub/epic-ehr-browser-automation) — Healthcare workflows
- [Workday HCM Browser Automation](https://github.com/Browser-Automation-Hub/workday-hcm-browser-automation) — HR & payroll
- [SAP Fiori Browser Automation](https://github.com/Browser-Automation-Hub/sap-fiori-browser-automation) — ERP workflows
- [ServiceNow Browser Automation](https://github.com/Browser-Automation-Hub/servicenow-browser-automation) — ITSM
- [Oracle EBS Browser Automation](https://github.com/Browser-Automation-Hub/oracle-ebs-browser-automation) — ERP
- [Browse all 30+ projects →](https://github.com/Browser-Automation-Hub)
## Contributing
PRs welcome! Please:
1. Add tests for new actions
2. Document new selectors (they break when Epic updates its UI)
3. Follow the `ActionBuilder` pattern for new actions
4. See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines
## License
MIT — use freely in personal and commercial projects.
---
*Built with ❤️ for developers who need to automate Epic EHR without wrestling with its API limitations. Powered by [Anchor Browser](https://anchorbrowser.io) for cloud-scale automation.*
*⭐ Star this repo if it saves you time! [Browse all automation projects →](https://github.com/Browser-Automation-Hub)*