# 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

The bot posts remittance payments into the **ClaimDesk** desktop app, one clinic at a time. You start it from the **ClaimDesk Poster** launcher window and give it an input Excel with three sheets:
- **Login:** the ClaimDesk user name and password.
- **Clinics:** the clinics to process.
- **Settings:** the cutoff date.

For each clinic it signs in to ClaimDesk, opens the clinic and reads the list of unposted remittances. Then it handles each item:
- **ACH payments dated on or before the cutoff:** it posts them.
- **Items paid by any other method:** it skips them.
- **Items dated after the cutoff:** it defers them.

You see one result row per item on the launcher's **Report screen**. The bot also writes a run log in the `logs` folder. It drives only one app, **ClaimDesk**.

## 2. How it works

```
ClaimDesk Poster launcher (the window you use, shows the Report screen)
   └─ starts → bot (automation process) ──drives──> ClaimDesk desktop app
                    │                                (do not touch while it runs)
                    ├─ writes → bot database (batch, clinics, one row per item)
                    │             └─ read by → Report screen
                    └─ writes → logs/run_<date>_<time>.log
```

- **ClaimDesk Poster launcher:** where you start a run and read the results on the Report screen. Its title bar shows the version.
- **Bot:** a background process with no window of its own. It moves the real mouse and types into ClaimDesk.
- **ClaimDesk:** the payment app. The bot starts it, signs in, and **force-closes it after every clinic**. That closes every ClaimDesk window on the machine, including one a person has open.
- **Bot database:** holds the batch, clinic and item results. Ops cannot open it; the Report screen shows part of it.
- **Run log:** one new file per run, with errors and retries.

**One run, step by step:**
1. The bot checks that no earlier batch is still unfinished. If one is, it refuses to start (E01).
2. It reads the input Excel and creates a new batch.
3. For each clinic:
   1. It starts ClaimDesk and signs in.
   2. It clicks the clinic in the clinic list.
   3. It reads the unposted remittance list.
   4. It handles each item: skip, defer, or post and save. One row per item goes to the Report screen.
   5. It closes ClaimDesk.
   6. If anything fails at clinic level, it repeats the whole clinic, up to 3 tries.
4. At the end it marks the batch Completed, but only when no red (Error) row and no unfinished clinic is left. Otherwise the batch stays Pending (see E01).

## 3. Before a run

- [ ] The previous batch is finished. If it isn't, the bot refuses to start (E01).
- [ ] Nobody is using ClaimDesk on this machine. The bot closes every ClaimDesk window.
- [ ] No other window whose title contains "ClaimDesk" is open: SQL tools, Explorer folders, browser tabs, a second launcher. The bot can grab the wrong one (E15).
- [ ] **Login sheet:** user name in cell A2, password in cell B2. Both must be filled.
- [ ] **Clinics sheet:** clinic names in column A, starting at row 2.
  - **Put one clinic per row.** Never put two clinics in one cell.
  - A name that itself contains a comma or a semicolon cannot be processed at all. Tell dev about such clinics.
  - Bad: `North Clinic, South Clinic` in one cell. Good: `North Clinic` in A2, `South Clinic` in A3.
  - Spell each name exactly as it appears in ClaimDesk's clinic list, including `&`, dots and spaces.
- [ ] **Settings sheet:** the cutoff date in cell B1.
  - The bot compares dates **as text**, not as dates. So the cutoff must be written in the **same format ClaimDesk shows check dates in**.
  - If you are not sure the format matches, ask dev before the first run.
- [ ] The ClaimDesk program path is set in the bot's settings file. Dev does this once per machine. If it is missing, every clinic fails (E06).
- [ ] 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 moves the real mouse, so your clicks and its clicks collide.
- **Don't close or use ClaimDesk.** If you close it, the bot treats the clinic as failed and restarts it.
- **To stop the bot:** there is no Stop button.
  - Best: let the run finish.
  - If you must stop it, close the ClaimDesk Poster launcher, then watch ClaimDesk for one minute. If ClaimDesk keeps moving, the bot is still running; contact dev. (Whether closing the launcher stops the bot could not be checked; the launcher code is not in this repo.)
  - **Any stop leaves the batch unfinished, and that blocks the next upload** (E01).
