# ClaimDesk Poster - ops handover

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

> This document was written by reading the bot's code and history. The bot was not run to produce it.

## 1. What the bot does

ClaimDesk Poster posts insurance remittance payments into the **ClaimDesk** desktop app, one clinic at a time. Ops start it from the **ClaimDesk Poster** launcher window, which hands it the input Excel. The Excel has three sheets: **Login** (the ClaimDesk username and password), **Clinics** (the clinics to work) and **Settings** (the check-date cutoff). For each clinic the bot signs in to ClaimDesk, opens the clinic and goes down the remittance list. It posts and saves every ACH payment dated on or before the cutoff. It skips other payment methods and defers later dates. Each remittance it handles becomes one row on the **Report screen** of the launcher. The bot produces no Excel, PDF or email output. The Report screen is the only result ops can see.

## 2. How it works

```
ClaimDesk Poster launcher (the window you use; title bar shows the version)
   └─ starts → Posting bot (runs in the background, no window of its own)
                   │
                   ├──drives──> ClaimDesk desktop app
                   │            (opened, signed in and force-closed by the bot
                   │             for every clinic - do not touch while it runs)
                   │
                   ├─ writes → bot database ──read by──> Report screen (in the launcher)
                   └─ writes → run log (developers only)
```

- **Launcher:** where ops start a run and open the Report screen. Its title bar shows the version.
- **Posting bot:** does the work. It has no window and no Stop button.
- **ClaimDesk:** the app the bot drives with the real mouse and keyboard. The bot opens it fresh for every clinic and force-closes it afterwards.
- **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, which only developers can open.

**One run, step by step:**
1. The bot refuses to start if the previous batch was never completed (see E08).
2. It reads the Excel and creates a new batch. Every clinic starts as Pending.
3. For each clinic, it opens ClaimDesk, signs in and clicks the clinic in the clinic list.
4. It waits for the remittance list, then handles each line. The result is one of: posted, skipped (not ACH), deferred (after the cutoff), rejected by ClaimDesk, or error. A row appears on the Report screen.
5. It force-closes ClaimDesk and moves on to the next clinic.
6. The batch becomes Completed only if every clinic finished and **no row is red**. Otherwise it stays Pending.

## 3. Before a run

- [ ] Nobody needs ClaimDesk on this machine during the run. The bot force-closes **every** ClaimDesk window on the machine after each clinic, including one a person has open.
- [ ] No other window has "ClaimDesk" in its title. That includes database or SQL tools, browser tabs and file explorer windows. The bot picks the first window it finds with "ClaimDesk" in its title.
- [ ] The machine stays unlocked, with the screen on, for the whole run. If the session is locked, minimised or disconnected, the bot's clicks have nowhere to land.
- [ ] **The previous batch is finished.** If any row from the last run is red, or a clinic did not finish, the new run is refused (E08). Clear that first through a ticket.
- [ ] **Login sheet:** username in A2 and password in B2, both filled in and correct. The bot does **not** detect a wrong password (E07). Each wrong attempt is a failed ClaimDesk login, and there can be 3 per clinic.
- [ ] **Clinics sheet:** **one clinic per row** in column A, starting at row 2. Never use commas or semicolons, because the bot splits on them.
  - Bad: `Clinic A, Clinic B` in one cell.
  - Bad: `Clinic C, Branch 2`. The bot reads this as two clinics, and neither exists.
  - Good: `Clinic A` in A2 and `Clinic B` in A3.
- [ ] **Clinic spelling:** exactly as the clinic link reads in ClaimDesk, including `&`, capitals and spaces. No empty cells between clinics. Don't list a clinic twice, because the bot does not remove duplicates and will run it twice.
- [ ] **A clinic whose real name contains a comma cannot be run by this version.** Post it by hand and raise a ticket.
- [ ] **Settings sheet:** the cutoff date is in B1. The bot compares the cutoff as text, not as a date, so Deferred decisions near the cutoff can be wrong. Until dev fixes this, spot-check the first run after changing the cutoff (see E05).
- [ ] The launcher title bar shows version **1.4.2** (see section 10).

## 4. During a run

