Rpa_Skills/tests/evals/results/handoff/h-desktop-poster-screens-r2.md

# ClaimDesk Poster - ops handover

Version 1.4.2 · Written 2026-10-23 · Escalation: raise a ticket in the **RPA Support** queue

## 1. What the bot does

Posts remittance (insurance payment) checks into the **ClaimDesk** desktop app, one clinic at a time, from an input Excel file with three sheets: **Login** (ClaimDesk username and password), **Clinics** (the clinics to work) and **Settings** (a cutoff date). For every clinic it logs in to ClaimDesk, opens the clinic, and walks its list of unposted remittances. ACH payments dated on or before the cutoff are posted and saved; other payment methods are skipped and later dates are deferred. Every check it touches gets a row on the **Report screen** of the ClaimDesk Poster window. It runs when ops start it from the ClaimDesk Poster window; it does not run on a schedule. It drives one app: **ClaimDesk**.

## 2. How it works

```
ClaimDesk Poster window (what you use: start a run, Report screen)
   └─ starts → Posting bot ──drives──> ClaimDesk desktop app
                    │                   (do not touch while it runs)
                    ├─ writes → bot database (one row per check, clinic and batch status)
                    └─ writes → a run log file (dev only)
```

- **ClaimDesk Poster window** - where you pick the input Excel, start a run and read the Report screen. Its title bar shows the version.
- **Posting bot** - the automation itself. It runs in the background with no window of its own.
- **ClaimDesk** - the app the bot clicks through. The bot opens it, logs in, and force-closes it after every clinic.
- **Bot database** - stores the result for every check, plus clinic and batch status. Ops see part of it through the Report screen only.
- **Run log** - one file per run with technical messages. Ops cannot open it; dev reads it.

**One run, step by step:**
1. The bot checks that no earlier batch is still open (Pending). If one is, it refuses to start.
2. It reads the input Excel and creates a new batch with one entry per clinic.
3. For each clinic: start ClaimDesk → log in → click the clinic's link → wait for the remittance list.
4. For each check in the list: skip it (not ACH), defer it (after the cutoff), or click Post Payment → Save → wait for "Payment saved". One Report-screen row per check.
5. ClaimDesk is force-closed. If anything in step 3-4 broke, the whole clinic is retried from login (up to 3 tries).
6. After the last clinic the batch is marked Completed - **only if** no check ended red and every clinic finished.

## 3. Before a run

- [ ] ClaimDesk is installed and the bot's settings on this machine point to it. If not, every clinic fails at login and no rows appear (E04).
- [ ] The input Excel has exactly these sheet names: **Login**, **Clinics**, **Settings**. A missing Clinics or Settings sheet makes the run stop at once with no rows (E03).
- [ ] **Login** sheet: username in A2, password in B2, both filled. Check they are correct - the bot never checks that the login worked (E05). Keep this file private: it holds the ClaimDesk password.
- [ ] **Clinics** sheet: **one clinic per row** in column A from row 2, spelled exactly as the link in ClaimDesk.
  - Bad: `North Clinic, South Clinic` in one cell (or with `;`). Good: `North Clinic` in A2, `South Clinic` in A3.
  - A clinic whose real name contains a comma (e.g. `Smith, Jones Clinic`) **cannot be run by this version** - the bot cuts it into two names that don't exist. Do those clinics by hand and tell dev (Fix #7).
  - No trailing comma at the end of a cell.
- [ ] **Settings** sheet: cutoff date in B1. Leave B1 empty to post everything with no date check. After the run, spot-check a few Deferred and Posted rows against the cutoff - the date comparison is unreliable (E11).
- [ ] The last batch on this machine finished. If any row of the last run was red, the next run will refuse to start until dev clears it (E01, E15).
- [ ] The ClaimDesk Poster title bar shows version **1.4.2** (see section 10).

## 4. During a run

