Rpa_Skills/tests/evals/results/handoff/h-desktop-poster-full-r4.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. It reads one input Excel file with three sheets: Login (the ClaimDesk user name and password), Clinics (the clinics to work on) and Settings (the cutoff date). For every clinic it signs in to ClaimDesk, opens the clinic, and works through the remittance list. ACH payments dated on or before the cutoff are posted and saved. Non-ACH payments are skipped, later-dated payments are deferred, and payments ClaimDesk rejects are cancelled. Every payment gets one row on the Report screen of the ClaimDesk Poster launcher. Each run is one batch. It drives one app: ClaimDesk.

2. How it works

ClaimDesk Poster launcher (the window you use; title shows the version)
   └─ starts → Posting process ──drives──> ClaimDesk desktop app
                    │                       (do not touch while it runs;
                    │                        the bot force-closes it after every clinic)
                    ├─ writes → Report screen (one row per payment)
                    ├─ writes → logs/run_<date>_<time>.log  (one file per run)
                    └─ watchdog: ends the run if no payment is handled for 5 minutes

• ClaimDesk Poster launcher: where you start a run and open the Report screen. The title bar shows the version.
• Posting process: runs in the background with no window of its own. It does the clicking in ClaimDesk.
• ClaimDesk: the target app. The bot starts it, signs in, and force-closes every ClaimDesk window on the machine when each clinic finishes, including one you opened yourself.
• Report screen: shows Clinic, Check No, File Status (coloured) and Comments for every payment the bot touched.
• Run log: a text file in the logs folder, named by the start time. Clinic-level problems are recorded only here.
• Watchdog: a timer inside the bot. If no payment is handled for 300 seconds, it ends the whole run.

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: Login, Clinics and Settings sheets.
3. It creates a new batch and marks every clinic as not yet done.
4. For each clinic: it starts ClaimDesk and signs in, opens the clinic from the clinic list, and checks that the window title shows that clinic's name.
5. It reads the remittance list and, for each payment, either skips it (not ACH), defers it (after the cutoff), cancels it (ClaimDesk shows "Remittance Errors"), or clicks Post Payment → Save and waits for "Payment saved".
6. Each payment gets a Report screen row straight away.
7. When the whole list is done, the clinic counts as done. If anything fails before that, the bot closes ClaimDesk and retries the clinic from sign-in, up to 3 attempts in total.
8. At the end, the batch is finished only if no row is red (Error) and no clinic was left undone. The log always ends with "[RUN SUMMARY] batch done", even when the batch is not finished.

3. Before a run

• The launcher title bar shows version 1.4.2 (see section 10).
• The last batch is finished. On the Report screen for the last batch there is no red (Error) row, and the last run log has no "left Pending" line. Otherwise the new run is refused (E01), and you need the dev team to release the old batch (E17).
• The settings file (.env) is in the bot folder and the bot's database is in its data folder. Dev sets both up at install. Ops should not edit them. Without the settings file every clinic fails (E04).
• The input Excel has three sheets named exactly Login, Clinics, Settings.
  • Login: user name in A2, password in B2. The password must be the current ClaimDesk password. A wrong password does not give a clear message: every clinic fails with "not found in list" (E07).
  • Clinics: column A, from row 2 down. One clinic per row.
  • Settings: the cutoff date in B1. If B1 is blank, there is no cutoff and every ACH payment is posted.
• Clinic names must contain no comma and no semicolon. The bot cuts every cell at commas and semicolons, even when the row holds one clinic.
  • Bad: North, East Clinic → the bot looks for "North" and "East Clinic", finds neither, and leaves both undone.
  • Good: North East Clinic (only if that is exactly how ClaimDesk spells it).
  • A clinic whose real ClaimDesk name has a comma or semicolon cannot be run by the bot. Post it by hand and tell the dev team.
• Spell each clinic exactly as in ClaimDesk's clinic list: spaces, capitals, &. Clinics with & in the name are known to fail with "Wrong clinic opened" (E08). Plan to post those by hand until dev fixes it.
• Cutoff date: enter it as a real Excel date, not text.
  • Bad: 30-Sep typed as text.
  • Good: a date cell showing 30/09/2026.
  • Even then, spot-check the first Deferred and Posted rows after the run. The bot compares dates as text, so it can get the order wrong (E13).
