Rpa_Skills/tests/evals/results/handoff/h-desktop-poster-screens-r3.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

ClaimDesk Poster posts remittance payments into the **ClaimDesk** desktop app, one clinic at a time. It takes one input Excel with three sheets: **Login** (the ClaimDesk user name and password), **Clinics** (the clinics to post) and **Settings** (the cutoff date). For each clinic it signs in to ClaimDesk, opens the clinic, and goes through every row in the remittance list. Each ACH payment dated on or before the cutoff is posted and saved. Other payments are skipped or deferred. Every row it handles appears on the **Report screen** of the ClaimDesk Poster window, with a colour and a comment. The only app it drives is **ClaimDesk**. Do not touch ClaimDesk while the bot runs.

## 2. How it works

```
ClaimDesk Poster (the window you use: start a run, Report screen)
   └─ starts → posting bot (runs in the background) ──drives──> ClaimDesk desktop app
                     │                                       (do not touch while it runs)
                     ├─ writes → the bot's own database (one row per remittance, clinic and batch status)
                     ├─ writes → a run log (developers only)
                     └─ watchdog: ends the run if nothing moves for 5 minutes
```

- **ClaimDesk Poster** is the window ops uses. It starts a run and shows results on the Report screen. Its title bar shows the version.
- **The posting bot** runs in the background. It opens ClaimDesk, signs in, and clicks through it like a person would.
- **ClaimDesk** is the target app. The bot opens it fresh for each clinic and **force-closes every ClaimDesk window on the machine** when it finishes that clinic.
- **The database** feeds the Report screen. Ops cannot open it directly.
- **The run log** records clinic-level errors and retries. Only developers can open it.
- **The watchdog** ends the whole run if no remittance row has been processed for 5 minutes.

**One run, step by step:**
1. The bot refuses to start if the previous batch is still open (see E01).
2. It reads the input Excel and creates a new batch. Every clinic starts as Pending.
3. For each clinic, it opens ClaimDesk and signs in with the user name and password from the Login sheet.
4. It clicks the clinic's name in ClaimDesk's clinic list.
5. It waits for the remittance list, then handles each row in turn:
   - not ACH → skip;
   - check date after the cutoff → defer;
   - otherwise → Post Payment, then Save, then wait for "Payment saved".
6. It force-closes ClaimDesk. If anything in steps 3-5 failed, it repeats the whole clinic, up to 3 attempts in total.
7. After the last clinic, it closes the batch. This only happens if no row is red and every clinic finished.

## 3. Before a run

- [ ] ClaimDesk is installed on this machine, and the bot's settings file points at it. Dev sets this up once per machine. If it is missing, every clinic fails (E06).
- [ ] ClaimDesk is **closed**, and no other window has "ClaimDesk" in its title. That includes SQL or database tools (see section 4).
- [ ] The machine stays signed in and unlocked, with the screen on, for the whole run. The bot clicks with the real mouse.
- [ ] **Login sheet:** user name in cell A2, password in cell B2. Both must be filled in (E03). The password must be current. A wrong password shows up as "clinic not found" for every clinic (E07).
- [ ] **Clinics sheet:** column A, starting at row 2, **one clinic per row**. Spell each name exactly as it appears in ClaimDesk's clinic list.
  - Bad: `North Clinic, South Clinic` in one cell, or `North Clinic; South Clinic`.
  - Good: `North Clinic` in A2, `South Clinic` in A3.
  - **A clinic whose real name contains a comma cannot be posted by this bot.** It is always cut into two names that don't exist (E07). Post that clinic by hand.
  - No comma at the end of a cell. `North Clinic,` creates an extra empty clinic that fails.
- [ ] **Settings sheet:** the cutoff date goes in cell B1, typed as a real Excel date. If B1 is empty, nothing is deferred and every ACH payment is posted, whatever its date.
- [ ] The previous run ended with **no red rows and no clinic missing** from the Report screen. Otherwise this upload is refused (E01, E16).
- [ ] The ClaimDesk Poster title bar shows version 1.4.2 (see section 10).

## 4. During a run