- **Hands off the machine.** The bot clicks with the real mouse. A click or keypress from a person can land anywhere, including on a payment screen.
- Don't open ClaimDesk, or any window with "ClaimDesk" in its title, on this machine.
- **To stop the bot:** this version has no Stop button.
  - Closing ClaimDesk does **not** stop it. The bot treats that as a failed clinic and opens ClaimDesk again, up to 3 times per clinic.
  - The code does not show whether closing the launcher stops the bot. After closing the launcher, watch for about 2 minutes. If ClaimDesk opens again, the bot is still running: raise a ticket.
  - Any stop in the middle of a run leaves the batch Pending, and the next run will be refused (E08).
- **What normal progress looks like:** ClaimDesk opens, signs in, works through one clinic and closes. Then it opens again for the next clinic, and new rows appear on the Report screen.
- **When it looks stuck:**
  - The bot kills itself after **5 minutes with no remittance handled** (E09). Wait at least 5 minutes before acting.
  - After that, **ClaimDesk still open and not moving** means the run died: raise a ticket.
  - **ClaimDesk closed and no longer reopening** means the run ended, whether it finished or failed.

## 5. Where to look when something goes wrong

Ops can open the launcher and its Report screen. The bot writes no output files, and the database and run logs are developer-only.

| Question | Where to look |
|---|---|
| Did the run finish? | Not shown on any screen ops can open (fix item 4). **Sign it has ended:** ClaimDesk has closed and does not reopen within 2 minutes. **Sign it ended badly:** ClaimDesk is left open, or the next run is refused (E08). |
| Which remittances failed? | Report screen → choose the batch → rows with File Status **Error** (red). |
| Which remittances were **not posted** although green? | Report screen → green rows whose Comments say **"Remittance Errors on posting"** (E03) or **"... - not posted"** (E04). |
| Why did one remittance fail? | Report screen → Comments column. Then use the exception catalogue (section 7). |
| Which clinic failed completely? | A failed clinic has **no rows at all** on the Report screen (E06). Compare the Report screen against your Clinics sheet. A clinic with no rows either had nothing to post or failed. Check ClaimDesk: unposted ACH remittances still listed for it means it failed. |
| Did the bot already retry? | Not visible to ops. A clinic is always tried 3 times before it is given up. Single remittances are never retried. |
| Which version is running? | The launcher title bar. |

## 6. Statuses

The Report screen shows **File Status** (with a colour) and **Comments**. Three different results all show as green Completed, so **always read the Comments column**.

| Status (File Status - Comments) | Colour | Meaning | What ops does |
|---|---|---|---|
| Completed - "Posted successfully" | green | Payment posted and ClaimDesk showed "Payment saved". | nothing |
| Completed - "Payment method '<method>' - not posted" | green | **Not posted on purpose.** Only ACH payments are posted. | nothing, unless the client wants that method posted by hand |
| Completed - "Remittance Errors on posting" | green | **Not posted. Needs follow-up.** ClaimDesk showed its Remittance Errors screen and the bot cancelled. | Review and post it by hand in ClaimDesk (E03) |
| Deferred - "Check date <date> is after the cutoff - deferred" | grey | Not posted. The check date is after the Settings cutoff. | nothing; a later run picks it up (see E05 for the caveat) |
| Error - "Save button not found" | red | The payment screen opened but had no Save button. Nothing was saved. | E02 |
| Error - "Payment not confirmed after Save" | red | The bot clicked Save but saw no "Payment saved" within 20 s. **It may really have posted.** | E01: check in ClaimDesk **before** anything else |
| Pending | amber | The screen supports this colour, but this version never writes it on a row. | If you see it, raise a ticket |
| Clinic Pending / Success | not shown | Kept per clinic in the database only. Pending means the clinic failed all 3 attempts or never ran. | See E06 |
| Batch Pending / Completed | not shown | Kept per batch in the database only. Pending means a red row or a failed clinic remains. A Pending batch blocks the next run. | See E08 |

## 7. Exception catalogue

Quote the ID (E01, E02, ...) in your ticket.

