godwinsystems/rb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move runbooks into domain directories

Browse Source 
od-db-backup.md becomes od/db-backup.md -- the hyphen becomes a slash, so
the fetch command is exactly as long to type as before. That mattered: the
length of a hand-typed command is the constraint this repo is organized
around, and a reorganization that lengthened it would have been a net loss.

Scripts deliberately stay flat in scripts/ with their domain prefix.
Everything executable in one directory is the set worth reading before it
runs, and nesting five files by domain would add characters without adding
clarity.

Updates every reference: README Contents (now grouped by directory), the
layout section, both fetch examples, inter-runbook links, and the .NOTES
headers in all five scripts. Verified every markdown link resolves on disk
and that Contents and the filesystem agree in both directions.

Records the naming rule in CONTRIBUTING so the next file lands correctly.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HwcG1jLs1T425QRMxtjxP7
This commit is contained in:
Ivan Godwin
2026-09-02 23:15:48 -07:00
parent f2a979f047
commit cb0c5b4614
14 changed files with 91 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
od/scan-duplex.md
+119
View File
@@ -0,0 +1,119 @@
# Runbook: Open Dental — Duplex ADF scanner captures only one side
> For qualified IT professionals, on systems they are authorized to administer.
> Provided as-is, without warranty — verify it fits your environment. See LICENSE.
**Applies to:** Any single-pass duplex ADF scanner feeding Open Dental over **TWAIN** on a Windows 11 workstation (standalone / self-enrolled is common). Written against a Canon imageFORMULA DR-series with the combined ISIS/TWAIN/WIA driver package, but the diagnostic tree is model-agnostic.
**Symptom:** A double-sided document run through the ADF into the Open Dental **Imaging** module lands as front-only — the back side is missing, blank, or pages come out in the wrong order.
**Most likely cause:** Duplex is not enabled on whichever setting is *authoritative*, and which one is authoritative depends on the **Show TWAIN UI** toggle. The classic miss is a checked-but-inert control on the branch that isn't in charge.
**Placeholders:**
| Placeholder | Meaning |
|---|---|
| `<WORKSTATION>` | The Windows 11 workstation with the scanner attached |
| `<SCANNER_MODEL>` | The duplex ADF scanner model (e.g. a Canon DR-series) |
| `<TWAIN_SOURCE>` | The native TWAIN data source name as it appears in Open Dental's **Twain Name** dropdown |
| `<TEST_PATIENT>` | A dummy patient/chart used for test scans only — never a live chart |
| `<OD_USER>` | The Open Dental user the front desk actually scans as |
---
## Key concept — where duplex is governed
> [!IMPORTANT]
> In Open Dental, duplex is controlled in **one of two places**, and only one is live at a time. The **Show TWAIN UI** toggle (Setup → Imaging → **Edit Imaging Device**) decides which:
>
> - **Show TWAIN UI = OFF** → **Open Dental's own Duplex checkbox** (Imaging Quality → **Multipage Scans**) is authoritative. The scanner's own dialog never appears.
> - **Show TWAIN UI = ON** → the **scanner's TWAIN dialog at scan time** is authoritative. Open Dental's Duplex checkbox is **inert** — it is not read.
>
> **The trap:** an OD Duplex checkbox that is checked *while Show TWAIN UI is ON* (or a scanner dialog set to duplex *while Show TWAIN UI is OFF*) changes nothing. A control set correctly on the **wrong branch** is the single most common misdiagnosis here. Always establish the toggle state **first**, then set duplex on the branch that matches it.
---
## Diagnostic steps
Work these in order. Steps a–c establish ground truth before you change anything.
### a. Confirm the Twain Name binds to the NATIVE source, not a WIA bridge
In **Edit Imaging Device**, check the **Twain Name** value.
- It should be the vendor's **native TWAIN** source (e.g. the `<SCANNER_MODEL>` TWAIN entry).
- If it reads **`WIA-<SCANNER_MODEL>`** or any `WIA-…` entry, that is the Windows WIA→TWAIN bridge. **The WIA bridge frequently drops the second side** and cannot be relied on for duplex. Re-select the native TWAIN source.
If the native source isn't in the list, the 32-bit TWAIN driver isn't registered — see [Gotchas](#gotchas).
### b. Record the Show TWAIN UI state
Note whether **Show TWAIN UI** is **ON** or **OFF**. This determines which fix branch applies below. Write it down — you'll restore or deliberately set it.
### c. Screenshot the current settings (baseline / rollback)
Capture the current **Edit Imaging Device** and **Imaging Quality → Multipage Scans** settings before touching anything, so you have a known-good rollback point and a record of what changed.
> [!WARNING]
> Screenshots for your own rollback are fine, but they may contain client-identifying detail (hostname, user, chart data). Keep them in the **private tier** — never attach them to this public repo.
### d. Confirm the scan action is multi-page (ADF), not single-page
The front-desk action must be **Scan Multi-Page Document** (ADF → multi-page PDF). The plain **Scan Document** action pulls a single page and **can never be duplex** regardless of every other setting. If the button in use is single-page, that alone explains front-only output.
### e. Reproduce with a real double-sided document
Feed a genuine two-sided document through the ADF and record the **exact** failure mode — they point at different causes:
| Observed | Points toward |
|---|---|
| Front pages only, backs never appear | Duplex off on the authoritative branch (step f) |
| Backs captured then dropped if blank/light | **Skip Blank Page** is on (see Gotchas) |
| Both sides present but interleaved/out of order | Scan-order / driver page-order setting |
### f. Apply the fix for the matching branch
Use the [decision table](#fix-decision-table) below, keyed to the Show TWAIN UI state from step b.
### g. If still failing, isolate with Twacker over TWAIN
Twacker is the reference TWAIN test application. Scan the same document through Twacker against the **same `<TWAIN_SOURCE>`**:
- **Works in Twacker, fails in Open Dental** → the driver and hardware are fine; the problem is Open Dental configuration or how it drives the source. Return to steps a–f.
- **Fails in Twacker too** → the problem is below Open Dental: driver settings or hardware. Fix it in the scanner's TWAIN dialog / driver, then retest.
### h. Verify end-to-end and set as default
1. Trigger the scan from the **actual front-desk button** as `<OD_USER>` — not a settings-screen test.
2. **Open the resulting PDF** and confirm **both sides are present and in reading order**.
3. Set the working configuration as the **default** so it survives an app restart or profile reset. A fix that only holds for the current session isn't done.
---
## Fix decision table
| Show TWAIN UI | Authoritative setting | Action |
|---|---|---|
| **OFF** | Open Dental **Duplex** checkbox (Imaging Quality → Multipage Scans) | **Check it.** |
| **ON** | Scanner's **TWAIN dialog** at scan time | Set **Scanning Side = Duplex**; set **Skip Blank Page = OFF**. |
> **Resolved example (OFF branch):** In the case that prompted this runbook, **Show TWAIN UI was OFF** and Open Dental's **Duplex** checkbox was **unchecked**. Checking it resolved the issue immediately — no driver or hardware change needed. This is the common OFF-branch outcome; still walk the tree above rather than assuming, since the ON branch fails differently.
---
## Gotchas
- **"Skip Blank Page" masquerades as simplex.** With this enabled in the TWAIN driver, a blank or light back side is **silently deleted on save** — the output looks exactly like a simplex scan even though both sides were captured. Turn it **OFF** while diagnosing duplex.
- **Open Dental is 32-bit and binds a 32-bit TWAIN source.** Open Dental only supports **32-bit TWAIN** drivers. The ISIS/TWAIN/WIA package installs a 32-bit source, and Open Dental (a 32-bit app) binds to it. A 64-bit-only driver, or picking the wrong source, means no working duplex — confirm the **native 32-bit TWAIN** source is what's selected in step a.
- **Windows Fax and Scan is NOT a valid isolation test.** It drives the scanner over **WIA, not TWAIN**. It can succeed while the TWAIN path fails (or vice versa) and tells you nothing about an Open Dental/TWAIN problem. Use **Twacker over TWAIN** (step g) for isolation.
- **Mechanical checks.** Before chasing software: the feed/separation **lever is in the separation (multi-sheet) position**, **double-feed detection** isn't misfiring and halting the second side, and the back side of the test document **genuinely has content**.
---
## Compliance note
> [!WARNING]
> Run all test scans into a **`<TEST_PATIENT>`** dummy account — **never a live chart**. When finished, **purge the test images** from `<TEST_PATIENT>` so no stray PHI or test scans are left behind. Confirm the dummy account holds nothing before leaving the workstation.
## References
- Open Dental manual — Imaging module / device setup: <https://www.opendental.com/manual/imaging.html>
- Open Dental manual — Edit Imaging Device (Twain Name, Show TWAIN UI): <https://www.opendental.com/manual/imagingdevices.html>