• The machine stays unlocked with the screen on for the whole run (no lock screen or screensaver). The bot clicks on the screen like a person.
• Close every window whose title contains "ClaimDesk", except the ClaimDesk Poster launcher. That includes your own ClaimDesk session and SQL or database tools showing "ClaimDesk" in the title (E18).

4. During a run

• Don't use the mouse or keyboard on this machine. The bot clicks on screen, and your input can send its clicks to the wrong place.
• Don't open ClaimDesk on this machine. After every clinic the bot force-closes all ClaimDesk windows, yours included.
• Don't open any window with "ClaimDesk" in its title (SQL or database tools, a second launcher). The bot may grab it instead of the real ClaimDesk (E18).
• To stop the bot: the bot has no Stop button, and its code does not watch the launcher. Closing the launcher may leave it running. The safe way:
  1. Open Task Manager and end the Python process that runs the bot.
  2. Close ClaimDesk.
  3. Tell the dev team. The batch is left unfinished and blocks the next run (E17).
  • Closing ClaimDesk alone does not stop the bot. It treats this as a failure and starts ClaimDesk again, up to 3 attempts per clinic.
• A run looks stuck when no new rows appear on the Report screen and no new lines appear in the run log for 5 minutes. The watchdog ends the run itself after 300 seconds with no payment handled. Wait 6 minutes before acting. After a watchdog stop, see E16.

5. Where to look when something goes wrong

Ops can open the launcher and its Report screen and the logs folder. The bot writes no other output files or folders. It does not save screenshots, Excel output or emails.

Question	Where to look
Did the run finish?	The run log (logs/run_<date>_<time>.log, newest file). The last line reads "[RUN SUMMARY] batch done" when the bot reached the end. If the last line is "[WATCHDOG] …", the run was cut off (E16). If the file is empty, the run never started (E01-E03).
Is the batch fully finished?	No screen shows this. It is finished only if the Report screen shows no red row for the batch and the log has no "left Pending" line.
Which payments failed?	Report screen → the batch → File Status = Error (red).
Which payments were not posted but show green?	Report screen → File Status = Completed → read Comments. Only "Posted successfully" means posted (see section 6).
Which clinics failed completely?	The Report screen shows nothing for them. Run log → search for "left Pending", then for "[ERROR] Clinic ''" to see why.
Why did one payment fail?	Report screen → Comments column. The bot writes no per-payment lines in the log.
Did the bot already retry a clinic?	Run log → lines "[AUTO-RERUN] attempt 2" / "attempt 3 for ''".
Which version is running?	The launcher title bar.

6. Statuses

The Report screen shows File Status (coloured) and Comments. The bot also stores an internal status per row, shown in brackets below. Ops cannot see it, but dev may quote it.

Status	Colour	Meaning	What ops does
Completed - "Posted successfully" (internal: Posted)	green	Payment posted and ClaimDesk showed "Payment saved".	Nothing
Completed - "Remittance Errors on posting" (internal: Rejected by app)	green	Not posted. ClaimDesk showed its Remittance Errors screen and the bot cancelled. Needs follow-up despite the green colour.	Review and post it in ClaimDesk by hand (E11)
Completed - "Payment method '' - not posted" (internal: Skipped)	green	Not posted on purpose. The bot only posts ACH.	Nothing, unless the client wants non-ACH posted (E12)
Deferred - "Check date is after the cutoff - deferred" (internal: Deferred)	grey	Not posted. Dated after the Settings cutoff. It stays in ClaimDesk for a later run.	Spot-check the date against the cutoff (E13)
Error - "Save button not found" (internal: Error)	red	The payment screen opened but had no Save button. Not saved. Blocks the batch.	E14
Error - "Payment not confirmed after Save" (internal: Error)	red	Save was clicked, but "Payment saved" did not appear within 20 s. It may have posted. Blocks the batch.	Check in ClaimDesk first (E15)
Pending	amber	The current version never writes this for a payment. It would mean an unknown result.	Report it to dev
Clinic: not done / done (internal: Pending / Success)	not shown	A clinic stays "not done" if all 3 attempts fail. The only trace is "left Pending" in the log. Blocks the batch.	E10
Batch: unfinished / finished (internal: Pending / Completed)	not shown	Finished only when no red row and no undone clinic. An unfinished batch blocks every new run.	E17