| ID | What you see | How the bot identifies it | Where it is recorded | Type | Who acts | What to do | Escalate when |
|---|---|---|---|---|---|---|---|
| E01 | Red row, Error - "Payment not confirmed after Save" | After clicking Save it waits 20 s for ClaimDesk's "Payment saved" message. If the message never appears, it writes Error and moves to the next remittance. It does not check again. | Report screen, Comments | System | **Ops, then Dev** | 1. **Check in ClaimDesk whether the payment posted.** 2. Do **not** post it again until you know. Re-posting can create a double payment. 3. If it did not post, post it by hand. 4. Ops cannot change the row, and this red row blocks the next run (E08). | Always. Raise a ticket so dev corrects the row. Send the batch ID, clinic, check number, and whether it posted in ClaimDesk. |
| E02 | Red row, Error - "Save button not found" | It waits 10 s for the Save button on the payment screen. If the button is missing, it writes Error and goes to the next remittance, leaving that screen open. | Report screen, Comments | System | **Ops, then Dev** | 1. In ClaimDesk, check that this remittance was not posted. 2. Check the **next few rows** of the same clinic as well. The bot carried on from the screen it left open, so they may be wrong. 3. Post by hand as needed. | Always. Send the batch ID, clinic, check numbers and time. |
| E03 | Green row, Completed - "Remittance Errors on posting" | ClaimDesk showed its "Remittance Errors" screen within 5 s of Post Payment. The bot clicked Cancel and moved on. | Report screen, Comments (the row is green, but nothing was posted) | Business | **Ops** | Open the remittance in ClaimDesk, review the errors and post it by hand, or follow the client's process. | The same remittance keeps coming back as rejected after it has been corrected. |
| E04 | Green row, Completed - "Payment method '<method>' - not posted" | The payment method in the remittance list is not ACH. | Report screen, Comments | Business | Bot | Nothing. The bot posts only ACH. Post it by hand if the client wants non-ACH posted. | ACH payments show up here. |
| E05 | Grey row, Deferred - "Check date ... is after the cutoff - deferred" | The check date text is compared with the cutoff in Settings B1 **as text, not as a date**. | Report screen, Comments | Business | Bot, then Ops | Nothing normally. A later run picks it up. After changing the cutoff, spot-check a few rows: a date before the cutoff should be posted, not Deferred, and a later date should not be posted. | Rows are deferred or posted on the wrong side of the cutoff. Send the batch ID, the cutoff value and two example rows. |
| E06 | A clinic has **no rows** on the Report screen, and ClaimDesk still lists unposted ACH remittances for it | The bot tried the clinic 3 times and every attempt failed at one of: ClaimDesk login window not shown within 60 s; clinic link not found within 10 s; a different clinic opened; remittance list not loaded within 60 s; ClaimDesk window not found. After 3 failures it skips the clinic and goes on to the next. | **Not on any ops screen.** The clinic stays Pending in the database, and the reason is in the run log. | Business (spelling) or System (ClaimDesk slow or down) | **Ops, then Dev** | 1. Check the clinic's spelling in the Clinics sheet against the link in ClaimDesk, including `&`. 2. Check for commas or semicolons (section 3). 3. If the spelling was wrong, fix it. The batch still needs clearing (E08). | The spelling is exact, or the clinic name contains a comma. Send the batch ID, clinic name and run start time. |
| E07 | ClaimDesk opens and closes again and again, but **no clinic gets any rows** | Not identified. The bot does not check whether sign-in worked. A wrong password shows up as "clinic not found" for every clinic, 3 attempts each. The same pattern appears if the bot's ClaimDesk path setting is missing on this machine. | Not on any ops screen; run log only | Business (password) or System (setup) | **Ops, then Dev** | 1. Stop the run (section 4). 2. Check the username and password in Login A2/B2 by signing in to ClaimDesk by hand. 3. Watch for an account lockout. | The login works by hand. Send the batch ID, run time and machine name. |
| E08 | A new run is refused, or does nothing. The bot's message is "A Pending batch exists - finish or clear it before a new upload" (where it shows depends on the launcher). | At start, the bot refuses if **any** earlier batch is still Pending. A batch stays Pending if it has any red row (E01, E02), a failed clinic (E06), or a run that was stopped or killed (E09). | Not on any ops screen; batch status is in the database only | System | **Dev** | Find the blocking items on the Report screen of the last batch: red rows and missing clinics. Sort out each one in ClaimDesk (E01, E02, E06), then raise a ticket to clear the batch. Ops have no button to clear it. | Always. Send the last batch ID and the list of red rows and missing clinics. |
| E09 | The run stops halfway. ClaimDesk is left **open and idle**, and later clinics have no rows. | The bot has a 5-minute no-progress limit, and the clock resets only when a remittance is handled. Slow sign-ins, clinics with nothing to post, and a clinic failing 3 times all count against it. When the limit passes, the bot kills itself at once, without closing ClaimDesk or finishing the batch. | Not on any ops screen; run log only | System | Bot, then **Dev** | 1. Close ClaimDesk. 2. On the Report screen, note the last clinic and check number that has a row. 3. In ClaimDesk, check that this remittance and the next one are not half-posted. 4. The batch is now Pending (E08). | Always. Send the batch ID, the time ClaimDesk stopped moving, and the last row shown. |
| E10 | Nothing happens after starting a run: ClaimDesk never opens and no batch appears | The Excel failed the bot's start checks: the Login sheet is missing, Login A2 or B2 is empty, or the Clinics or Settings sheet is missing. | Not on any ops screen and not in the run log. The launcher may show the message. | Business | **Ops** | Check that the Excel has the three sheets **Login**, **Clinics** and **Settings** with exactly those names, and that Login A2 and B2 are filled in. Start again. | The Excel is correct and the bot still does nothing. Send the time and a screenshot of the launcher. |
| E11 | A ClaimDesk window that a person had open on the bot machine suddenly closes | After every clinic the bot force-closes **all** ClaimDesk windows on the machine. | Nowhere | System | Ops | Don't use ClaimDesk on the bot machine during a run. Re-check any work that was open in ClaimDesk when it closed. | - |
| E12 | The bot types into or clicks in the wrong window (a database tool, a browser, the launcher), or ClaimDesk closes as soon as it opens | The bot attaches to the first window whose title contains "ClaimDesk". | Not on any ops screen; often appears as E06 | System | Ops, then **Dev** | Stop the run (section 4). Close every other window with "ClaimDesk" in its title, then check the batch (E08). | It happens with no other "ClaimDesk" window open. Send the time and a screenshot. |
| E13 | The same check number appears twice in one batch on the Report screen | When a clinic is retried, the bot goes through the list again and writes new rows for items it already skipped or deferred. | Report screen | System | Ops | Duplicate **Skipped** or **Deferred** rows are harmless. | The same check shows "Posted successfully" twice. Check ClaimDesk for a double payment and send the batch ID and check number. |

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| A clinic fails at any step: ClaimDesk won't start or sign in, the clinic is not found, the wrong clinic opens, the list won't load, or ClaimDesk is closed | Force-closes ClaimDesk, signs in again from scratch and retries the whole clinic | 3 attempts per clinic. Each attempt can take up to about 2.5 minutes of waiting (60 s sign-in + 10 s clinic + 60 s list). | Clinic skipped with no rows (E06), next clinic. The batch will stay Pending. |
| "Remittance Errors" screen | Clicks Cancel and moves on | 1 (no retry) | Green row "Remittance Errors on posting" (E03) |
| Save button missing / save not confirmed | Nothing. No retry. | - | Red row (E02, E01), next remittance |
| No progress at all | Kills the whole run | 5 minutes with no remittance handled, checked every 10 s. Can trigger during the clinic retries above. | Run ends with ClaimDesk open and the batch Pending (E09) |
| Run stopped or killed halfway | **No resume.** The next run will not continue where it left off. | - | The batch must be cleared by dev (E08) |