- **A run looks stuck** when ClaimDesk sits on the same screen and the newest log file stops growing.
  - The bot gives up by itself after **5 minutes with no item posted**: the log then ends with a `[WATCHDOG]` line (E14).
  - Wait those 5 minutes before you act.

## 5. Where to look when something goes wrong

| Question | Where to look |
|---|---|
| Did the run finish? | Newest file in the `logs` folder (`run_<date>_<time>.log`). Look at its last line. A `[RUN SUMMARY] batch N done` line means the run reached the end. **It does not mean every item worked**, so check the Report screen too. A `[WATCHDOG]` last line means the run was killed (E14). If neither line is there, the run is still going or crashed. |
| Is the batch still unfinished? | Ops can't see this directly. If the next upload is refused with "A Pending batch exists", it is still unfinished (E01). |
| Which items failed? | Report screen → that batch → rows in **red** (File Status = Error). Also read the comment on **green** rows, because some green rows were not posted (section 6). |
| Why did one item fail? | Report screen → **Comments** column. |
| Which clinics failed completely? | A clinic that failed completely has **no rows at all** on the Report screen. Search the run log for `left Pending after 3 attempts`; the clinic name is on that line. The `[ERROR] Clinic '<name>'` lines just above it give the reason. |
| Did the bot already retry? | Run log: lines starting `[AUTO-RERUN] attempt 2` or `attempt 3` for that clinic. |
| Which version is running? | The launcher title bar. |

The bot creates no output Excel or output files, and takes no screenshots. Everything ops can see is on the Report screen and in the `logs` folder.

## 6. Statuses

**On the Report screen (File Status colour plus Comment).** You can see only the colour and the comment, so **read the comment on green rows**.

| Status (internal name) | Colour / File Status | Comment shown | Meaning | What ops does |
|---|---|---|---|---|
| Posted | green, Completed | "Posted successfully" | Payment posted, and ClaimDesk showed "Payment saved". | Nothing. |
| Rejected by app | **green, Completed** | "Remittance Errors on posting" | **Not posted.** ClaimDesk showed its Remittance Errors screen and the bot pressed Cancel. | **Needs follow-up.** Review and post it in ClaimDesk by hand (E11). |
| Skipped | **green, Completed** | "Payment method '<method>' - not posted" | Not posted on purpose, because the bot only posts ACH payments. | Nothing, unless the client wants non-ACH posted (E09). |
| Deferred | grey, Deferred | "Check date <date> is after the cutoff - deferred" | Not posted, because the check is dated after the cutoff. | Picked up by a later run once the cutoff moves past the check date. Check the date really is later (E10). |
| Error | red, Error | "Save button not found" | Not posted. The payment screen had no Save button. | E12. |
| Error | red, Error | "Payment not confirmed after Save" | **Possibly posted.** The bot clicked Save but didn't see "Payment saved" within 20 seconds. | **Check in ClaimDesk before re-running** (E13). |
| Pending | amber, Pending | (any) | The code never writes this colour today; it is a fallback. | If you ever see it, report to dev. |

**Not shown anywhere ops can see.** These are kept in the bot database only.

| Status | Of what | Meaning | How ops can tell |
|---|---|---|---|
| Pending | Clinic | Not done yet, or it failed all 3 tries. | Run log: "left Pending after 3 attempts". |
| Success | Clinic | The bot went through the clinic's whole list. **This doesn't mean every item posted**; red rows can still exist. | Run log has no "left Pending" line for that clinic. |
| Pending | Batch | Unfinished. **Blocks every new upload.** | The next upload is refused (E01). |
| Completed | Batch | No red rows and no unfinished clinics. | The next upload is accepted. |

## 7. Exception catalogue