- **Hands off the machine.** Don't use the mouse or keyboard. The bot clicks with the real mouse, so your clicks and its clicks get mixed up.
- **Don't open ClaimDesk, or any window with "ClaimDesk" in its title, on this machine during a run.** That includes SQL or database tools. The bot picks the first window with "ClaimDesk" in its title, so it can end up working in the wrong one. At the end of each clinic it also force-closes **every** ClaimDesk window on the machine, including one you are using.
- **Closing ClaimDesk does not stop the bot.** The bot treats it as a failure, reopens ClaimDesk and tries that clinic again.
- **To stop the bot:** the code in this repo has no Stop button. Raise an RPA Support ticket if a run must be stopped. Do not just close windows. See *Fix before handover* item 15.
- **A run looks stuck** when no new rows appear on the Report screen for several minutes. The bot ends the run by itself after **5 minutes with no new row**, so wait at least that long. After that the batch stays open and the next upload is refused (E15).

## 5. Where to look when something goes wrong

Ops can open only the ClaimDesk Poster window, its Report screen, and the bot's output files and folder. The bot writes no output files today. Everything ops can see is on the Report screen. The run log and the database are for developers only.

| Question | Where to look |
|---|---|
| Did the run finish? | Ops cannot see the batch status. Compare the Report screen with your Clinics sheet: every clinic must have rows, and no row should be red. Otherwise raise a ticket. |
| Which rows failed? | Report screen → File Status = Error (red) |
| Which rows need a person even though they are green? | Report screen → Comments column: "Remittance Errors on posting" and "Payment method '…' - not posted" |
| Why did one row fail? | Report screen → Comments column, then the matching row in section 7 |
| A clinic has no rows at all | The clinic failed all 3 attempts (E05-E09). The reason is only in the run log, so raise a ticket naming the clinic. |
| Did the bot already retry? | Ops can't see this. Every clinic gets up to 3 attempts automatically. A row that appears twice for the same check number is a sign of a retry (E17). |
| Which version is running? | The ClaimDesk Poster title bar |

## 6. Statuses

What the Report screen shows. File Status is the colour; Comments is the text.

| Status (File Status - Comments) | 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 cancelled. Needs follow-up. | Review and post it in ClaimDesk by hand (E10) |
| Completed - "Payment method '<method>' - not posted" | green | **NOT posted on purpose.** Not an ACH payment. | Nothing, unless the client wants non-ACH payments posted; then post it by hand (E13) |
| Deferred - "Check date <date> is after the cutoff - deferred" | grey | Not posted. The check date is after the Settings cutoff. | Nothing. A later run with a later cutoff picks it up. Spot-check the date (E14). |
| Error - "Save button not found" | red | The payment screen had no Save button. Probably not posted. | E11 |
| Error - "Payment not confirmed after Save" | red | Save was clicked but "Payment saved" never appeared within 20 s. **It may have posted.** | Check in ClaimDesk first (E12) |
| Pending | amber | The code never writes this on a row today. If you see it, something unexpected happened. | Raise a ticket |
| Clinic: Pending / Success | not shown | Stored by the bot, not on any screen. A clinic left Pending has **no rows** on the Report screen. | See section 5 |
| Batch: Pending / Completed | not shown | The batch stays Pending while any row is red or any clinic is unfinished. A Pending batch blocks the next upload. | E16 |

For developers: the stored row status behind these is Posted, Rejected by app, Skipped, Deferred or Error. It is not shown to ops.

## 7. Exception catalogue

For any **Dev** row, the ticket must include:
- the exception ID;
- the date and time of the run (to the minute);
- the clinic name and check number from the Report screen;
- a screenshot of the Report screen, and of ClaimDesk if it is still open.

Dev finds the run log from the run time.