**How long to wait:** Act after **5 minutes** with no new row on the Report screen and ClaimDesk sitting still. Before that, the bot may still be retrying.

## 9. Known incidents

Dates are unknown for the four code-history items (they all came in one import). They are listed newest first by history order.

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| 1.3.0 → 1.4.x | Users still on 1.3.0 after an update | The launcher kept the old program folder until the machine was restarted | After an update, restart the machine and check the title bar (section 10) | Yes |
| before 1.4.2 (also in the 2026-09-01 run) | Red "Payment not confirmed after Save" rows that had really posted | ClaimDesk took longer than 10 s to show "Payment saved" | The wait was raised to 20 s, but it is still a fixed wait, so this can recur on a slow day. Always check in ClaimDesk first (E01). | Partly |
| before 1.4.2 | Clinics with a comma in the name were never processed | The bot splits clinic cells on commas and semicolons | One clinic per row. A real comma in a clinic name still can't be handled (section 3). | Partly |
| before 1.4.2 | The bot drove a SQL browser window, then closed the real ClaimDesk | Window match on "ClaimDesk" in the title | Close every other "ClaimDesk" window before a run. **Still open in the code** (E12). | Partly |
| 2026-09-01 | "Wrong clinic opened" for a clinic with `&` in its name. The bot retried, then the whole run was killed after 5 minutes without progress. The last clinic never ran. | The clinic check did not match a name with `&`, and the no-progress limit does not count sign-in and clinic retries as progress. | Not fixed. The batch stays Pending (E08, E09). Spell `&` names exactly as ClaimDesk shows them, and raise a ticket if it repeats. | Partly |

