# ClaimDesk Poster - ops handover

Version 1.4.2 · Written 2026-10-23 · Escalation: RPA dev team, Teams channel **#rpa-support**

## 1. What the bot does

ClaimDesk Poster posts remittance payments into the **ClaimDesk** desktop app, one clinic at a time. Ops start it from the **ClaimDesk Poster** launcher window with an input Excel that has three sheets: **Login** (ClaimDesk user name and password), **Clinics** (the clinics to work) and **Settings** (an optional cutoff date). For every clinic the bot opens ClaimDesk, signs in, opens the clinic, and works through every unposted remittance in the list: ACH payments are posted and saved; other payment methods are skipped; checks dated after the cutoff are deferred. The result of every remittance is shown on the launcher's **Report screen**. The bot writes one run log per run in the `logs` folder. It drives one app: **ClaimDesk**.

## 2. How it works

```
ClaimDesk Poster launcher (the window you use, Report screen)
   └─ starts → posting bot (runs in the background) ──drives──> ClaimDesk desktop app
                     │                                       (do not touch while it runs)
                     ├─ writes → bot database (ops cannot open it; the Report screen reads it)
                     └─ writes → logs/run_<date>_<time>.log
```

- **Launcher**: where you start the run, see the Report screen, and read the version in the title bar.
- **Posting bot**: a background process the launcher starts. It has a built-in watchdog that kills the whole run if no remittance is processed for 5 minutes.
- **ClaimDesk**: the bot starts it fresh for every clinic, and force-closes it after every clinic, whether that clinic worked or not. This closes **every** ClaimDesk window on the machine, including one a person has open.
- **Bot database**: holds the batch, the clinics and one row per remittance. Ops see it only through the Report screen.
- **Run log**: one file per run, named by the start time, e.g. `logs/run_20260901_101500.log`.

**One run, step by step:**
1. Check that no earlier batch is still open. If one is, the bot stops at once (E01).
2. Read the Excel: Login, Clinics, Settings. Create a new batch with every clinic set to Pending.
3. For each clinic: start ClaimDesk → sign in → click the clinic in the list → wait for the remittance list.
4. For each remittance in the list: skip / defer / post → Save → wait up to 20 s for "Payment saved". One row goes to the Report screen.
5. Close ClaimDesk. If anything in step 3 failed, try the whole clinic again (up to 3 attempts).
6. After the last clinic, the batch is marked Completed **only if** no row is Error and no clinic is still Pending. Otherwise it stays open and blocks the next upload (E01).

## 3. Before a run

- [ ] ClaimDesk is installed on this machine and the bot's settings file (`.env`, next to the bot) has the path to it. Without it every clinic fails (E03). Only the dev team edits this file.
- [ ] The last batch finished as Completed. If it did not, the next run will not start (E01) and you need the dev team first.
- [ ] **Login sheet**: user name in cell A2, password in cell B2. Both must be filled, and the password must be current. A wrong password does not give a clear message; every clinic then fails with "not found in list" (E05).
- [ ] **Clinics sheet**: column A, from row 2 down, **one clinic per cell, no commas and no semicolons anywhere**. The bot splits a cell at every comma or semicolon.
  - Bad: `Clinic A, Clinic B` in one cell → the bot looks for two names it may not find. Bad: a clinic whose real name contains a comma (`Smith, Jones Family Care`) → split into `Smith` and `Jones Family Care`, both fail. Bad: a trailing comma `Clinic A,` → an extra empty clinic that fails.
  - Good: `Clinic A` in A2, `Clinic B` in A3, spelled exactly as in the ClaimDesk clinic list.
  - A clinic whose real name contains a comma cannot be run today. Tell the dev team (see section 13).
- [ ] **Settings sheet**: cell B1 is the cutoff date, or empty for no cutoff. Type it in the **same format** the ClaimDesk remittance list shows dates. The bot compares the two as text, not as dates, so a different format defers or posts the wrong checks (E13).
- [ ] All three sheets exist, named exactly Login, Clinics, Settings. A missing sheet stops the run at once (E02).
- [ ] The launcher title bar shows version 1.4.2 (see section 10).

## 4. During a run