| ID | What you see | How the bot identifies it | Where it is recorded | Type | Who acts | What to do | Escalate when |
|---|---|---|---|---|---|---|---|
| E01 | You start a run and nothing happens; no new rows appear | Before reading the Excel, the bot checks for an unfinished (Pending) batch and refuses to start. Message: "A Pending batch exists - finish or clear it before a new upload". | Nowhere ops can see. The message goes to the background window only. | System | Dev | Ops cannot clear the batch. Raise a ticket. | Always |
| E02 | The run ends at once; no new rows | The Excel has no sheet named "Login" | Nowhere ops can see | Business | Ops | Rename the sheet to exactly `Login`, then run again | It still fails with the sheet present |
| E03 | The run ends at once; no new rows | The Login sheet's A2 or B2 is empty ("UserName/Password missing in Login sheet (row 2)") | Nowhere ops can see | Business | Ops | Fill in A2 (user name) and B2 (password) | It still fails with both filled |
| E04 | The run ends at once; no new rows | The Excel has no sheet named "Clinics" or "Settings" | Nowhere ops can see | Business | Ops | Add the missing sheet with exactly that name | It still fails with all three sheets |
| E05 | A clinic has no rows on the Report screen | The ClaimDesk sign-in window did not appear within 60 s, on all 3 attempts | Run log only; clinic left Pending | System | Bot, then Dev | Wait for the run to end. Check that ClaimDesk opens normally on this machine by hand. | Every clinic has no rows, or it repeats on the next run |
| E06 | **No** clinic has any rows; the run ends quickly | ClaimDesk's location is missing from the bot's settings, so it cannot start ClaimDesk | Run log only; every clinic left Pending | System | Dev | Raise a ticket | Always |
| E07 | One clinic, or every clinic, has no rows | The bot clicks the clinic's name in ClaimDesk's list; the name was not there within 10 s ("Clinic '<name>' not found in list"). Usual causes: a spelling difference, a comma name that was cut in two, or a wrong or expired password (then **every** clinic fails this way). | Run log only; clinic left Pending after 3 attempts | Business | Ops | Compare the spelling with ClaimDesk's list exactly. Put one clinic per row. Check that the Login sheet password still works by signing in to ClaimDesk by hand. | Spelling and password are both correct |
| E08 | A clinic has no rows, or only some rows from a partial attempt | Right after clicking the clinic, the bot checks that ClaimDesk's title contains the clinic name ("Wrong clinic opened, leaving Pending"). The bot still retries it. Names with `&` or other special characters often fail this check. | Run log only; clinic left Pending after 3 attempts | System | Bot, then Ops | Post that clinic by hand in ClaimDesk this time | It happens to a clinic without special characters |
| E09 | A clinic has no rows | The clinic opened, but the remittance list did not appear within 60 s, on all 3 attempts ("Remittance grid did not load") | Run log only; clinic left Pending | System | Bot, then Dev | Check by hand whether that clinic's list opens in ClaimDesk; it may simply be slow | It repeats on the next run |
| E10 | Green row, Comments "Remittance Errors on posting" | After Post Payment, ClaimDesk showed its "Remittance Errors" screen within 5 s. The bot pressed Cancel. | Report screen | Business | **Ops** | **This payment was not posted.** Open it in ClaimDesk, resolve the remittance error, post it by hand. | ClaimDesk shows no error for it |
| E11 | Red row, "Save button not found" | After Post Payment, no Save button appeared within 10 s | Report screen | System | Ops, then Dev | Check the payment in ClaimDesk. It is most likely not posted. Post it by hand if needed. The red row keeps the batch open (E16). | It happens on more than one row |
| E12 | Red row, "Payment not confirmed after Save" | Save was clicked, but ClaimDesk's "Payment saved" message did not appear within 20 s | Report screen | System | **Ops** | **Check the payment in ClaimDesk before doing anything else. It may have posted.** If it posted, do not post it again. Raise a ticket so dev corrects the row; ops cannot edit it, and the red row keeps the batch open (E16). If it did not post, post it by hand. | Every time, so the row can be corrected |
| E13 | Green row, "Payment method '<method>' - not posted" | The remittance's method is anything other than ACH | Report screen | Business | Ops | Nothing, unless the client wants it posted; then post it by hand | - |
| E14 | Grey row, "Check date <date> is after the cutoff - deferred" | The check date is after the Settings B1 cutoff. The comparison is done on the date text, so unusual date formats can give the wrong answer. | Report screen | Business | Ops | Nothing for a real future date. If the date is plainly before the cutoff, raise a ticket. | A date before the cutoff was deferred, or a later date was posted |
| E15 | The run stops partway: later clinics have no rows; ClaimDesk may still be open | The watchdog saw no new row for 5 minutes and ended the whole run. It often fires when a clinic fails all 3 attempts, or has no remittances, because no rows are produced. | Run log only; the batch stays open | System | Dev | Close ClaimDesk. Raise a ticket listing the clinics with no rows. The next upload will be refused until dev clears the batch. | Always |
| E16 | The next upload is refused (E01) after a run that "finished" | The batch only closes when no row is red and every clinic finished. One red row or one failed clinic keeps it open, and an open batch blocks every new upload. | Not shown to ops | Business | Ops, then Dev | Find the red rows and the clinics with no rows on the Report screen. Handle each one by its ID above. Then raise a ticket asking dev to close or clear the batch. | Always: only dev can clear it |
| E17 | The same check number appears twice for one clinic | A clinic was retried after a failure partway through its list. The first attempt's rows stay, and the retry writes the rows again. | Report screen | System | Ops | Trust the **latest** row for that check. An old red row from the first attempt still keeps the batch open (E16). | The two rows disagree on whether it was posted |
| E18 | ClaimDesk you were using closes by itself, or the bot clicks inside a database tool or the Poster window | The bot takes the first window with "ClaimDesk" in its title, and force-closes all ClaimDesk windows after each clinic | Not recorded | System | Ops, then Dev | Close all other "ClaimDesk" windows before a run. 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 fails while signing in, opening the clinic or walking its list (E05-E09, or a ClaimDesk button missing mid-list) | Force-closes ClaimDesk, signs in again and repeats the whole clinic | 3 attempts per clinic. Each attempt can take up to about 2-3 minutes (60 s sign-in, 10 s clinic list, 60 s remittance list). | Clinic left Pending with no new rows; the bot moves to the next clinic |
| One remittance row fails (E11, E12) | **No retry.** Writes the red row and moves to the next remittance. | - | Row stays red; batch stays open |
| No new row for 5 minutes | Ends the entire run | 5 minutes, checked every 10 s | Run over; batch open; ClaimDesk may be left open (E15) |
| Next run | **No resume.** A new upload is refused while the old batch is open. | - | Dev must clear the batch (E01, E16) |