## 10. Releases and version check

- **How an update arrives:** through the launcher. Its update code is not part of this repository.
- **How to confirm it applied:** the launcher title bar shows the new version. This document is for **1.4.2**.
- **If the version did not change:** restart the machine, open the launcher and check again. If it still shows the old version, raise a ticket with the machine name and the version shown.
- Each machine keeps its own bot database. Batches and the Report screen are per machine, so check results on the machine that ran the batch.

## 11. Escalating to dev

Raise a ticket in the **RPA Support** queue. Include:
- the exception ID from section 7 (for example E01)
- the batch ID (as chosen on the Report screen)
- the clinic name and check number(s)
- the time of the failure and the machine name
- a screenshot of the Report screen
- for E01, E02 and E09: what you found in ClaimDesk (posted or not)

Dev will read the run log and the database themselves.

**Never send:** passwords (including the Login sheet), the bot's settings file, or patient or payment details in chat. Refer to rows by batch ID, clinic and check number only.

## 12. Failure-class check

- **F1** Missing prerequisite: covered in section 3 (Excel sheets, Login cells, version), E07 (ClaimDesk path setting missing), E10 (missing sheets), fix items 14 and 18.
- **F2** Wrong window / focus: covered in sections 3 and 4, E11, E12, fix items 7 and 8.
- **F3** Target app slower or different: covered in E01, E02, E06, section 8 (every wait and limit), section 3 (keep the session unlocked), fix items 11 and 12.
- **F4** Input read differently: covered in section 3 (commas, `&`, duplicates, cutoff as text), E05, E06, fix items 9 and 10.
- **F5** Marked done when nothing was done: covered in fix items 15 and 20 (a clinic is marked Success with no positive check; a crash after Save leaves no row).
- **F6** Action happened but not confirmed: covered in E01 (check in ClaimDesk first; dev corrects the row), fix item 11.
- **F7** Business exception shown as success: covered in section 6 ("Remittance Errors on posting" and "not posted" are green), E03, E04, fix item 1.
- **F8** Endless re-runs / watchdog: no endless loop (3 attempts per clinic). The watchdog kill is covered in section 8, E09 and fix item 6.
- **F9** Stopping the wrong way: covered in section 4 (closing ClaimDesk does not stop it), fix item 19.
- **F10** One stuck item blocks the queue: covered in E08 (any red row or failed clinic blocks all later runs), fix item 5.
- **F11** Cause hidden from ops: covered in section 5, fix items 2, 3, 4 and 14.
- **F12** Update didn't arrive / old build undoes new: covered in section 10 and fix item 17. Nothing is written to shared resources on start, because each machine has its own database.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | "Rejected by app" (ClaimDesk rejected the remittance, nothing posted) and "Skipped" are stored as Completed (green) | Ops read green as done; rejected remittances get no follow-up | `bot.py:27-33` STATUS_MAP |
| 2 | Report screen hides the `status` and `tech_comments` columns | Rejected, skipped and posted rows look identical apart from the comment; the technical cause is invisible | `report_screen.py:6` |
| 3 | A clinic that fails all 3 attempts writes no report row, only a log line | Ops can't see failed clinics; they look the same as clinics with nothing to post | `bot.py:143-147` |
| 4 | Batch status and clinic status are not shown anywhere ops can open | Ops can't tell whether a run finished, or why the next run is refused | `bot.py:170,178`; `report_screen.py:11-13` |
| 5 | Any red row or Pending clinic keeps the batch Pending, and a Pending batch refuses every later run. There is no clear/edit function; the only fix is a manual DB edit. | One unconfirmed save stops all posting until dev intervenes | `bot.py:150-154`, `bot.py:167-168` |
| 6 | The watchdog clock resets only per item (and starts at import), so sign-in, clinic retries and zero-item clinics count as "no progress". `os._exit` skips cleanup, leaving ClaimDesk open and the batch Pending. | Whole runs are killed by one slow clinic; later clinics never run | `bot.py:36`, `bot.py:44-49`, `bot.py:137` |
| 7 | Window match is a title substring. It also matches the launcher "ClaimDesk Poster", the "ClaimDesk Login" window and SQL tools. The 8fa51ac fix is only a comment; the code is unchanged. | The bot can drive the wrong window | `bot.py:66-70`, `bot.py:185` |
| 8 | `taskkill /im ClaimDesk.exe /f` after every clinic kills every ClaimDesk on the machine | Users lose open work | `bot.py:146` |
| 9 | Clinic cells are split on `,` and `;`. There is no duplicate check, and empty names come from trailing commas. | Clinics with a comma in their name can never run; duplicates run twice | `bot.py:60-62` |
| 10 | The cutoff is compared as text (`str(cutoff)` vs the grid text) | Deferred/posted decisions near the cutoff can be wrong | `bot.py:107` |
| 11 | "Payment not confirmed" is a fixed 20 s wait with no re-check of the grid or payment afterwards | False red rows that really posted; risk of double-posting on manual re-post | `bot.py:117-118` |
| 12 | "Post Payment" is clicked without selecting the grid row. After Rejected/Error the screen is not reset before the next item, and the grid is read by column position, which a header row breaks. | A row's check number may not match what was actually posted; items after an error act on a stale screen | `bot.py:95-119` |
| 13 | A failed sign-in is not detected. It surfaces as "Clinic not found", with 3 sign-ins per clinic. | Wrong password causes many failed logins and a possible account lockout | `bot.py:73-83` |
| 14 | Start-up errors are not logged: missing sheets, an empty Login, and "A Pending batch exists". A missing `CLAIMDESK_EXE` becomes a per-clinic error. | Ops see "nothing happened" with no message on file | `bot.py:52-63`, `bot.py:74`, `bot.py:167-168` |
| 15 | The report row is written only after the post completes, so a crash or watchdog kill between Save and the write leaves no record | A payment can be posted with no trace on the Report screen | `bot.py:116-139` |
| 16 | A clinic retry re-writes rows for items already handled in the failed attempt | Duplicate rows on the Report screen | `bot.py:136-139` |
| 17 | The sample run log contains lines this code cannot write, including **patient names**, so the deployed build is not this repo's code. The bot also writes a `BOT_WAS_RUN` marker file into the program folder. | This doc may not match what is running; old logs hold PHI and must be handled as such. **That log is committed to git**, so the PHI is in the repo history. | `logs/run_20260901_101500.log`; `bot.py:161` |
| 18 | `.env` holds an unused plaintext password entry and an unused alert setting next to the code | Credential exposure: **`.env` is committed to git**, so the password is in the repo history and should be rotated. There is no alerting despite the setting. | `.env` (key names only; values not copied) |
| 19 | Launcher code (start, stop, update) is not in this repo. There is no Stop button, and it is unknown whether closing the launcher stops the bot. | Ops have no safe way to stop a run | `bot.py:3` (only reference) |
| 20 | The "right clinic" check is the clinic name as a substring of the window title (fails on `&`/encoding). A clinic is marked Success with no check that the list really loaded its items. | Correct clinics are retried and abandoned; an empty or half-loaded list is marked Success | `bot.py:91`, `bot.py:96-101`, `bot.py:140` |