- **Hands off this machine.** Don't use the mouse or keyboard. The bot clicks on screen; your clicks move the focus and its clicks land in the wrong place.
- **Close every other window whose title contains "ClaimDesk"** before the run, and don't open one during it: a database browser, a File Explorer folder, a browser tab, a document. The bot takes the first window with "ClaimDesk" in its title as the app, so it can drive the wrong window and then close the real ClaimDesk (E15).
- **Don't use ClaimDesk yourself on this machine during a run.** The bot force-closes all ClaimDesk windows after every clinic.
- Closing ClaimDesk does **not** stop the bot. It treats it as a failure, starts ClaimDesk again and retries the clinic.
- **To stop the bot**: there is no Stop button in the bot. Closing the launcher is not confirmed to stop it. If you must stop it, ask in #rpa-support first. Any stop leaves the batch open, and the next run will not start until the dev team clears it (E01).
- **A run looks stuck** when the newest run log in `logs` has no new line for more than 5 minutes. The bot's watchdog kills the run after 5 minutes with no remittance processed; the last line is then `[WATCHDOG] no progress for 300s - killing run` (E14). Wait 6 minutes before escalating.
- One clinic can take up to about 6-7 minutes when it fails all 3 attempts (each attempt waits up to 60 s for sign-in and up to 60 s for the remittance list). A clinic with many remittances takes longer; that is normal as long as new lines keep appearing.

## 5. Where to look when something goes wrong

| Question | Where to look |
|---|---|
| Did the run finish? | Newest file in `logs`: the last line is `[RUN SUMMARY] batch <n> done`. If the last line is `[WATCHDOG] ...`, the run was killed (E14). If the file is empty, the run never started (E01 / E02). |
| Did the batch complete? | Not visible to ops today (section 13, item 3). Rule of thumb: if the Report screen shows any red Error row, or any clinic has no rows at all, the batch is still open and the next run will be blocked. |
| Which remittances failed? | Report screen → the batch → rows in **red** (File Status Error). |
| Why did one remittance fail? | Report screen → **Comments** column for that check number. |
| Which clinics failed completely? | A clinic with **no rows** on the Report screen. Then search the run log for the clinic name: lines `[ERROR] [ERROR] Clinic '<name>' : <reason>` and `[DB] Clinic '<name>' left Pending after 3 attempts`. |
| Did the bot already retry? | Run log: `[AUTO-RERUN] attempt 2 for '<name>'` and `attempt 3`. Single remittances are never retried. |
| Was a green row really posted? | Comments column. Only **"Posted successfully"** means posted. Green rows with other comments were not posted (section 6). |
| Which version is running? | The launcher title bar. |

Note: error lines in the log start with `[ERROR] [ERROR]` (the word appears twice). That is normal for this version.

## 6. Statuses

The Report screen shows **File Status** (as a colour) and **Comments**. Read both: three different outcomes share the green colour.

| File Status | Colour | Comments | Meaning | What ops does |
|---|---|---|---|---|
| Completed | green | Posted successfully | Payment posted and saved in ClaimDesk | nothing |
| Completed | green | Remittance Errors on posting | **Not posted.** ClaimDesk showed its Remittance Errors screen; the bot cancelled. **Needs follow-up.** | Review the remittance in ClaimDesk by hand (E11) |
| Completed | green | Payment method '<method>' - not posted | **Not posted on purpose**: not an ACH payment | nothing, unless the client wants non-ACH posted (E12) |
| Deferred | grey | Check date <date> is after the cutoff - deferred | Not posted: dated after the cutoff in Settings B1 | It stays unposted in ClaimDesk and is picked up by a later run. Check the date format if many rows defer (E13) |
| Error | red | Payment not confirmed after Save | Saved, but "Payment saved" did not appear in 20 s. **It may have posted.** | **Check ClaimDesk before doing anything** (E09) |
| Error | red | Save button not found | Not posted: the Save button was missing on the payment screen | Escalate (E10) |
| Pending | amber | (none) | Listed on the screen, but the current bot never writes it | If you see it, escalate |
| (no rows for a clinic) | - | - | The clinic failed all 3 attempts, or it had nothing to post | See E08 and E18 |

Statuses kept in the bot database that ops cannot see: each clinic is **Pending** or **Success**, and each batch is **Pending** or **Completed**. A clinic is set to Success even when it had zero remittances (E18). A batch stays Pending if any row is Error or any clinic is Pending.

## 7. Exception catalogue

Quote the ID (E01, E02...) in #rpa-support.