So: **once a clinic has had 3 attempts, or the run has been quiet for 5 minutes, the bot will not try again by itself.** Wait for that, then act.

## 9. Known incidents

Newest first.

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| Before 1.4.2 | Users kept running 1.3.0 after an update | The launcher kept using the old program folder until it was restarted | After every update, close and reopen ClaimDesk Poster, and check the title bar shows the new version (section 10) | Yes |
| Before 1.4.2 | Red "Payment not confirmed after Save" rows that had really posted | ClaimDesk took longer to confirm than the bot waited (10 s) | The wait is now 20 s, but a slow ClaimDesk can still cause it. **Always check in ClaimDesk first** (E12). | Partly |
| Before 1.4.2 | Clinics with a comma in the cell were never posted | The bot cuts names at every comma or semicolon | One clinic per row. Clinics whose real name has a comma must be posted by hand (E07). | Partly |
| Before 1.4.2 | The bot worked inside a SQL tool whose title contained "ClaimDesk", then closed the real ClaimDesk | The bot takes the first window with "ClaimDesk" in its title | Close every other "ClaimDesk" window before a run (section 4, E18). The code still matches this way. | Partly |
| Earlier build (log) | Run stopped partway with no message on screen | Watchdog: 5 minutes with no new row | E15 | Partly |
| Earlier build (log) | A clinic with `&` in its name was retried and left without rows | The clinic-name check failed on the special character | E08 | Partly |

## 10. Releases and version check

- **How an update arrives:** through the ClaimDesk Poster launcher. **The launcher keeps the old version until it is closed and reopened.**
- **How to confirm it applied:** the ClaimDesk Poster title bar shows the version. Today that is 1.4.2.
- **If the version did not change:** close ClaimDesk Poster completely and reopen it, then check the title bar again. If it is still old, raise an RPA Support ticket with the version shown and the machine name.
- Every machine that runs the bot should show the same version.

## 11. Escalating to dev

Raise a ticket in the **RPA Support** queue.

**Send:**
- the exception ID from section 7;
- the date and time of the run (to the minute) and the machine name;
- the clinic name and check number(s) from the Report screen;
- the version from the title bar;
- a screenshot of the Report screen, and of ClaimDesk if it is open.

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

## 12. Failure-class check