| ID | What you see | How the bot identifies it | Where it is recorded | Type | Who acts | What to do | Escalate when |
|---|---|---|---|---|---|---|---|
| E01 | The run refuses to start: "A Pending batch exists - finish or clear it before a new upload". | Before starting, it checks whether any earlier batch is still unfinished. A batch stays unfinished if it has **even one red row**, a clinic that failed all 3 tries, or a run that was killed or stopped. | Message on screen only. The new log file is empty. | System | **Dev** | Ops cannot clear it, because there is no button and ops has no database access. Find the cause first: red rows on the previous batch's Report screen, "left Pending" lines or a `[WATCHDOG]` line in the previous run's log. | Always. Send the previous run's log file name, its batch number, and the red rows / clinic names you found. |
| E02 | The run stops at once with an input message: "'Login' sheet not found", "UserName/Password missing in Login sheet (row 2)", or a technical error naming "Clinics" or "Settings". | It reads the Excel before doing anything else. | Message on screen only. The new log file is empty. No batch is created, so nothing is blocked. | Business | Ops | Fix the Excel: sheet names exactly Login, Clinics, Settings; user name in A2 and password in B2 of Login. Then start again. | The sheets are correct and it still stops. |
| E03 | **Every** clinic fails with "Clinic '<name>' not found in list", and each is left Pending after 3 attempts. | The bot does **not** check whether sign-in worked. After a wrong password it stays on the login screen and can't find any clinic. | Run log `[ERROR] Clinic ... not found in list` lines. No rows on the Report screen. Batch left unfinished. | Business | Ops, then Dev | Sign in to ClaimDesk by hand with the Login sheet's user name and password. If that fails, fix the password in the Excel. | Always for the unfinished batch (E01). Also when the password works by hand. |
| E04 | **One** clinic fails with "Clinic '<name>' not found in list". | The clinic's link doesn't appear in ClaimDesk's clinic list within 10 seconds. It is retried 3 times with a fresh sign-in. | Run log `[ERROR]` and "left Pending after 3 attempts". No rows on the Report screen for that clinic. | Business | Bot, then Ops | Compare the name in the Excel with ClaimDesk's list, letter by letter. A half-name (for example only the part before a comma) means two clinics were in one cell, or the name contains a comma. Fix the input and re-run just that clinic once the batch is cleared (E01). | The spelling is exact, or the real name contains a comma or semicolon. |
| E05 | "Wrong clinic opened, leaving Pending: <name>". | Right after clicking the clinic, it checks whether the ClaimDesk window title contains the clinic name. It checks instantly, so a slow ClaimDesk, or a name with characters like `&`, can trigger it falsely. | Run log `[ERROR]` and `[AUTO-RERUN]` lines. No Report rows for that clinic. | System | Bot, then Ops / Dev | Wait for the 3 tries. If the clinic still fails, check its spelling against ClaimDesk (as in E04). | The spelling is exact. Send the log file name and clinic name. |
| E06 | "Login window not found", "ClaimDesk window not found", or an error that just names the ClaimDesk program setting. | ClaimDesk's sign-in window doesn't appear within 60 seconds, ClaimDesk can't be found after sign-in, or the program path isn't set. | Run log `[ERROR] Clinic ...` lines, then "left Pending after 3 attempts". | System | Bot, then Ops / Dev | Wait for the 3 tries. Then open ClaimDesk by hand on this machine. If it doesn't open or is very slow, the problem is ClaimDesk or the machine. | ClaimDesk opens fine by hand, or the error names the program setting. Send the log file name. |
| E07 | "Remittance grid did not load". | The list of unposted remittances doesn't appear within 60 seconds after opening the clinic. | Run log `[ERROR]` and "left Pending" lines. | System | Bot, then Dev | Wait for the 3 tries. Open the clinic in ClaimDesk by hand to see whether the list loads at all. | It fails after 3 tries. Send the log file name and clinic name. |
| E08 | Any other `[ERROR] Clinic '<name>'` line, for example "list index out of range". | Something unexpected happened on the ClaimDesk screen while it was handling the clinic. | Run log. | System | Bot, then Dev | Wait for the 3 tries. | It fails after 3 tries. Send the log file name, clinic name and the error text. |
| E09 | Green row: "Payment method '<method>' - not posted". | The item's payment method is not ACH. | Report screen. | Business | Ops | Nothing. Post it by hand only if the client asks. | Never. |
| E10 | Grey row: "Check date <date> is after the cutoff - deferred". | The check date is "later" than the Settings cutoff, compared as text. | Report screen. | Business | Ops | Check that the date really is after the cutoff. If a date that is clearly earlier was deferred, or a later one posted, the date formats don't match (see section 3). | The formats match and the result is still wrong. |
| E11 | **Green** row: "Remittance Errors on posting". | After Post Payment, ClaimDesk shows its "Remittance Errors" screen within 5 seconds. The bot presses Cancel. | Report screen. | Business | **Ops** | **It was not posted, even though the row is green.** Open the item in ClaimDesk, read the error, and post it or follow up by hand. | Never, unless every item does this. |
| E12 | Red row: "Save button not found". | The payment screen has no Save button within 10 seconds. | Report screen. Batch left unfinished (E01). | System | Dev | Check the item in ClaimDesk: it should not be posted. | Always: this red row blocks the batch. Send the log file name, clinic name, check number and time. |
| E13 | Red row: "Payment not confirmed after Save". | It clicked Save, but ClaimDesk's "Payment saved" message did not appear within 20 seconds. **The payment may still have posted.** | Report screen. Batch left unfinished (E01). | System | **Ops**, then Dev | **Check the payment in ClaimDesk before doing anything else.** Note whether it posted. **Don't re-run it or post it by hand until you've checked; it can post twice.** | Always: ops can't correct the row, and it blocks the batch. Send the clinic name, check number and whether it posted. |
| E14 | The run stopped half-way. The log's last line is `[WATCHDOG] no progress for 300s - killing run`. ClaimDesk is often left open. Later clinics never ran. | No item was posted for 5 minutes. Signing in, opening a clinic and retries don't count as progress, so a slow clinic or a run of clinics with no items can trigger it. | Run log, last line. Clinics after that point have no Report rows. Batch left unfinished (E01). | System | Ops, then Dev | Close ClaimDesk. List the clinics that have no Report rows; they need a re-run once dev clears the batch. | Always (the batch must be cleared). Also when it happens on 2 runs in a row. Send the log file name and the list of clinics that didn't run. |
| E15 | The bot clicks in a window that isn't ClaimDesk (a SQL tool, a folder, the launcher), and then ClaimDesk closes. | It takes the first window whose title **contains** "ClaimDesk", which can be the wrong one. | Usually only seen on screen. The log then shows clinic errors like E04 or E05. | System | Ops, then Dev | Close every other window with "ClaimDesk" in its title, then re-run once the batch is cleared. | It happens with no other such window open. |
| E16 | The same check number appears more than once for a clinic on the Report screen. | After a clinic-level failure, the bot repeats the whole clinic, and items that are still in the unposted list get a new row. | Report screen. Run log shows `[AUTO-RERUN]` for that clinic. | System | Ops | Read the latest row for that check. If any copy says "Posted successfully", check ClaimDesk to make sure it posted only once. | A payment posted twice. |

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| Any clinic-level failure (E03-E08, E15) | Closes ClaimDesk, starts it again, signs in again and repeats the whole clinic. No pause between tries. | 3 tries. Each try can take up to about 2 minutes of waiting. | Log: "left Pending after 3 attempts". The clinic gets no Report rows, the batch stays unfinished, and the bot moves to the next clinic. |
| Remittance Errors screen on one item | Presses Cancel. | Once, no retry. | Green "Remittance Errors on posting", next item. |
| Save button missing | None. | 10 seconds. | Red "Save button not found", next item. |
| No "Payment saved" message | None. | 20 seconds. | Red "Payment not confirmed after Save", next item. |
| Nothing posted for a long time | The watchdog kills the whole run. | 5 minutes. | Run ends, ClaimDesk may stay open, batch unfinished (E14). **The bot does not resume.** |

