Admin Dashboard Settings — What Lives Where & What It Does¶
Page Map¶
Settings Hub (4 cards)
|
+-- Clinic Information ......... identity, location, pharmacy
+-- Schedule & Booking ......... hours, template codes, booking rules
+-- Voice Booking .............. voice agent behavior, visit reasons, provider summary
+-- EMR Connection ............. OSCAR URL, OAuth creds, pull/sync
|
(also in sidebar, not on hub)
+-- Provider Settings .......... provider roster, per-provider voice overrides
1. Clinic Information¶
What it is: Your clinic's identity card — name, phone numbers, address, timezone, pharmacy.
What "Save" does:
- Writes to the clinic table (name, phone, address, city, province, postal code, timezone)
- Writes pharmacy info to clinicConfig (preferred pharmacy name, address, fax)
- Does NOT touch OSCAR. This is our database only.
Does the voice agent use this? - Yes — clinic name appears in the voice greeting - Yes — timezone is used to calculate "today" for same-day booking and slot filtering - Yes — phone numbers are displayed/referenced during calls
OSCAR relationship: None. This is purely Vitara config.
2. Schedule & Booking¶
What it is: Three sections stacked on one page:
a) Operating Hours (top section)¶
Your clinic's open/close times per day of the week, plus holidays.
| Field | What it controls |
|---|---|
| Day toggles + times | Which days are open and when (e.g., Mon 9:00-17:00) |
| Holidays | Specific dates the clinic is closed |
| Appointment duration | Default slot length in minutes |
| Buffer time | Gap between appointments |
| Max advance days | How far ahead patients can book |
What "Save Changes" does: Writes to clinicConfig as JSON. Our database only.
Does the voice agent use this? Yes — the booking engine filters OSCAR slots against these hours. If OSCAR says 18:00 is available but your hours end at 17:00, the voice agent won't offer it.
OSCAR relationship: "Sync from EMR" (blue banner) pulls day schedules FROM OSCAR into our hours config. One-way read. After syncing, you can manually adjust the hours and save — your edits override the synced values.
b) EMR Schedule Configuration — Template Codes¶
Only visible when EMR is connected. Shows the schedule template codes pulled from OSCAR (e.g., B = Booked, P = Practice, L = Lunch).
| Action | What it does |
|---|---|
| Toggle a code to "blocked" | Voice agent will SKIP slots with this code |
| Toggle a code to "bookable" | Voice agent will OFFER slots with this code |
What "Save Template Codes" does: Writes blocked/bookable lists to oscarConfig. Our database only. Does NOT change anything in OSCAR — OSCAR still has the same template codes. We're just deciding which ones we'll book into.
Does the voice agent use this? Yes — getTrueAvailability() filters out slots whose template code is in the blocked list.
c) Booking Constraints¶
| Field | What it controls |
|---|---|
| Allow same-day booking | Can patients book for today? |
| Allow weekend booking | Can patients book Sat/Sun? |
| Require DOB verification | Must the voice agent verify date of birth? |
| Max appointments per patient | Daily cap per patient |
| Cancellation notice (hours) | Minimum hours before appointment to allow cancel |
What "Save Constraints" does: Writes to oscarConfig. Our database only.
Does the voice agent use this? Yes — checked before every booking attempt.
3. Voice Booking¶
What it is: Everything that controls how the voice agent behaves on calls. Three save buttons, each saves a different piece:
a) Voice Agent Settings (top card)¶
| Field | What it controls |
|---|---|
| Custom greeting (EN) | What the Router agent says first in English |
| Custom greeting (ZH) | What the Router agent says first in Mandarin |
| Transfer phone number | Where to send callers who ask for a human |
| Default provider | Which doctor to use when caller says "any doctor" |
What "Save Voice Agent Settings" does: Writes to clinicConfig.clinicalSettings. Our database only.
Does the voice agent use this? Yes — read on EVERY incoming call. The greeting plays immediately. The default provider is used as fallback when no specific doctor is requested.
b) Voice Configuration (middle card)¶
| Field | What it controls |
|---|---|
| Default visit mode | In-person, virtual, or both |
| Ask reason before search | Should the agent ask "what's this visit for?" before searching slots? |
| Enabled visit reasons | Which visit reasons the agent can offer (checkup, follow-up, etc.) |
| Provider fallback behavior | What happens when the requested doctor has no slots |
| Max fallback providers | How many alternative doctors to try |
| Fallback search window (days) | How far ahead to search for fallback slots |
What "Save Configuration" does: Writes to clinicConfig.voiceConfig. Our database only.
Does the voice agent use this? Yes — controls the entire booking conversation flow.
c) Visit Reason Mappings (bottom table)¶
This is where you connect voice intents to OSCAR appointment codes:
| Column | Meaning |
|---|---|
| Visit Reason | What the patient says ("checkup", "follow-up", "sick visit") |
| OSCAR Code | The template code to use when booking this type (e.g., B) |
| Duration (min) | How long to book |
| Voice Enabled | Should the voice agent offer this reason? |
What "Save Mappings" does: Writes to oscarConfig.appointmentTypeMappings. Our database only. Does NOT change anything in OSCAR — OSCAR still has the same appointment types. We're mapping our voice reasons to OSCAR's codes.
Does the voice agent use this? Yes — when a patient says "I need a checkup", the agent looks up "checkup" in this table, gets the OSCAR code and duration, and uses those to create the appointment in OSCAR.
d) Provider Summary Table (read-only)¶
Shows all providers with their voice-bookable status, visit mode, and appointment type overrides. Click a provider row to open the slide-out (same one as Provider Settings page).
4. EMR Connection¶
What it is: How we connect to OSCAR. Credentials and sync controls.
| Field | What it controls |
|---|---|
| EMR Type | oscar, telus, other |
| Base URL | OSCAR instance URL (e.g., https://fbh.kai-oscar.com/oscar) |
| OAuth Consumer Key/Secret | From OSCAR admin panel |
| OAuth Token Key/Secret | From OSCAR admin panel |
What "Save Changes" does: Encrypts credentials and writes to clinicConfig.encryptedEmrCredentials. Our database only. The credentials are encrypted at rest and only decrypted when making OSCAR API calls.
Buttons:
| Button | What it does |
|---|---|
| Test Connection | Calls OSCAR with your credentials, reports success/failure |
| Pull from OSCAR | Fetches template codes + provider roster + appointment types FROM OSCAR into our database. One-way read. OSCAR is unchanged. |
Does the voice agent use this? Yes — this is THE connection. Every OSCAR API call (search patient, get slots, book appointment, cancel) uses these credentials.
IMPORTANT: After changing credentials, the server needs to establish a new TLS connection to OSCAR. The first call after a credential change may be slow (~6s) as it warms up.
5. Provider Settings¶
What it is: Your provider roster with per-provider voice overrides.
Provider List (main view)¶
Add, edit, delete providers. Fields: name, title, specialty, email, phone, status, accepting new patients.
"Sync from EMR" button: Pulls the provider list FROM OSCAR. One-way read. Merges with existing providers (matches by OSCAR ID).
Provider Voice Slide-Out (click a provider)¶
Per-provider overrides that WIN over clinic defaults:
| Field | What it controls |
|---|---|
| Voice Bookable | Can the voice agent book this provider? If off, agent will never offer them. |
| Visit Mode | Override clinic default (in-person/virtual/both) for this provider |
| Appointment Type Overrides | Override clinic-level reason→code mappings for this provider |
What "Save" does: Writes to clinicProviderConfig. Our database only.
Does the voice agent use this? Yes — provider overrides are MERGED with clinic defaults at runtime via getEffectiveConfig(). Provider-level settings always win.
The Big Picture: What Comes FROM OSCAR vs What's Ours¶
FROM OSCAR (pulled/synced, read-only) OUR CONFIG (saved locally, controls voice agent)
+----------------------------------+ +------------------------------------------+
| Template codes (B, P, L, etc.) | ---> | Which codes are bookable/blocked |
| Provider roster (names, IDs) | ---> | Which providers are voice-bookable |
| Appointment types | ---> | Visit reason -> code mappings |
| Operating hours (day schedules) | ---> | Adjusted hours, holidays |
+----------------------------------+ +------------------------------------------+
| + Booking constraints (same-day, DOB) |
| + Voice agent settings (greeting, phone) |
| + Fallback behavior |
| + Per-provider overrides |
+------------------------------------------+
The pattern: 1. Pull raw data from OSCAR (codes, providers, types) 2. Configure our rules on top of it (block codes, set durations, map reasons) 3. Voice agent reads our config at runtime to decide what to offer 4. Voice agent writes to OSCAR only when actually booking/cancelling (not from settings UI)
When Do Changes Take Effect?¶
| Change | When it applies |
|---|---|
| Greeting, visit reasons, constraints, fallback | Immediately — next incoming call |
| Template code blocking | Immediately — next slot search |
| Provider voice-bookable toggle | Immediately — next provider lookup |
| EMR credentials | Next OSCAR call (may have ~6s warmup) |
| EMR type change | Requires PM2 restart |
Who Maintains What¶
| Page | Who should configure it | How often |
|---|---|---|
| Clinic Information | Clinic admin (one-time setup) | Rarely — only when address/phone changes |
| EMR Connection | Vitara onboarding team | Once at setup, then only if credentials rotate |
| Schedule & Booking | Clinic admin | When hours change, new holidays, or adjusting booking rules |
| Voice Booking | Clinic admin + Vitara team | During onboarding to set greeting/mappings, then as needed |
| Provider Settings | Clinic admin | When providers join/leave, or change voice availability |