7. Exception catalogue

Quote the ID (E01…) in every message to #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 does nothing; the new log file is empty; no new rows on the Report screen. (If the launcher shows the bot's message: "A Pending batch exists - finish or clear it before a new upload".)	At start, the bot looks for any earlier batch that is not finished and refuses to start.	Not in the log file. The message goes only to the launcher's output, if it shows it.	System	Dev	Check the last batch for red rows and "left Pending" lines (E17). There is no screen to release a batch.	Always. Send: time of the attempt, the empty log file name, the last batch number.
E02	Run does nothing; empty log file. (Launcher may show "'Login' sheet not found" or "UserName/Password missing in Login sheet (row 2)".)	The Login sheet is missing, or A2 or B2 is empty.	Not in the log file. No batch is created.	Business	Ops	Fix the Login sheet (name exactly "Login", user in A2, password in B2) and run again.	The sheet is correct and it still fails.
E03	Run does nothing; empty log file; no friendly message.	The Clinics or Settings sheet is missing or misnamed. The bot stops with a technical error.	Not in the log file. No batch is created.	Business	Ops	Check that the sheets are named exactly "Clinics" and "Settings", then run again.	All three sheets are correct and it still fails. Send the time and the empty log file name.
E04	Every clinic fails. Log: "[ERROR] Clinic '' : 'CLAIMDESK_EXE'", then AUTO-RERUN and "left Pending" for each clinic.	The bot cannot find the ClaimDesk program path in its settings file.	Run log	System	Dev	Don't re-run. The settings file is missing or incomplete.	Always. Send the log file name.
E05	Log: "[ERROR] Clinic '' : Login window not found"	The ClaimDesk sign-in window did not appear within 60 s of starting ClaimDesk.	Run log	System	Bot, then Ops	The bot retries the clinic up to 3 times. If it is left undone: open ClaimDesk by hand on this machine and check it starts and shows its sign-in window.	ClaimDesk starts fine by hand but the bot still gets this. Send log file name and time.
E06	Log: "[ERROR] Clinic '' : ClaimDesk window not found"	After sign-in, no window with "ClaimDesk" in its title exists.	Run log	System	Bot, then Dev	The bot retries up to 3 times.	It happens on 2 runs in a row. Send log file name and time.
E07	Log: "[ERROR] Clinic '' : Clinic '' not found in list"	The clinic link with that exact name did not appear within 10 s.	Run log; clinic left undone (no Report rows)	Business	Ops	1) Check the spelling matches ClaimDesk exactly. 2) Check the name has no comma or semicolon; if the log shows a piece of a name, that is the comma split (section 3). 3) If every clinic shows this, check the Login sheet password: a failed sign-in looks like this.	Spelling and password are correct. Send log file name, time, clinic name.
E08	Log: "[ERROR] Clinic '' : Wrong clinic opened, leaving Pending: "	After clicking the clinic, the window title does not contain the clinic's name. Despite the wording, the bot still retries 3 times.	Run log; clinic left undone	System	Ops, then Dev	Check the spelling. Names with & are known to fail here: post that clinic by hand in ClaimDesk.	Spelling is exact. Send log file name, time, clinic name.
E09	Log: "[ERROR] Clinic '' : Remittance grid did not load"	The remittance list did not appear within 60 s after opening the clinic.	Run log	System	Bot, then Dev	The bot retries up to 3 times. If ClaimDesk is slow for everyone, run again later.	Same clinic on 2 runs. Send log file name and time.
E10	Log: "[DB] Clinic '' left Pending after 3 attempts". Few or no Report rows for that clinic.	All 3 attempts at the clinic failed.	Run log only (not on the Report screen)	System or Business	Ops	Read the "[ERROR] Clinic ''" lines just above it and follow E04-E09. The batch stays unfinished (E17).	The cause is a Dev row above.
E11	Green Completed, Comments "Remittance Errors on posting"	After Post Payment, ClaimDesk showed its "Remittance Errors" screen within 5 s. The bot clicked Cancel.	Report screen	Business	Ops	It was not posted. Review the remittance in ClaimDesk and post or correct it by hand.	Never, unless every payment shows it
E12	Green Completed, Comments "Payment method '' - not posted"	The payment method in the list is not ACH.	Report screen	Business	Ops	Nothing, unless the client wants that method posted. Then post by hand.	Never
E13	Grey Deferred, Comments "Check date is after the cutoff - deferred"	The check date is later than the Settings cutoff (compared as text).	Report screen	Business	Ops	Compare the date with the cutoff. If it is really before the cutoff, post it by hand. Do the same check in reverse: a Posted row dated after the cutoff.	A wrong Deferred or Posted is found. Send batch number, check number, cutoff.
E14	Red Error, Comments "Save button not found"	The payment screen opened but no Save button appeared within 10 s.	Report screen	System	Ops, then Dev	Check that payment in ClaimDesk: it was not saved. Post it by hand if needed. The bot may have left the payment screen open, so the next payment in that clinic may also fail.	Always (the row blocks the batch). Send batch number, check number, log file name, time.
E15	Red Error, Comments "Payment not confirmed after Save"	Save was clicked, but "Payment saved" did not appear within 20 s.	Report screen	System	Ops	Check the payment in ClaimDesk before doing anything. It has often really posted. Do not post it again by hand if it shows as posted. If it is not posted, post it by hand or leave it for the next run. Either way the red row stays, and only dev can correct it.	Always, so dev can correct the row and release the batch. Send batch number, check number, and whether it posted in ClaimDesk.
E16	Run ended mid-way. Last log line "[WATCHDOG] no progress for 300s - killing run". No "[RUN SUMMARY]" line. ClaimDesk may still be open.	No payment was handled for 300 s. This also happens during normal slow sign-ins and retries, or when several clinics in a row have no payments.	Run log	System	Ops, then Dev	Close ClaimDesk. Note which clinics have no Report rows. The batch is left unfinished (E17).	Always. Send log file name and the clinic it was on.
E17	The next run is refused (E01), or a batch never finishes	Any red Error row, or any clinic left undone, keeps the batch unfinished. An unfinished batch blocks every new run.	Report screen (red rows) + run log ("left Pending")	Business / System	Ops, then Dev	1) List the red rows and "left Pending" clinics. 2) Settle each one in ClaimDesk (E10, E14, E15). 3) Ask dev to release the batch. Ops has no screen for this.	Always. Send batch number and the list from step 1.
E18	ClaimDesk closes by itself, or your own ClaimDesk session closes; or the bot works in the wrong window	The bot takes the first window with "ClaimDesk" in its title (this can be a SQL tool, the launcher or the sign-in window). It force-closes every ClaimDesk window after each clinic.	Not recorded. May show as E07 or E08 in the log.	System	Ops	Close all other "ClaimDesk" windows before a run. Don't use ClaimDesk on this machine during a run.	It happens with no other ClaimDesk window open
E19	The same check number appears twice or more for one clinic on the Report screen	When a clinic is retried, rows from the earlier attempt stay, and Skipped, Deferred or Rejected payments are recorded again.	Report screen; "[AUTO-RERUN]" in the log	System	Ops	Treat duplicates as one payment. Check ClaimDesk for the real state.	Two rows for one check disagree (e.g. one Posted, one Error)

