Rpa_Skills/tests/evals/results/handoff/h-desktop-poster-full-r1.md

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 '' - not posted	Not posted on purpose: not an ACH payment	nothing, unless the client wants non-ACH posted (E12)
Deferred	grey	Check 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 '' - 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 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