| ID | What you see | How the bot identifies it | Where it is recorded | Type | Who acts | What to do | Escalate when |
|---|---|---|---|---|---|---|---|
| E01 | Run stops at once with "A Pending batch exists - finish or clear it before a new upload". The new run log is empty. | At start it checks for an earlier batch that never completed. Any batch with one red Error row, one failed clinic, or a killed run stays open for good. | On screen only; not in the run log | System | **Dev** | Nothing ops can do: ops cannot clear a batch. Don't retry. | Always. Send: the time, the previous run's log file, and which earlier batch had red rows or a killed run. |
| E02 | Run stops at once with "'Login' sheet not found", "UserName/Password missing in Login sheet (row 2)", or a technical error naming Clinics or Settings. The new run log is empty. | The Excel has no Login sheet, A2 or B2 is empty, or the Clinics / Settings sheet is missing. | On screen only | Business | Ops | Fix the Excel (section 3) and start again. No batch was created. | The sheets are correct and it still stops. Send the error text and the time (not the Excel, it holds the password). |
| E03 | Every clinic fails, log lines `[ERROR] [ERROR] Clinic '<name>' : 'CLAIMDESK_EXE'` or `... : Login window not found` for every clinic | The bot can't find where ClaimDesk is installed, or ClaimDesk doesn't open its sign-in window within 60 s. | Run log | System | Bot, then Dev | The bot retries each clinic 3 times. Check that ClaimDesk opens normally by hand on this machine (after the run). | Every clinic shows it. Send the log file. The batch is now open → E01. |
| E04 | Log line `... : Login window not found` for some clinics only | ClaimDesk's sign-in window did not appear within 60 s (slow start). | Run log | System | Bot | Wait; the bot retries the clinic up to 3 times. | The clinic is left Pending (E08). |
| E05 | Log line `... : Clinic '<name>' not found in list`; the clinic has no rows on the Report screen | After sign-in, the bot looks 10 s for a link with exactly that clinic name. | Run log | Business | Ops | Check the spelling against ClaimDesk, and that the cell has no comma or semicolon. **If every clinic shows this, the password in the Login sheet is probably wrong.** | Spelling and password are correct. |
| E06 | Log line `... : Wrong clinic opened, leaving Pending: <name>` | Right after clicking the clinic, the ClaimDesk title does not contain the clinic name. It checks with no wait, so a slow screen or a name with `&` can fail even when the right clinic opened. | Run log | System | Bot, then Dev | Wait for the 3 attempts. Check the spelling. | It fails all 3 attempts with the spelling exact. Send the log file and the clinic name. |
| E07 | Log line `... : Remittance grid did not load` | The remittance list did not appear within 60 s after opening the clinic. | Run log | System | Bot, then Dev | Wait for the 3 attempts. | The same clinic fails it on two runs. Send the log file. |
| E08 | Log line `[DB] Clinic '<name>' left Pending after 3 attempts`; the clinic has no rows on the Report screen (or only rows from an earlier attempt) | All 3 attempts failed. | Run log | System | Ops, then Dev | Read the `[ERROR]` lines just above it for the reason (E03-E07) and act on that one. The batch is now open → E01. | Always, to get the batch cleared. Send the log file and the clinic name. |
| E09 | Red row, Comments "Payment not confirmed after Save" | After Save the bot waits 20 s for "Payment saved". It never appeared. | Report screen | System | **Ops** | **Check the payment in ClaimDesk first** (the check number). If it posted: do not post again; note it for the dev team. If it did not post: post it by hand or leave it for the next run. Re-running or re-posting without checking can post it twice. The row stays red (ops can't edit it) and the batch stays open → E01. | Always, to get the row corrected and the batch cleared. Send the check number, what ClaimDesk shows, and the log file. |
| E10 | Red row, Comments "Save button not found" | The payment screen opened but its Save button did not appear within 10 s. | Report screen | System | Dev | Check in ClaimDesk that the payment was not posted. | Always. Send the check number, the time and the log file. |
| E11 | Green row, Comments "Remittance Errors on posting" | ClaimDesk showed its Remittance Errors screen within 5 s of Post Payment; the bot pressed Cancel. | Report screen | Business | Ops | **Not posted.** Review the remittance in ClaimDesk by hand and resolve it there. | The same remittance keeps coming back on every run. |
| E12 | Green row, Comments "Payment method '<method>' - not posted" | The remittance's method is not ACH. | Report screen | Business | Ops | Nothing; the bot posts ACH only. Post by hand if the client wants it. It reappears on every run while unposted. | Never. |
| E13 | Grey row, Comments "Check date <date> is after the cutoff - deferred" | The check date is compared with Settings B1 **as text**, not as a date. | Report screen | Business | Ops | Normal when the date really is after the cutoff. If checks dated before the cutoff were deferred (or later ones posted), fix the B1 format to match how ClaimDesk shows dates. | B1 matches ClaimDesk's format and it's still wrong. |
| E14 | Run stopped in the middle; last log line `[WATCHDOG] no progress for 300s - killing run`; later clinics never ran | No remittance was processed for 5 minutes. Sign-in and list waits don't count as progress, so 3 slow attempts in a row can trigger it. | Run log | System | Dev | Don't restart: the batch is open → E01. ClaimDesk may still be open; leave it. | Always. Send the log file and the time. |
| E15 | The bot types or clicks in the wrong window, or a ClaimDesk you had open suddenly closes | The bot takes the first window with "ClaimDesk" in its title, and force-closes all ClaimDesk windows after every clinic. | Not recorded; you see it on screen | System | Ops, then Dev | Follow the section 4 rules: no other "ClaimDesk" windows, no one using ClaimDesk on this machine. | It happens with no other ClaimDesk window open. Send the time and the log file. |
| E16 | The same check number appears twice or three times on the Report screen | Each retry of a clinic writes rows again for everything still unposted. | Report screen | System | Ops | Count each check once. Skipped / deferred / rejected duplicates are harmless. If one copy is red and another green "Posted successfully", check ClaimDesk (E09). | A red copy keeps the batch open → E01. |
| E17 | The launcher title still shows an old version after an update | The launcher keeps the old folder until it is fully restarted. | Launcher title bar | System | Ops | Close the launcher completely and start it again. Check the title bar. | Still the old version after a restart. |
| E18 | A clinic that should have work shows no rows at all, and the log has no error for it | The remittance list loaded but was empty when read (possibly not filled in yet). The bot marks the clinic done with nothing posted. | Nowhere ops can see | System | Ops, then Dev | Open the clinic in ClaimDesk (after the run) and check for unposted remittances. | Remittances are there. Send the clinic name, time and log file. |

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| Sign-in, clinic, or remittance list fails, or any click fails (E03-E07) | Closes ClaimDesk, starts it again, signs in, retries the whole clinic | 3 attempts per clinic, no pause between; each up to ~2 min | Clinic left Pending (E08), next clinic. Batch stays open. |
| "Payment saved" doesn't appear | Waits | 20 s, **no retry** | Row Error (E09), next remittance |
| Save button missing | Waits | 10 s, **no retry** | Row Error (E10), next remittance |
| Remittance Errors screen | Presses Cancel | waits 5 s for it | Row green "Remittance Errors on posting" (E11) |
| No remittance processed for a while | Watchdog kills the whole run | 5 min (checked every 10 s) | Run ends; nothing restarts it; batch open (E14, E01) |

The bot never retries a single remittance, never resumes a killed run, and never clears an open batch.

## 9. Known incidents

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| Up to 1.3.0 | Users stayed on 1.3.0 after an update | The launcher kept the old folder until it was restarted | Restart the launcher fully and check the title bar (E17). Fix not visible in this repo. | Yes |
| Before 1.4.2 | Red rows "Payment not confirmed after Save" that had really posted | ClaimDesk took longer than the 10 s wait | Wait raised to 20 s. Still check ClaimDesk before re-posting (E09). | Partly |
| Before 1.4.2 | Clinics with a comma in the name were split and skipped | The bot splits cells at commas | One clinic per row, no commas (section 3). Still open for names that really contain a comma. | Partly |
| Before 1.4.2 | The bot drove a database browser whose title contained "ClaimDesk", then closed the real ClaimDesk | Window found by title text | Close other "ClaimDesk" windows (section 4). Marked fixed, but the code still matches by title. | Partly |
| 2026-09-01 run log | Clinic with `&` in its name: "Wrong clinic opened, leaving Pending" | Not diagnosed (no wait before the title check, or `&` shown differently) | Escalate if spelling is exact (E06) | No |
| 2026-09-01 run log | Run killed by the watchdog after auto-reruns | Retries without progress add up to 5 min | Escalate (E14) | No |

## 10. Releases and version check

- **How an update arrives**: through the launcher. The launcher's update steps are not in this repo; ask #rpa-support when a new version is due.
- **How to confirm it applied**: close the launcher completely, start it again, and read the version in its title bar.
- **If the version did not change**: restart the launcher once more. If it is still old, post in #rpa-support with the version you see. Don't run on the old version.
- Every machine that runs the bot must be on the same version.

## 11. Escalating to dev

Post in **#rpa-support** (RPA dev team). Send:
- the exception ID from section 7 (E01...),
- the date and time of the failure,
- the clinic name and check number when it is about one remittance,
- the run log file `logs/run_<date>_<time>.log` (attach the file),
- a screenshot of the Report screen or of the ClaimDesk message.

Never send: passwords, the input Excel (its Login sheet holds the password), the `.env` settings file, or patient data in chat. Don't paste log lines that contain patient names (older logs may have them; see section 13).

## 12. Failure-class check

- F1 covered in section 3 (ClaimDesk path, sheets) and E02, E03.
- F2 covered in section 4 and E15; root cause in section 13 item 6.
- F3 covered in E04, E06, E07, E09, E10 and section 8. No screen-size dependency found in the code.
- F4 covered in section 3 (commas, cutoff format, exact spelling) and E05, E13; section 13 items 8, 9.
- F5 covered in E18; section 13 item 5.
- F6 covered in E09.
- F7 covered in section 6 and E11, E12; section 13 item 4.
- F8 covered in E14 and section 8; section 13 item 7. No endless loop: a clinic stops after 3 attempts.
- F9 covered in section 4 (no Stop button, closing ClaimDesk doesn't stop it); section 13 item 10.
- F10 covered in E01, E08, E09, E16; section 13 items 1, 2.
- F11 covered in section 5 and E01, E02, E18; section 13 items 3, 11.
- F12 covered in section 10 and E17; section 13 item 12. The bot writes nothing to shared resources at start.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | An open batch blocks every new upload, and nothing can clear it except a hand edit of the database | Ops is blocked after any failure and must wait for dev every time | `bot.py:167-168` |
| 2 | A batch can never complete once any row is Error or any clinic is Pending; nothing re-checks it later, and retries leave the old Error rows behind | One red row = the next run is blocked (E01) | `bot.py:150-154`, `bot.py:177-179`, `bot.py:139` |
| 3 | Batch and clinic status are in the database only, not on the Report screen | Ops can't see whether a batch completed or which clinic failed without the log | `report_screen.py:6`, `bot.py:140`, `bot.py:178` |
| 4 | "Rejected by app" and "Skipped" are stored as Completed (green), same as Posted | Unposted remittances look done; ops must read every comment | `bot.py:27-33` |
| 5 | A clinic is marked Success after reading the remittance list with no positive count; an empty or not-yet-filled list counts as done | Work silently not done (E18) | `bot.py:96-101`, `bot.py:140` |
| 6 | Window found by "ClaimDesk" anywhere in the title, which also matches the launcher "ClaimDesk Poster" and "ClaimDesk Login"; the commit "fix: bot grabbed the SQL browser window" did not change this code | Bot drives the wrong window (E15); a wrong password looks like "clinic not found" | `bot.py:66-70`, `bot.py:83` |
| 7 | Watchdog heartbeat only on each remittance; sign-in and list waits (up to 3 × ~130 s) and empty clinics never reset it; kill leaves ClaimDesk open and the batch open | Healthy-but-slow runs get killed (E14) | `bot.py:39-49`, `bot.py:137` |
| 8 | Clinic cells split at `,` and `;`; real names with a comma can't be run; a trailing comma creates an empty clinic | Clinics silently fail (E05) | `bot.py:62` |
| 9 | Cutoff date compared as text with the grid's date text | Wrong checks deferred or posted (E13) | `bot.py:107` |
| 10 | No Stop button / clean stop; launcher code not in the repo, so whether closing it stops the bot is unknown | Ops has no safe way to stop a run | `bot.py:157-180` |
| 11 | Start-up errors (open batch, Excel problems) are not written to the run log, only to the screen | Lost once the window closes; empty log | `bot.py:167-169`, `bot.py:52-63` |
| 12 | Launcher/update code is not in this repo; the 1.3.0 update fix can't be checked | Version drift; the 2026-09-01 log has lines this code never writes, so it came from another build | `report_screen.py:8`, `report_screen.py:14` |
| 13 | The existing log `logs/run_20260901_101500.log` contains a patient name (line 3). Ops can open the logs folder. Current code doesn't write that line. | PHI exposed to anyone with log access; could be pasted into chat | `logs/run_20260901_101500.log:3` |
| 14 | "Wrong clinic opened" checked immediately after the click, with no wait; names with `&` fail | Clinics left Pending for no real reason (E06) | `bot.py:90-92` |
| 15 | Force-close of all ClaimDesk instances after every clinic, including successful ones | Closes a person's ClaimDesk on the same machine | `bot.py:146` |
| 16 | "Payment not confirmed after Save" has no re-check in ClaimDesk (e.g. is the check still in the unposted list?) and no way for ops to correct the row | Double-posting risk; red row blocks the batch (E09) | `bot.py:117-118` |
| 17 | Error log lines carry a doubled `[ERROR] [ERROR]` prefix | Confusing when searching logs | `bot.py:144`, `bot.py:165` |
| 18 | ClaimDesk password stored in plain text in the input Excel | Excel can't be shared for support | `bot.py:56` |