**How long to wait:** a clinic that is failing can take up to about 6-7 minutes over 3 tries. The watchdog may kill the run before the third try ends. If the log has not grown for more than 5 minutes and has no `[WATCHDOG]` line, escalate.

## 9. Known incidents

Dates are when the note was added to the code, not when the incident happened. In version 1.4.2, the three code "fixes" below are only notes: **the code itself didn't change.** Treat them as still open.

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| Noted 2026-10-23 (before 1.4.2) | Users stayed on 1.3.0 after an update. | The launcher kept the old program folder loaded until it was restarted. | After every update, fully close and reopen the launcher, then check the title bar (section 10). | Yes |
| Noted 2026-10-23 (before 1.4.2) | Red "Payment not confirmed after Save" rows that had really posted. | ClaimDesk saved more slowly than the bot waited, which was 10 seconds then and is 20 seconds now. | Always check in ClaimDesk first (E13). It can still happen when ClaimDesk takes more than 20 seconds. | Yes |
| Noted 2026-10-23 (before 1.4.2) | Clinics never processed; "not found in list" errors for half-names. | Clinic names were split at commas and semicolons. | One clinic per row (section 3). Names containing a comma still fail; report them to dev. | Partly |
| Noted 2026-10-23 (before 1.4.2) | The bot drove a SQL browser window, then closed the real ClaimDesk. | It picks any window whose title contains "ClaimDesk". **Still not fixed.** | Close other "ClaimDesk" windows before a run (E15). | Partly |
| 2026-09-01 run | "Wrong clinic opened" for a clinic with `&` in its name. During the retry the watchdog killed the run; the remaining clinics never ran and the batch stayed unfinished. | Sign-in and retries don't count as progress for the watchdog. The `&` may also have broken the name check. | E05, then E14. | Partly |