- F1 (missing prerequisite) covered in section 3, E06, and Fix 10, 16.
- F2 (wrong window / focus) covered in section 4, E18, and Fix 3, 4.
- F3 (target app slower or different) covered in E05, E08, E09, E11, E12, section 8, and the section 3 "unlocked, screen on" rule.
- F4 (input read differently) covered in section 3 input rules, E07, E08, E14, and Fix 5, 13.
- F5 (done when nothing done) covered in E15 and Fix 7. A clinic is marked finished even with 0 remittances, and that looks the same as a failed clinic on screen.
- F6 (action happened but not confirmed) covered in E12 and Fix 2.
- F7 (business exception shown as success) covered in section 6, E10, E13, and Fix 1.
- F8 (endless re-runs / watchdog) covered in section 8 and E15. Retries are capped at 3, so there is no endless loop. Fix 11.
- F9 (stopping the wrong way) covered in section 4 and Fix 15.
- F10 (one stuck item blocks the queue) covered in E01, E16, E17, and Fix 9, 12.
- F11 (cause hidden from ops) covered in section 5 and Fix 7, 8, 9, 10.
- F12 (update didn't arrive) covered in section 10, incident 1, and Fix 15, 17.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | "Rejected by app" (Remittance Errors, not posted) and "Skipped" (not ACH) are stored as Completed, so they show green | Ops thinks unposted payments are done | `bot.py:29-30` STATUS_MAP |
| 2 | A Save confirmation timeout is recorded as Error. There is no read-back in the grid to check whether the payment really posted. | Real posts show red; re-posting by hand risks double payment; the red row blocks the batch | `bot.py:117-118` |
| 3 | The window match is still a plain "title contains ClaimDesk", even though commit 6c4ca09 says it was fixed. It can grab the "ClaimDesk Poster" launcher, the "ClaimDesk Login" window or a SQL tool. | The bot drives the wrong window | `bot.py:66-70` |
| 4 | `taskkill /im ClaimDesk.exe /f` kills every ClaimDesk process on the machine | A user's own ClaimDesk session is closed | `bot.py:146` |
| 5 | Clinic cells are split on commas and semicolons. README:8 wrongly says such names are "split and skipped": they are actually retried 3 times, then left Pending. | Clinics with a comma in their name can never be posted; the batch is blocked | `bot.py:62`, `README.md:8` |
| 6 | The wrong-clinic check runs immediately after the click, with no wait, as a substring match. Its message says "leaving Pending" but the clinic is retried. | False failures on `&` names; a misleading message | `bot.py:91-92` |
| 7 | A clinic left Pending writes no Report row. Clinic and batch status are not on any screen. | Ops can't see failed clinics without the log | `bot.py:147`, `report_screen.py:6` |
| 8 | The raw status and tech_comments columns are stored but not shown on the Report screen | The developer-level cause is hidden from ops | `report_screen.py:6` |
| 9 | The "A Pending batch exists" refusal goes to stderr only, and there is no clear or resume tool for ops | The upload silently does nothing; only dev can unblock it | `bot.py:167-168` |
| 10 | Input errors (missing sheets, missing login) are raised before or without logging, and never reach a screen. A missing CLAIMDESK_EXE surfaces only as a clinic error in the log. | Ops sees "nothing happened" | `bot.py:52-63`, `bot.py:74`, `bot.py:169` |
| 11 | The watchdog heartbeat happens only per remittance row, so sign-in, clinic open and retries don't count. A clinic failing 3 times, or one with 0 rows, can exceed 300 s. Exiting with os._exit skips cleanup: ClaimDesk is left open and the batch stays Pending. | Whole runs die partway | `bot.py:39-49`, `bot.py:137` |
| 12 | A clinic retry re-inserts report rows without removing the first attempt's rows | Duplicate rows; a stale red row blocks the batch forever | `bot.py:130-139` |
| 13 | The cutoff is compared as text (`check_date > str(cutoff)`) | Wrong defer/post decisions when date formats differ | `bot.py:107` |
| 14 | The Remittance Errors popup is only waited for 5 s | A late popup is clicked past, and the row may end up as "Save button not found" | `bot.py:110` |
| 15 | The launcher and updater code are not in this repo. There is no Stop button, and it's unknown whether closing the launcher stops the bot. The 1.3.0 update fix has no code here. | Ops has no safe way to stop a run; the update behaviour can't be verified | `report_screen.py:14`, `bot.py:3` |
| 16 | The ClaimDesk user name and password are kept in plain text in the input Excel | Credentials get passed around with the input file | `bot.py:56` |
| 17 | The version is shown in the title bar only. It is not written to the run log. | The run that produced a log can't be matched to a build | `report_screen.py:8`, `bot.py:164` |
| 18 | The existing run log contains a patient name. It was written by an older build, but the log folder should be treated as PHI. | PHI exposure if logs are shared | `logs/run_20260901_101500.log:3` |
| 19 | Remittance outcomes are not written to the run log at all. The bot writes no output file, although ops' access was planned around an output folder. | Ops has no output to check outside the Report screen | `bot.py:136-139` |
| 20 | Sign-in success is never checked. With a wrong password, the window search returns the Login window, and every clinic fails as "not found in list". | Credential problems are misreported | `bot.py:80-83` |