8. What the bot recovers by itself

Problem	What the bot does	Limit	After the limit
Any clinic-level failure (sign-in, clinic not found, wrong clinic, list didn't load, unexpected screen)	Force-closes ClaimDesk, starts it again, signs in and re-does the clinic from the start	3 attempts per clinic. Each attempt can wait up to 60 s for sign-in, 10 s for the clinic link, 60 s for the list.	Log "left Pending". The bot moves to the next clinic and the batch stays unfinished.
One payment fails (Save button missing, save not confirmed)	No retry. Records a red Error row and moves to the next payment.	none	Red row; batch unfinished
ClaimDesk "Remittance Errors" screen	Clicks Cancel and moves on	waits 5 s for it	Green "Remittance Errors on posting" row
No progress	The watchdog ends the whole run	300 s with no payment handled	Run stops. ClaimDesk is left open and the batch unfinished (E16).
Bot stopped or crashed	No resume. A new run starts a new batch from the Excel, and only after the old batch is released by dev.	none	E01 / E17

9. Known incidents

Dates were not kept in the project history. Versions are given where known. Each "fix" recorded in history added only a note to the code. The code change itself is not in this repository, so treat the risks as still open.

When / version	What ops saw	Cause	What to do now	Ops could handle?
before 1.4.2	Users stayed on 1.3.0 after an update	The launcher kept using the old folder until it was restarted	After every update, close the launcher fully and reopen it. Check the title bar version (section 10).	Yes
before 1.4.2	Red "Payment not confirmed after Save" rows for payments that had really posted	ClaimDesk took longer to save than the bot waited. The wait was raised from 10 s to 20 s but is still a fixed wait.	Always check in ClaimDesk first (E15)	Partly: ops can check, only dev can correct the row
before 1.4.2	Clinics silently never posted	Clinic names with commas were cut into pieces	One clinic per row and no comma or semicolon in any name. Clinics whose real name has a comma are posted by hand (section 3).	Partly
before 1.4.2	The bot drove a SQL tool window, then closed the real ClaimDesk	Any window with "ClaimDesk" in its title is grabbed	Close all other "ClaimDesk" windows before a run (E18). The code still matches this way.	Partly
2026-09-01 run	A clinic with & in its name failed "Wrong clinic opened", re-ran, then the watchdog killed the run	& name check (E08), plus the watchdog counting retries as "no progress" (E16)	Post & clinics by hand. Escalate watchdog stops.	No

10. Releases and version check

• How an update arrives: through the ClaimDesk Poster launcher. The launcher and updater are not in this repository; dev owns them.
• How to confirm it applied: the launcher title bar shows the new version (currently 1.4.2).
• If the version did not change: close the launcher completely (check that it is gone from Task Manager) and reopen it. Still old? Post in #rpa-support with the machine name and the version shown.
• Each install keeps its own Report data, and nothing shared is rewritten at start. A machine on an old version does not damage another. Still keep all machines on the same version so the doc matches what you see.

11. Escalating to dev

Post in #rpa-support (Teams), to the RPA dev team.

Send:

• the exception ID from section 7 (e.g. E15)
• the batch number (from the "[RUN SUMMARY] batch " line or the Report screen)
• the time of the failure
• the run log file name (logs/run_<date>_<time>.log) and the machine name
• the clinic name and check number
• for E15: whether the payment shows as posted in ClaimDesk

Never send:

• passwords
• the settings file
• the input Excel (its Login sheet holds the ClaimDesk password)
• patient or customer data in chat

Don't paste log lines into Teams: older run logs can contain patient names. Dev reads the log on the machine.

12. Failure-class check

• F1 (missing prerequisite) covered in section 3 (settings file, database, input sheets) and E02, E03, E04. The missing-database case → Fix #19.
• F2 (wrong window / focus) covered in sections 3 and 4 and E18. Code fix → Fix #6, #7.
• F3 (app slower or different than expected) covered in E05, E06, E07, E09, E11, E14, E15 with the timeouts in section 8; unlocked screen rule in section 3. The 5 s popup wait → Fix #15.
• F4 (input read differently) covered in section 3 (comma/semicolon split, &, cutoff date, password) and E07, E08, E13. Code → Fix #8, #9, #10.
• F5 (marked done when nothing was done) → Fix #13: a clinic counts as done with zero payments and no confirmation. Not visible to ops.
• F6 (action happened, not confirmed) covered in E15 and incident 2. Code → Fix #14.
• F7 (business exception shown as success) covered in section 6 and E11, E12. Mapping → Fix #3.
• F8 (endless re-runs / watchdog) covered in section 8 and E16 (3 attempts per clinic, so no endless loop). Watchdog heartbeat → Fix #5.
• F9 (stopping the wrong way) covered in section 4. No Stop button → Fix #18.
• F10 (one stuck item blocks the queue) covered in E01, E17 and section 3. No release tool → Fix #1.
• F11 (cause hidden from ops) covered in section 5 (log-only clinic failures, no visible batch status). → Fix #2, #4, #17.
• F12 (update didn't arrive) covered in section 10 and incident 1. Launcher not in repo → Fix #18.

13. Fix before handover (dev team)

#	Gap	Why it hurts ops	Where (file:line)
1	Any Error row or undone clinic keeps the batch Pending forever, and any Pending batch blocks every new upload. There is no screen or tool to release a batch.	Ops are blocked after a single red row and need dev for every release (E17)	bot.py:150-154, bot.py:167-168
2	The "Pending batch exists" refusal and input-sheet errors are raised without being logged	Ops see an empty log file and no reason (E01-E03)	bot.py:167-169, bot.py:52-63
3	"Rejected by app" and "Skipped" map to Completed (green)	Unposted payments look done (E11, E12)	bot.py:27-33
4	Report screen hides status and tech_comments; clinic status and batch status are not shown anywhere; clinic failures produce no Report rows	Causes are only in the DB (ops can't open it) or the log	report_screen.py:6, bot.py:140, bot.py:147
5	The watchdog heartbeat beats only per payment, so it kills runs during normal sign-in, retries or empty clinics. os._exit skips cleanup, leaving ClaimDesk open and the batch Pending.	False kills, blocked next run (E16)	bot.py:36-49, bot.py:137
6	The ClaimDesk window is matched by title substring, which can match the launcher ("ClaimDesk Poster"), "ClaimDesk Login" or a SQL tool. Commit d9a2483 added only a comment; there is no code fix.	Wrong window driven (E18)	bot.py:66-70, bot.py:83, bot.py:185
7	taskkill /im ClaimDesk.exe /f after every attempt kills every ClaimDesk process on the machine	Users lose their own ClaimDesk work	bot.py:146
8	Clinic cells are split on , and ;, even with one clinic per row. The README advice doesn't prevent it.	Clinics with commas can never be run (E07)	bot.py:62, README.md:8
9	The "wrong clinic" check needs the exact name in the window title. It fails for & names.	& clinics always fail (E08)	bot.py:91
10	The cutoff is compared as text (check_date > str(cutoff))	Payments wrongly deferred or posted (E13)	bot.py:107
11	A failed sign-in is not detected. It surfaces later as "Clinic not found in list".	Misleading message (E07)	bot.py:82-83
12	Retries re-insert report rows. Rows carry no timestamp or attempt number.	Duplicate rows (E19)	bot.py:122-139
13	A clinic is marked Success with zero payments, with no positive confirmation	A clinic done on the wrong screen looks finished	bot.py:140
14	"Payment not confirmed" relies on a fixed 20 s wait with no re-check of the list. Ops cannot correct the row.	False red rows that block the batch (E15)	bot.py:117-118, bot.py:21
15	The Remittance Errors popup wait is only 5 s. After "Save button not found", the payment screen is left open.	A slow popup or open screen turns into Error rows or clinic retries (E14)	bot.py:110-115
16	The grid is read live while posting, header rows are not skipped, and a short row raises IndexError	Skipped or double-handled payments; spurious clinic retries	bot.py:95-101
17	"[RUN SUMMARY] batch N done" is logged even when the batch is not completed	Ops think the batch is finished	bot.py:180
18	No Stop button; the worker doesn't stop when the launcher closes. The launcher and updater code (incl. the d84ff92 fix) are not in this repo.	Ops must use Task Manager. The update fix can't be verified.	bot.py:157-180, report_screen.py:14
19	The data/ folder and database schema are not in the repo or created by code	A fresh install fails with a database error	bot.py:20, bot.py:166
20	.env and a run log containing a patient name are committed to git. The ClaimDesk password sits in plain text in the input Excel.	Credential and PHI exposure. The log must be purged from history and old logs on ops machines checked.	.env, logs/run_20260901_101500.log:3, bot.py:56