- **Hands off this machine.** No mouse, no keyboard. The bot clicks on screen positions, and your clicks can land in the wrong place.
- **Close every other window whose title contains "ClaimDesk"** before you start - database tools, Explorer folders, browser tabs, your own ClaimDesk session. The bot grabs the first window with "ClaimDesk" in its title and may work in the wrong one (E18).
- **Don't use ClaimDesk on this machine during a run.** After every clinic the bot force-closes *all* ClaimDesk windows, including one you opened yourself. Unsaved work in it is lost.
- **Don't close ClaimDesk to stop the bot.** The bot treats that as a failure and starts the clinic again from login.
- To stop the bot: this version has **no Stop button**, and it is not confirmed that closing the ClaimDesk Poster window stops it. If you must stop a run, raise an RPA Support ticket; until dev confirms the safe way, let the run finish (Fix #14).
- A run looks stuck when **no new rows appear on the Report screen for more than 5 minutes**. The bot ends the run by itself after 5 minutes with no new row (E16) - wait that long before raising a ticket.

## 5. Where to look when something goes wrong

Ops can open only the ClaimDesk Poster window (its Report screen and title bar), the bot's output files and the output folder. The bot writes **no output files** (no Excel, no screenshots) - the Report screen is the only result ops can read. Everything else below goes to dev.

| Question | Where to look |
|---|---|
| Did the run finish? | **Not shown on any ops screen in this version.** Signs it ended: ClaimDesk is closed and the Report screen has stopped growing. Whether the batch is Completed or still Pending is only visible to dev (Fix #4). |
| Which checks failed? | Report screen → pick the batch → File Status column red (Error). |
| Why did one check fail? | Report screen → the Comments column on that row. The technical reason is hidden; dev can read it (Fix #5). |
| Which clinic failed completely? | A clinic from your input with **no rows at all** on the Report screen. Either it had nothing to post, or the bot never got into it (E04-E09). Ops cannot tell which - check in ClaimDesk whether the clinic has unposted ACH checks; if it has, raise a ticket. |
| Did the bot already retry? | Not visible to ops. A clinic is always tried up to 3 times before it is given up. Repeated rows for the same check number are a sign of a retry (E17). |
| Which version is running? | ClaimDesk Poster title bar. |

## 6. Statuses

What you see on the Report screen (File Status + Comments):

| Status | Colour | Meaning | What ops does |
|---|---|---|---|
| Completed - "Posted successfully" | green | Payment posted and ClaimDesk showed "Payment saved". | Nothing. |
| Completed - "Remittance Errors on posting" | green | **NOT posted.** ClaimDesk showed its Remittance Errors screen and the bot pressed Cancel. Needs follow-up despite the green colour. | Review and post it by hand in ClaimDesk (E12). |
| Completed - "Payment method '<method>' - not posted" | green | Not ACH, so skipped on purpose. Not posted. | Nothing, unless the client wants non-ACH posted - then post by hand. |
| Deferred - "Check date <date> is after the cutoff - deferred" | grey | Dated after the cutoff; left unposted. A later run picks it up. | Spot-check the date against the cutoff (E11). |
| Error - "Save button not found" | red | Payment screen opened but had no Save button. Not posted. **Blocks the next run.** | E13. |
| Error - "Payment not confirmed after Save" | red | Save was clicked but "Payment saved" did not appear within 20 s. **It may have posted.** **Blocks the next run.** | Check in ClaimDesk first (E14). |
| Pending | amber | The screen supports this colour, but the current bot never writes it. | If you ever see it, raise a ticket. |

Statuses ops cannot see (dev reads them from the bot database):

| Status | Meaning |
|---|---|
| Clinic Success | The clinic's list was walked to the end. Set **even when some of its checks are red.** |
| Clinic Pending | The clinic failed 3 times, or the run was killed before it. It has no rows on the Report screen. |
| Batch Completed | No red rows and every clinic Success. |
| Batch Pending | Anything else. **A Pending batch stops every later run on this machine** until dev clears it. |

## 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 | Run doesn't start; no new rows. The message (if the window shows it) reads "A Pending batch exists - finish or clear it before a new upload". | At start it finds an earlier batch still Pending (see E15, E16). | On screen only, if shown. Not in the log. | System | Dev | Raise a ticket. Ops has no way to clear a batch. | Always. Send: machine, time, the last batch number on the Report screen, and its red rows. |
| E02 | Run doesn't start; no new rows. Message "'Login' sheet not found" or "UserName/Password missing in Login sheet (row 2)". | It checks the Login sheet exists and A2/B2 are filled. | On screen only, if shown. | Business | Ops | Fix the Login sheet name and fill A2 and B2. Start again. | Sheet and cells are correct and it still fails. |
| E03 | Run doesn't start; no new rows; a short technical message naming "Clinics" or "Settings". | A sheet named Clinics or Settings is missing - the bot crashes with no friendly message. | On screen only, if shown. | Business | Ops | Rename the sheets exactly: Clinics, Settings. Start again. | Names are exact and it still fails. Send the input file **without the Login sheet**. |
| E04 | Every clinic has no rows; ClaimDesk never appears or never shows its login window. | It waits 60 s for the "ClaimDesk Login" window; if ClaimDesk can't be started or the window never appears, the clinic is retried. | Run log (dev): "Login window not found". Clinic left Pending. | System | Bot, then Dev | Check ClaimDesk opens by hand on this machine. If it does, raise a ticket - the bot's ClaimDesk setting on this machine is likely wrong. | All clinics fail. Send machine, time, batch number. |
| E05 | Every clinic has no rows; ClaimDesk opens and the login screen stays or shows an error. | The bot types the username and password and clicks Sign in **without checking it worked**. It then fails on the next step. | Run log (dev): "ClaimDesk window not found" or "Clinic ... not found in list". | Business | Ops | Check the username and password in the Login sheet by logging in to ClaimDesk by hand. Fix and start again (after dev clears the batch, E01). | Login works by hand and the bot still fails. |
| E06 | One clinic has no rows. | It waits 10 s for a link with exactly the clinic's name; if none, the clinic is retried, then given up. | Run log (dev): "Clinic '<name>' not found in list". Clinic left Pending. | Business | Ops | Compare the spelling in the Clinics sheet with the link in ClaimDesk, character by character (spaces, `&`, commas). One clinic per row. Fix, then re-run that clinic. | Spelling is exact and it still has no rows. |
| E07 | One clinic has no rows, though spelled correctly. | Right after clicking the link, the clinic's name is not in ClaimDesk's title. It checks without waiting, so a slow screen can trigger it. | Run log (dev): "Wrong clinic opened, leaving Pending: <name>". Clinic left Pending. | System | Bot, then Dev | Bot retries 3 times. Then raise a ticket. | Always after 3 tries. Send machine, time, batch number, clinic name. |
| E08 | One clinic has no rows; ClaimDesk was on the clinic but showed no list. | It waits 60 s for the remittance list; if it never appears, the clinic is retried. | Run log (dev): "Remittance grid did not load". Clinic left Pending. | System | Bot, then Dev | Bot retries 3 times. Check in ClaimDesk whether the clinic's list opens by hand. Then raise a ticket. | Always after 3 tries. Send machine, time, batch number, clinic name. |
| E09 | One clinic has no rows, or only some of its checks. | Any other unexpected problem in the clinic (e.g. an odd row in the list) restarts the clinic from login. | Run log (dev): "[ERROR] Clinic '<name>' : ..." then "[DB] Clinic '<name>' left Pending after 3 attempts". | System | Bot, then Dev | Wait for the run to end. Raise a ticket. | Always after 3 tries. Send machine, time, batch number, clinic name. |
| E10 | Green "Payment method '<method>' - not posted". | The check's payment method is not ACH. | Report screen. | Business | Ops (if needed) | Nothing - by design. Post by hand only if the client wants it. | Never. |
| E11 | Grey "Check date <date> is after the cutoff - deferred" - or checks posted that should have been deferred. | It compares the check date to the Settings cutoff **as text, not as a date**. Depending on how ClaimDesk shows dates, it can defer the wrong checks or never defer anything. | Report screen. | Business | Ops, then Dev | After a run with a cutoff, compare a few Deferred and Posted rows' dates with the cutoff. Deferred ones are retried on a later run. | Any row is on the wrong side of the cutoff. Send batch number and two example check numbers. |
| E12 | **Green** "Remittance Errors on posting". | After Post Payment, ClaimDesk showed its "Remittance Errors" screen within 5 s; the bot pressed Cancel. | Report screen (green, so easy to miss - filter on the Comments text). | Business | Ops | Open the check in ClaimDesk, resolve the remittance error, and post by hand. | ClaimDesk shows no error for it. |
| E13 | Red "Save button not found". | The payment screen opened but no Save button appeared within 10 s. Not posted. | Report screen. | System | Dev | Check in ClaimDesk that it is not posted. Raise a ticket - this row also blocks the next run (E15). | Always. Send batch number, check number, time. |
| E14 | Red "Payment not confirmed after Save". | It clicked Save and waited 20 s for "Payment saved"; it never appeared. **The payment may still have posted** (this happened before - see section 9). | Report screen. | System | **Ops**, then Dev | **Check the payment in ClaimDesk first. Do not post it by hand until you have.** If it posted: nothing more in ClaimDesk. If not: post by hand, or let the next run pick it up. Either way raise a ticket so dev can correct the row - ops cannot edit rows, and the red row blocks the next run (E15). | Always (to clear the row). Send batch number, check number, and whether it posted. |
| E15 | Yesterday's run had a red row; today's run won't start (E01). | A batch is only Completed when it has no red rows and every clinic finished. One red row, or one clinic given up, keeps it Pending for good; a Pending batch blocks all new runs. | Batch status (dev only). | Business | Dev | Handle the red rows (E13, E14) and clinics with no rows (E04-E09) first, then raise a ticket to clear the batch. | Always. Send batch number and the list of red rows / missing clinics. |
| E16 | The run stops halfway: ClaimDesk stays open, later clinics have no rows, nothing new for 5+ minutes. Next run won't start (E01). | A watchdog ends the run when no new check row has been written for 5 minutes. Logging in, waiting for screens, retries and clinics with nothing to post do not count as progress, so several slow or empty clinics in a row can trigger it. | Run log (dev): "[WATCHDOG] no progress for 300s - killing run". Batch left Pending. | System | Dev | Close ClaimDesk. Raise a ticket to clear the batch. Then re-run only the clinics that have no rows. | Always. Send machine, time, batch number, last clinic with rows. |
| E17 | The same check number appears twice in one batch (e.g. a red row and later a green one). | When a clinic is retried, rows already written are kept and the clinic is walked again. | Report screen. | System | Ops, then Dev | The latest row is the true result. Checks that posted drop out of ClaimDesk's unposted list, so they are not posted twice. If a stale red row remains, it still blocks the batch - raise a ticket. | A stale red row remains. Send batch number and check number. |
| E18 | The bot clicks in a database tool, Explorer, or its own Poster window instead of ClaimDesk; or your own ClaimDesk session closes. | It takes the first window whose title contains "ClaimDesk", and force-closes every ClaimDesk process after each clinic. | Nowhere. Usually shows up as clinics with no rows (E05-E09). | System | Ops | Before a run, close every other window with "ClaimDesk" in its title. Don't use ClaimDesk on this machine during a run. | It happens with no other such window open. |

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| Anything goes wrong inside a clinic (login, clinic link, list, odd row, ClaimDesk closed) | Force-closes ClaimDesk, logs in again, starts the clinic from the top | 3 tries per clinic. One try can take up to about 2.5 minutes before it gives up. | Clinic given up (no rows / partial rows); next clinic. Batch stays Pending. |
| A single check fails (no Save button, save not confirmed) | **No retry.** Writes a red row. | - | Next check. The check stays unposted in ClaimDesk and is tried again on the next run. |
| ClaimDesk "Remittance Errors" screen | Clicks Cancel | Once | Green row "Remittance Errors on posting" - needs ops (E12). |
| No new check row for 5 minutes | Ends the whole run | 5 minutes | Run over. No restart, no resume. ClaimDesk left open. Batch Pending (E16). |
| Run stopped part-way | Nothing - there is no resume | - | Dev clears the batch; ops re-runs the missing clinics. |

**Waiting rule:** if the Report screen is still getting new rows, leave it. If nothing new for 5 minutes, the bot has ended or is about to - then act.

## 9. Known incidents

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| Before 1.4.2 | Users still on 1.3.0 after an update was released | The launcher kept using the old program folder until it was restarted | After every update, fully close and reopen ClaimDesk Poster and check the title bar (section 10). | Yes |
| Before 1.4.2 | Red "Payment not confirmed after Save" rows that had really posted | ClaimDesk took longer than the bot's 10 s wait | Wait raised to 20 s. Still check in ClaimDesk before acting (E14). | Partly |
| 2026-09-01, batch 41 | Run stopped mid-way after a clinic retry; next upload refused | Watchdog ended the run after 5 min with no new check row (retries don't count as progress); batch stayed Pending | E16, then E01. Not fixed in code (Fix #3). | Partly |
| Before 1.4.2 | Clinics with a comma in the cell were "not found" and skipped every run | The bot splits clinic cells on commas | One clinic per row (section 3). Names that really contain a comma still can't run (Fix #7). | Yes |
| Before 1.4.2 | Bot worked in a database tool whose title contained "ClaimDesk", then closed the real ClaimDesk | Window picked by title text | Close other "ClaimDesk" windows before a run (section 4). Marked fixed, but the code still matches by title (Fix #6). | Partly |

## 10. Releases and version check

- How an update arrives: through the ClaimDesk Poster launcher. Its update code is not in this repo, so dev must confirm the exact steps.
- How to confirm it applied: **fully close ClaimDesk Poster, open it again**, and check the title bar shows the new version (today: 1.4.2). Without the restart the old version keeps running.
- If the version did not change: raise an RPA Support ticket with the machine name and the version shown. Don't run with an old version.
- The bot's database and logs are per machine, so one machine on an old build does not overwrite another. Still keep every machine on the same version so results match this document.

## 11. Escalating to dev

Raise a ticket in the **RPA Support** queue. Send:
- the exception ID from section 7 (e.g. E14),
- machine name, date and start time of the run,
- batch number and, where relevant, clinic name and check number,
- what you checked in ClaimDesk (e.g. "payment did post"),
- a screenshot of the Report screen and, if relevant, of ClaimDesk.

Dev pulls the run log and database from the machine themselves - ops can't open those.

Never send: the ClaimDesk password, the input Excel's Login sheet, the bot's settings file, or patient details in chat or tickets.

## 12. Failure-class check

- **F1** covered in section 3 (ClaimDesk setting, sheet names, login cells) and E02-E05.
- **F2** covered in section 4 (close other "ClaimDesk" windows, hands off, don't use ClaimDesk) and E18; Fix #6.
- **F3** covered in E04, E06-E09, E13, E14 (60 s / 10 s / 5 s / 20 s waits, 3 clinic tries in section 8); Fix #9.
- **F4** covered in section 3 (one clinic per row, comma names, cutoff check) and E06, E11; Fix #7, #10.
- **F5** covered in section 6 (clinic Success even with red rows) and E05 (login never confirmed); Fix #8. The batch itself has a guard and is only Completed with no red rows and all clinics finished.
- **F6** covered in E14; Fix #11.
- **F7** covered in section 6 and E12 ("Remittance Errors on posting" shows green); Fix #1.
- **F8** covered in section 8 and E16 (5-minute watchdog, retries don't count as progress); Fix #3. No endless loop: retries stop at 3 per clinic.
- **F9** covered in section 4 (no Stop button; don't close ClaimDesk); Fix #14.
- **F10** covered in E01, E15, E16 (one red row blocks all later runs); Fix #2.
- **F11** covered in section 5 (only the Report screen is open to ops) and section 6 (hidden statuses); Fix #4, #5, #13.
- **F12** covered in section 10 and incident "Users still on 1.3.0"; Fix #17.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | "Rejected by app" (Remittance Errors, not posted) maps to Completed/green. | Unposted payments look done. | `bot.py:29` STATUS_MAP |
| 2 | Any Error row or Pending clinic keeps the batch Pending forever, and a Pending batch blocks every new run. No clear/discard/resume tool exists. | One red row stops the machine until dev edits the DB. | `bot.py:150-154`, `bot.py:167-168` |
| 3 | Watchdog heartbeat is only called per posted item; login, screen waits, retries and empty clinics don't beat. On kill (`os._exit`) the batch stays Pending and ClaimDesk stays open. | Healthy-but-slow runs get killed and then block the next run. | `bot.py:137`, `bot.py:44-49` |
| 4 | Clinic status and batch status are never shown to ops; a clinic that failed writes no Report row; the bot writes no output file ops can open. Clinic-level reasons exist only in the log. | Ops can't tell "nothing to post" from "never got in", or whether a run finished. | `bot.py:140`, `bot.py:147`, `bot.py:177-180`, `report_screen.py:6` |
| 5 | Report screen hides `status` and `tech_comments`. | Technical cause needs dev. | `report_screen.py:6` |
| 6 | Window chosen by title substring "ClaimDesk" - also matches the launcher "ClaimDesk Poster", "ClaimDesk Login" and any DB tool. Commit 34cae4a did not change the logic. Cleanup kills every ClaimDesk.exe. | Bot works in the wrong window; ops lose their own ClaimDesk session. | `bot.py:66-70`, `bot.py:146` |
| 7 | Clinic cells split on `,` and `;`; real names with commas can't run; trailing comma creates an empty clinic. | Clinics silently skipped. | `bot.py:62` |
| 8 | Login success never verified. | Wrong password shows up as unrelated clinic failures. | `bot.py:80-83` |
| 9 | Wrong-clinic title check runs right after the click with no wait. | False "wrong clinic" failures on a slow screen. | `bot.py:90-92` |
| 10 | Cutoff compared as text (`check_date > str(cutoff)`); an Excel date becomes `YYYY-MM-DD 00:00:00`. | Wrong checks deferred or posted with no warning. | `bot.py:107` |
| 11 | Save confirmation is a fixed 20 s wait with no follow-up check (e.g. re-read the unposted grid); no way for ops to correct a row afterwards. | False red rows that also block the batch. | `bot.py:116-118` |
| 12 | Clinic retry keeps earlier rows and re-inserts; stale Error rows keep the batch Pending. | Duplicate rows; batch blocked by already-resolved checks. | `bot.py:130-139`, `bot.py:122-126` |
| 13 | Startup failures (Pending batch, missing sheets/login) go to the console only, not the log; missing Clinics/Settings sheet crashes with a raw KeyError. | Ops see no reason, or a technical one. | `bot.py:53-63`, `bot.py:168` |
| 14 | No Stop mechanism; launcher code not in repo, so it's unknown whether closing the Poster window kills the bot. | Ops have no safe way to stop a run. | `bot.py:174-176` (launcher missing) |
| 15 | Sample log contains a patient name; the log lines in it don't match current code (older build logged item details at INFO). | PHI in log files. Scrub it and confirm no current build logs PHI. | `logs/run_20260901_101500.log:3` |
| 16 | Error lines are written as `[ERROR] [ERROR] ...`. | Breaks log searches for dev. | `bot.py:144` |
| 17 | Launcher/updater code not in repo; the 1.3.0 update fix can't be verified; version is a hard-coded string. | Machines may silently stay on old versions. | `report_screen.py:8`, `report_screen.py:14` |
| 18 | No notification on failure (an alert mail setting exists in `.env` but is unused). | Nobody hears about a killed or blocked run. | `bot.py` (none) |
| 19 | Odd/header rows in the remittance list raise an index error and restart the whole clinic. | Whole clinic retried for one bad row. | `bot.py:99-101` |
| 20 | No tests; none of the four fixes has a regression check. | Fixes can quietly regress. | repo root |