## 10. Releases and version check

- **How an update arrives:** through the ClaimDesk Poster launcher. The updater is not part of this code, so dev must confirm how updates are delivered.
- **How to confirm it applied:** the launcher title bar shows the new version. Today that is **1.4.2**.
- **If the version did not change:** fully close the launcher, open it again and check the title bar. If it still shows the old version, post in #rpa-support. Don't run the bot on an old version.

## 11. Escalating to dev

Post in Teams **#rpa-support**. Send:
- the exception ID from section 7 (for example E13)
- the batch number from the Report screen
- the time of the failure
- the run log **file name** from the `logs` folder, for example `run_20261023_093000.log`. Dev can open the folder; don't paste the log's contents.
- the clinic name and check number
- a screenshot of the Report screen

Never send passwords, the input Excel (it holds the ClaimDesk password), the bot's settings file, or patient data in chat.

## 12. Failure-class check

- F1 (missing prerequisite) covered in section 3 (ClaimDesk path set by dev) and E06. Fix-before-handover item 18.
- F2 (wrong window / focus) covered in sections 3 and 4 and E15. Fix-before-handover item 1.
- F3 (app slower or different than expected) covered in E05, E06, E07, E08 and E12, and section 8.
- F4 (input read differently) covered in section 3 input rules, E02, E04 and E10. Fix-before-handover items 10 and 11.
- F5 (marked done when nothing done) covered in section 6 (clinic Success) and fix-before-handover item 9.
- F6 (done but not confirmed) covered in E13 and fix-before-handover item 7.
- F7 (business exception shown as success) covered in section 6, E09 and E11. Fix-before-handover item 2.
- F8 (endless re-runs / watchdog) covered in E14, E16 and section 8. Fix-before-handover item 6.
- F9 (stopping the wrong way) covered in section 4. Fix-before-handover item 15.
- F10 (one stuck item blocks the queue) covered in E01, E12, E13 and E14. Fix-before-handover item 5.
- F11 (cause hidden from ops) covered in section 5. Fix-before-handover items 3, 4, 12 and 13.
- F12 (update didn't arrive) covered in section 10 and incident list. Fix-before-handover item 16.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | The window is matched on any title *containing* "ClaimDesk". That also matches the launcher ("ClaimDesk Poster"), the login window and SQL tools. Commit d9a2483 says this was fixed, but only a comment was added. | The bot drives the wrong window and closes the real ClaimDesk. | bot.py:66-70 (line 68), bot.py:185 |
| 2 | "Rejected by app" and "Skipped" map to Completed (green). The internal status column isn't shown on the Report screen. | Unposted items look done. | bot.py:27-30, report_screen.py:6 |
| 3 | `tech_comments` is written but never shown. | The technical cause is invisible to ops, who have no database access. | bot.py:118, report_screen.py:6 |
| 4 | Clinic-level failures write no Report row. Clinic and batch status are not shown anywhere ops can reach. | Ops must read raw logs to find failed clinics and can't see whether a batch is finished. | bot.py:143-147, report_screen.py:11-13 |
| 5 | One red row, or one failed clinic, keeps the batch Pending for ever. Any Pending batch refuses every new upload. Ops has no way to edit or clear it. | One item stops all posting until dev edits the database. | bot.py:150-154, bot.py:167-168 |
| 6 | The heartbeat fires only when an item is posted. Sign-in, clinic retries and clinics with no items don't count, so the watchdog can kill healthy runs. The kill skips cleanup (ClaimDesk is left open) and leaves the batch Pending, with no resume. | Half-finished runs and a blocked queue. | bot.py:36-49, bot.py:137, bot.py:145-146 |
| 7 | After a Save timeout, the bot doesn't re-check the grid. | Red rows that actually posted, and a double-posting risk. | bot.py:117-118 |
| 8 | Sign-in success isn't checked. | A wrong password shows as "Clinic not found" for every clinic. | bot.py:80-83 |
| 9 | Clinic marked Success even with zero items or all-red items. The wrong-clinic check runs instantly after the click, with plain text matching (`&`). | False Success; false "Wrong clinic opened". | bot.py:90-92, bot.py:140 |
| 10 | Clinic cells are split on `,` and `;`. A trailing comma creates an empty clinic. | Names containing a comma can never run; the doc only works around this. | bot.py:62, README.md:8 |
| 11 | The cutoff is compared as text, not as dates. | Wrong items deferred or posted when date formats differ. | bot.py:107 |
| 12 | Input errors and the "Pending batch exists" refusal aren't written to the log. | The cause is lost once the screen closes. | bot.py:54-58, bot.py:167-169 |
| 13 | `[RUN SUMMARY] batch N done` is logged even when the batch stays Pending. Errors are logged as `[ERROR] [ERROR]`. | "Done" misleads ops. | bot.py:144, bot.py:180 |
| 14 | A clinic retry adds new Report rows for items already logged. `taskkill /im ClaimDesk.exe` kills every ClaimDesk on the machine. | Duplicate rows; a person's ClaimDesk session is closed. | bot.py:136-139, bot.py:146 |
| 15 | There's no Stop button and no confirmed safe way to stop. The launcher code isn't in this repo. | Ops can't stop a run safely. | bot.py:157-180 (launcher missing) |
| 16 | The launcher/updater isn't in the repo. The 1.3.0 fix (d84ff92) is only a comment. | Users can stay on old versions without noticing. | report_screen.py:8, report_screen.py:14 |
| 17 | No alerting: `ALERT_SMTP` is defined but never used. | Nobody is told when a run fails or is killed. | .env (key name only), bot.py (not referenced) |
| 18 | Database tables aren't created by the code. The ClaimDesk path missing from the settings file fails every clinic with a cryptic message. | A new machine fails in confusing ways. | bot.py:20, bot.py:74, bot.py:166 |
| 19 | Security: `.env` is committed to git, including an unused password-fallback key. A committed log contains patient-identifying data. The ClaimDesk password sits in plain text in the input Excel. | Leak of credentials and PHI. | .env, logs/run_20260901_101500.log:3, bot.py:56 |
| 20 | The committed log contains messages the current code never writes (for example "could not bring window to foreground"). | Ops can't map those log lines to this doc. Confirm which build is in production. | logs/run_20260901_101500.log:5 |