# 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

The bot posts remittance (insurance) payments into the **ClaimDesk** desktop app one clinic at a time. Each run starts from the **ClaimDesk Poster** launcher window and works from one input Excel file, which has three sheets:
- **Login:** the ClaimDesk username and password
- **Clinics:** the clinic names
- **Settings:** the cutoff date

For every clinic, the bot does five things:
1. signs in to ClaimDesk;
2. opens that clinic;
3. reads the list of unposted payments;
4. posts every ACH payment dated on or before the cutoff;
5. writes one row per payment to the launcher's **Report screen**.

It writes no output file. The Report screen is the only result ops can see. It drives one app, **ClaimDesk**, and you must not touch ClaimDesk while the bot is running.

## 2. How it works

```
ClaimDesk Poster launcher (the window you use; title bar shows the version)
   └─ starts → Bot process ──drives──> ClaimDesk desktop app
                   │                   (do not touch while it runs)
                   ├─ writes → the bot's database (one row per payment, plus batch and clinic status)
                   │              └─ read by → Report screen in the launcher
                   └─ writes → a run log in the bot's logs folder (dev only; ops has no access)
```

- **The launcher** is where you start a run and read the Report screen.
- **The bot process** does the work. It has no window of its own.
- **ClaimDesk** is the app the bot clicks through. The bot opens it and closes it again for every clinic.
- **The database** stores every result. Ops sees part of it on the Report screen; the rest is only available to dev.
- **The run log** records clinic-level failures and restarts. Only dev can read it.

**One run, step by step:**
1. **Refuse to start** if an earlier batch is still Pending (E01).
2. **Read the input Excel.** One batch is created, and every clinic in it starts as Pending.
3. **Process each clinic in order.** For each one the bot:
   1. starts ClaimDesk and signs in;
   2. opens the clinic;
   3. waits for the payments list.
4. **Handle each payment in the list:**
   - not ACH → skipped;
   - dated after the cutoff → deferred;
   - otherwise → the bot clicks Post Payment, then Save, then waits for "Payment saved".
5. **Close ClaimDesk** and mark the clinic done. If any step in 3 or 4 failed, the clinic is tried again, up to 3 times in total.
6. **Mark the batch Completed** only when there are no red rows and no clinic left undone. Otherwise the batch stays **Pending**, and that blocks the next upload (E01).

## 3. Before a run

- [ ] **The previous batch is Completed.** If it is still Pending, the new run will not start (E01) and dev must clear it first.
- [ ] **No other ClaimDesk is open on this machine**, not even one you opened yourself. The bot force-closes every ClaimDesk window after each clinic, so any work open in it will be lost.
- [ ] **No other window has "ClaimDesk" in its title.** That includes a SQL or database browser, a file explorer, or an email with that title. The bot may grab that window by mistake (E17).
- [ ] **The input Excel has the sheets Login, Clinics and Settings**, spelled exactly like that (E02).
- [ ] **Login sheet:** the username is in cell A2 and the password in B2. Before the run, check that they still work by logging in to ClaimDesk by hand. The bot cannot detect a wrong password (E05).
- [ ] **Clinics sheet: one clinic per row** in column A, starting at row 2. Spell each name exactly as ClaimDesk shows it.
  - **Bad:** `North Clinic, South Clinic` in one cell.
  - **Good:** `North Clinic` in A2 and `South Clinic` in A3.
  - **Never use a comma or a semicolon in a cell.** The bot cuts the name at that point, so a clinic whose real name contains a comma cannot be processed at all. Post those clinics by hand (E07).
  - A clinic with **"&"** in its name may fail as "wrong clinic" (E08). Watch these clinics on the Report screen.
- [ ] **Settings sheet:** put the cutoff date in cell B1. Payments dated after it are deferred. See E12 for a caution about date formats.
- [ ] **The launcher title bar shows version 1.4.2** (see section 10).

## 4. During a run

- **Don't use the mouse or keyboard on this machine.** Don't lock the screen and don't minimise ClaimDesk either. The bot clicks on screen; if another window comes to the front, its clicks land in the wrong place (E18).
- **Don't open ClaimDesk** or any window with "ClaimDesk" in its title.
- **To stop the bot:** the bot has no Stop button.
  - **Closing ClaimDesk does not stop it.** The bot treats that as a failure and opens ClaimDesk again, up to 3 times per clinic.
  - Ask dev before stopping a run. Any stop leaves the batch **Pending**, and dev then has to clear it before the next upload (E01).
- **When a run looks stuck:** the Report screen gets no new rows for 5 minutes and ClaimDesk sits idle.
  - The bot ends the whole run by itself after **5 minutes with no new payment row** (E16). Wait until then.
  - That stop is a kill, not a recovery. The batch stays Pending and dev must step in.

## 5. Where to look when something goes wrong

Ops can open only the launcher's screens. This version writes **no output file** and nothing to the output folder.

| Question | Where to look |
|---|---|
| Did the run finish? | The Report screen gets no more new rows and ClaimDesk is closed. The batch status (Pending or Completed) is **not shown to ops**, so if in doubt, raise a ticket. |
| Which payments failed? | **Report screen** for the batch. Look at the File Status column: red **Error** rows. |
| Which payments were *not* posted although green? | Report screen, green **Completed** rows. Read the Comments column: anything other than "Posted successfully" was **not** posted (E11, E13). |
| Why did one payment fail? | Report screen, **Comments** column. See section 6 and the catalogue. |
| A clinic from the input has **no rows at all** | Ops cannot see why. Possible causes: <br>- the clinic failed 3 times (E03-E10); <br>- the run was killed before it got there (E16); <br>- the clinic had nothing to post. <br>Raise a ticket and give the clinic name. |
| Did the bot already retry? | Not visible to ops; only the run log shows it. Assume it already tried each failing clinic 3 times. |
| Which version is running? | The launcher title bar. |

## 6. Statuses

What the Report screen shows: the **File Status** colour and the **Comments** text.

| File Status - Comments | Colour | Meaning | What ops does |
|---|---|---|---|
| Completed - "Posted successfully" | green | Payment posted and saved in ClaimDesk | Nothing |
| Completed - "Remittance Errors on posting" | green | **Needs follow-up. NOT posted.** ClaimDesk showed its Remittance Errors screen and the bot pressed Cancel. | Review and post it in ClaimDesk by hand (E13) |
| Completed - "Payment method '<method>' - not posted" | green | **Not posted on purpose**, because the method is not ACH | Nothing, unless the client wants it posted (E11) |
| Deferred - "Check date <date> is after the cutoff - deferred" | grey | Not posted. Its date is after the cutoff in Settings B1. | A later run picks it up (E12) |
| Error - "Save button not found" | red | Not posted. The payment screen had no Save button. | E14 |
| Error - "Payment not confirmed after Save" | red | **Might have posted.** Save was clicked, but "Payment saved" did not appear within 20 s. | **Check in ClaimDesk first** (E15) |
| Pending | amber | Not written by this version. If you see it, something unexpected happened. | Raise a ticket |

Statuses the bot stores but **does not show** on the Report screen (dev can read them):

| Item | Values | Meaning |
|---|---|---|
| Payment (detail) | Posted, Rejected by app, Skipped, Deferred, Error | "Rejected by app" and "Skipped" both appear on screen as green Completed |
| Clinic | Pending, Success | Success = the bot got through the clinic's list, **even if some rows are red or there were no payments at all** |
| Batch | Pending, Completed | Pending blocks the next upload (E01) |
| Technical comment | (empty), "RemitErrors screen shown", "Save button missing on payment screen", "no confirm text within 20s" | Dev detail for E13, E14 and E15 |

## 7. Exception catalogue

When a run fails, check the Report screen first. The **What you see** column describes the screen or ClaimDesk. In **Where it is recorded**, "run log" means the record is for dev only.

| ID | What you see | How the bot identifies it | Where it is recorded | Type | Who acts | What to do | Escalate when |
|---|---|---|---|---|---|---|---|
| E01 | A new upload does nothing: no Report rows appear and ClaimDesk never opens | When it starts, the bot checks for an earlier batch still Pending and stops if it finds one. The message is "A Pending batch exists - finish or clear it before a new upload". | The bot's console output only. It is not in the log or on the Report screen. | System | Dev | Raise a ticket asking dev to clear the Pending batch. Ops cannot clear it. | Always. Send the date and start time of the previous run and the batch number shown in the launcher. |
| E02 | A new upload does nothing: no Report rows appear and ClaimDesk never opens | Before creating a batch, the bot reads the Excel and stops if any of these is missing: <br>- the Login, Clinics or Settings sheet; <br>- the username in Login A2; <br>- the password in Login B2. <br>Messages include "'Login' sheet not found" and "UserName/Password missing in Login sheet (row 2)". | The bot's console output only | Business | Ops | Check the three sheet names and Login A2/B2. Fix them and run again. No batch was created, so nothing is blocked. | The file looks right and it still does nothing. Send the input file **without the password**. |
| E03 | No clinic gets any Report rows, and ClaimDesk never opens | The setting that points to the ClaimDesk program is missing or wrong, so each clinic fails 3 times | Run log | System | Dev | Raise a ticket. Afterwards the batch is Pending (E01). | Always. Send the run start time. |
| E04 | ClaimDesk opens but stays on its start screen. The clinic has no Report rows. | The bot waits **60 s** for the "ClaimDesk Login" window; then the message is "Login window not found" | Run log | System | Bot, then Dev | Wait. The bot tries the clinic 3 times. | The clinic still has no rows after the run. Send the run start time and the clinic name. |
| E05 | Clinics have no Report rows. If you were watching, ClaimDesk showed a login error. | **Not detected.** A wrong or expired password shows up later as E06 or E07. | Run log, as E06 or E07 | Business | Ops | Log in to ClaimDesk by hand with the Login sheet details. If they fail, correct them. A dev must then clear the batch (E01). | The details work by hand but clinics still get no rows |
| E06 | The clinic has no Report rows | Right after signing in, the bot looks for a window whose title contains "ClaimDesk"; if none is found, the message is "ClaimDesk window not found" | Run log | System | Bot, then Dev | Wait for the 3 attempts | The clinic still has no rows after the run. Send the run start time and the clinic name. |
| E07 | The clinic has no Report rows | The bot waits **10 s** for the clinic name to appear as a link in ClaimDesk; then the message is "Clinic '<name>' not found in list". <br>Usual causes: <br>- a spelling mismatch; <br>- a comma in the name, which cut it in two; <br>- the clinic not being on this login; <br>- a wrong password (E05). | Run log | Business | Ops | Compare the spelling in the Excel with ClaimDesk, character for character. Make sure each clinic is on its own row with no comma or semicolon. A clinic whose real name contains a comma must be posted by hand. | The spelling matches exactly and it still fails. Send the clinic name and the run start time. |
| E08 | The clinic has no Report rows | After clicking the clinic link, the bot checks that the clinic name appears in ClaimDesk's title. If not, the message is "Wrong clinic opened, leaving Pending: <name>". Clinics with "&" in the name are suspected to fail here every time. | Run log | System | Dev | Post that clinic by hand for now | Always. Send the clinic name and the run start time. |
| E09 | The clinic has no Report rows | The bot waits **60 s** for the payments list; then the message is "Remittance grid did not load" | Run log | System | Bot, then Dev | Wait for the 3 attempts | It happens on 2 runs in a row. Send the clinic name and the run start time. |
| E10 | The clinic has no Report rows (or only some), and the batch stays Pending | The result of E03-E09 after 3 failed attempts on one clinic. The message is "Clinic '<name>' left Pending after 3 attempts". | Run log | System | Dev | Raise a ticket. Later clinics are still processed. | Always. Send the clinic name and the run start time. |
| E11 | Green Completed - "Payment method '<method>' - not posted" | The payment method in ClaimDesk's list is not exactly "ACH". The match is case-sensitive, so "Ach" is skipped too. | Report screen | Business | Ops | Nothing, unless this payment should have been posted. In that case post it by hand. | The method is ACH but it was still skipped. Send the clinic name and the check number. |
| E12 | Grey Deferred - "Check date <date> is after the cutoff - deferred" | The payment date is compared with Settings B1. The compare is done **as text**, not as a date, so different date formats can defer the wrong payments or post ones that should wait. | Report screen | Business | Ops | Check that the date really is after the cutoff. A later run picks it up. | A payment dated *before* the cutoff was deferred, or one dated after it was posted |
| E13 | Green Completed - "Remittance Errors on posting" | After Post Payment, ClaimDesk showed its "Remittance Errors" screen within 5 s. The bot pressed Cancel. **Nothing was posted.** | Report screen | Business | Ops | Open the payment in ClaimDesk, review the errors, and post it by hand or follow the client's process | Many rows in the same clinic show this |
| E14 | Red Error - "Save button not found" | On the payment screen the Save button did not appear within 10 s. There is no retry for this payment. | Report screen | System | Ops, then Dev | Check the payment in ClaimDesk. Post it by hand if needed. The batch now stays Pending (E01). | Always, so dev can clear the batch. Send the clinic name, the check number and the run start time. |
| E15 | Red Error - "Payment not confirmed after Save" | The bot clicked Save and waited **20 s** for "Payment saved". It did not see it, but **the payment may still have posted**. | Report screen | System | **Ops** | **Check this check number in ClaimDesk before doing anything else.** <br>- **If it posted:** do not post it again; raise a ticket so dev can correct the row. <br>- **If it did not post:** post it by hand, or let a later run pick it up. <br>Re-running without checking can post it twice. | Always, because the red row keeps the batch Pending (E01). Send the clinic name, the check number, the run start time, and whether it was posted in ClaimDesk. |
| E16 | No new Report rows for 5 minutes, then the bot stops. ClaimDesk is left open and idle, and later clinics have no rows. | No new payment row for **300 s**, so the bot kills the whole run. Signing in, opening a clinic and its retries do **not** count as progress, so a slow or failing clinic, or several clinics in a row with no payments, can trigger it. Message: "[WATCHDOG] no progress for 300s - killing run". | Run log (last line) | System | Dev | Close ClaimDesk. Raise a ticket. The batch is Pending, so the next upload is blocked (E01). | Always. Send the run start time and the last clinic with rows. |
| E17 | ClaimDesk suddenly closes while another "ClaimDesk" window stays open, or the bot clicks inside the wrong window | The bot uses the first window whose title *contains* "ClaimDesk". That can be: <br>- a database tool; <br>- the launcher itself ("ClaimDesk Poster"); <br>- the ClaimDesk login window. <br>After every clinic it force-closes **all** ClaimDesk windows. | Run log, usually as E06/E07 | System | Ops, then Dev | Before the next run, close every other window with "ClaimDesk" in its title (section 3) | It happens again with no other such window open. Send the run start time. |
| E18 | Clinics fail with no clear reason while someone was using the PC, or the screen was locked | Windows refused to bring ClaimDesk to the front, so the bot's clicks missed. The current code has no message of its own for this; older logs showed "could not bring window to foreground". | Run log | System | Ops | Keep hands off the machine and the screen unlocked (section 4). A dev must clear the batch (E01). | It happens with nobody using the machine |
| E19 | The same check number appears twice or more on the Report screen for one clinic | When a clinic is retried, the bot reads the clinic's list again and writes the Skipped, Deferred and Rejected rows a second time | Report screen | System | Ops | Count each check number once. A duplicate grey or green row is not a second payment. | A check number shows "Posted successfully" twice. Send the clinic name and the check number. |

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| Any clinic-level failure (E03-E09, E17, E18) | Force-closes ClaimDesk, starts it again, signs in and redoes the whole clinic | 3 attempts per clinic. Each attempt can take up to about 2 minutes: 60 s for login, 10 s for the clinic, 60 s for the list. | Clinic left Pending (E10), batch stays Pending, next clinic starts |
| Payment-level failure (E14, E15) | **No retry** | - | Red Error row, next payment |
| No progress | Kills the whole run (not a recovery) | 5 minutes without a new payment row | Run ends, ClaimDesk left open, batch Pending (E16) |
| A Pending batch from an earlier run | **Nothing.** There is no resume and no clear. | - | Every new upload is refused until dev clears it (E01) |

Rules of thumb:
- Wait at least **7 minutes** after the last new Report row before treating a run as dead.
- **Any red row, any clinic without rows, or any killed run means dev must clear the batch** before the next upload.

## 9. Known incidents

Newest first. The repo history does not give exact dates.

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| 1.3.0 → 1.4.x | After an update the title bar still showed 1.3.0 | The launcher kept running from the old folder until it was restarted | After every update, close the launcher completely, reopen it, and check the title bar (section 10) | Yes |
| Before 1.4.2 | Red "Payment not confirmed after Save" rows for payments that had really posted | ClaimDesk took longer than the wait to show "Payment saved" | The wait was raised from 10 s to 20 s. A slow save can still cause it, so **always check in ClaimDesk first** (E15). | Partly |
| Before 1.4.2 | Some clinics were never processed; "not found in list" | Clinic names with commas were cut into pieces | One clinic per row, with no commas or semicolons. A real name containing a comma still cannot be processed, so post it by hand (E07). | Partly |
| Before 1.4.2 | The bot drove a database tool and then closed the real ClaimDesk | That tool's title contained "ClaimDesk". **The code still matches window titles the same way**, so this can happen again. | Close every other "ClaimDesk" window before a run (E17) | Yes |
| 2026-09-01 run | Run stopped mid-way; batch Pending; the next upload was refused | The bot's 5-minute no-progress stop (E16) | Raise a ticket (E16, E01) | Partly |
| 2026-09-01 run | A clinic with "&" in the name failed as "wrong clinic" | Suspected "&" title mismatch (not confirmed) | Post it by hand (E08) | Partly |
| 2026-09-01 run | Clicks missed while the PC was in use or locked | Windows blocked the bot from bringing ClaimDesk to the front | Hands off, screen unlocked (E18) | Yes |

## 10. Releases and version check

- **How an update arrives:** through the ClaimDesk Poster launcher. The update code is not in this repo, so dev must confirm the exact steps.
- **How to confirm it applied:** **fully close the launcher and open it again.** The title bar must show the new version, currently **1.4.2**.
- **If the version did not change:** close the launcher again, check that no launcher window is left open, and reopen it. If it is still old, raise a ticket with the version shown and the machine name. Do not run the bot on an old version.

## 11. Escalating to dev

Raise a ticket in the **RPA Support** queue and include:
- the exception ID from section 7 (for example E15);
- the date and start time of the run, so dev can find the run log;
- the batch number, if the launcher shows it;
- the clinic name and the check number;
- a screenshot of the Report screen;
- for E15: whether the payment shows as posted in ClaimDesk.

Never send: passwords (including the Login sheet), the bot's settings file, or patient details in chat or in the ticket text.

## 12. Failure-class check

- **F1** (missing prerequisite): covered in E02, E03 and section 3. Missing database setup is in section 13, item 18.
- **F2** (wrong window or focus): covered in E17, E18, and the rules in sections 3 and 4. Also section 13, items 6 and 7.
- **F3** (target app slower than expected): covered in E04, E06-E09, E14 and section 8 (all timeouts). No screen-size rule is needed, because clicks are found by element, not by position.
- **F4** (input read differently): covered in section 3 input rules (comma/semicolon, "&", A2/B2, B1), E07, E11 and E12. Also section 13, items 8, 11 and 12.
- **F5** (marked done when nothing was done): there is no guard. A clinic is marked done with 0 payments or with red rows. See section 13, item 14.
- **F6** (action happened but not confirmed): covered in E15 (check ClaimDesk first). Also section 13, item 10.
- **F7** (business exception shown as success): covered in section 6 (green rows that need follow-up), E11 and E13. Also section 13, item 1.
- **F8** (re-runs and watchdog): covered in E16 and section 8. Retries are capped at 3 per clinic, so there is no endless loop. The watchdog problem is in section 13, item 5.
- **F9** (stopping the wrong way): covered in section 4. There is no Stop button and closing ClaimDesk does not stop the bot. See section 13, item 17.
- **F10** (one stuck item blocks the queue): covered in E01 and section 8. Any red row or failed clinic blocks the next upload. See section 13, items 3 and 4.
- **F11** (cause hidden from ops): covered in section 5. Clinic failures, retries, the batch status and the detailed status are hidden. See section 13, items 2, 3 and 15.
- **F12** (update didn't arrive): covered in section 10. The database lives on each machine, so nothing shared is overwritten at start. The launcher code is missing from the repo; see section 13, item 19.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | "Rejected by app" (Remittance Errors, cancelled) and "Skipped" (not ACH) are stored as Completed and shown green | Ops reads green as posted; unposted payments are missed | `bot.py:27-33` STATUS_MAP |
| 2 | The Report screen hides the detailed status and the technical comment | Ops can't tell Rejected from Posted except by reading the comment | `report_screen.py:6` COLUMNS |
| 3 | A clinic that fails all 3 attempts writes **no row** to the Report screen, only a log line; ops has no log access | A failed clinic is invisible; it looks the same as "no payments" | `bot.py:143-147` |
| 4 | A Pending batch blocks every new upload. There is no clear or resume function, and the refusal message goes to the console only. Any red row also keeps the batch Pending, even a payment that really posted (E15), and ops can't edit rows. | Every red row or failed clinic needs a dev before the next run | `bot.py:150-154`, `bot.py:167-168`, `report_screen.py:11-13` |
| 5 | The watchdog only counts a new payment row as progress. Sign-in, opening a clinic and retries don't count. It exits without cleanup, so ClaimDesk stays open and the batch stays Pending. | Slow clinics, or several empty clinics in a row, kill the whole run | `bot.py:44-49`, `bot.py:137` |
| 6 | Window match is "title contains ClaimDesk", first hit wins. It can also match the launcher ("ClaimDesk Poster") and the login window right after Sign in. Commit 7d468fa says fixed, but only a comment was added. | The bot drives the wrong window; the incident can recur | `bot.py:66-70`, `bot.py:83`, `bot.py:185` |
| 7 | After every clinic, `taskkill /im ClaimDesk.exe /f` kills every ClaimDesk process | A user's own ClaimDesk session is closed and their work is lost | `bot.py:146` |
| 8 | Clinic cells are split on "," and ";" and blank pieces are not removed | Clinics whose real names contain a comma can never be processed | `bot.py:60-62` |
| 9 | A wrong password is not detected after Sign in | It shows up as a misleading "clinic not found" | `bot.py:82-83` |
| 10 | When "Payment saved" times out, the bot does not re-check ClaimDesk | Posted payments show red; risk of posting twice | `bot.py:117-118` |
| 11 | The cutoff is compared as text (`check_date > str(cutoff)`) | Wrong payments can be deferred or posted when date formats differ | `bot.py:107` |
| 12 | The payment method must be exactly "ACH" (case-sensitive) | "Ach" and similar values are skipped | `bot.py:105` |
| 13 | A clinic retry re-walks the list and writes duplicate Report rows | Confusing duplicates on screen (E19) | `bot.py:130-139` |
| 14 | A clinic is set to Success with 0 payments, or with red rows | Nothing proves the bot was on the right, populated list | `bot.py:140` |
| 15 | Input sheet errors are not logged. A missing Clinics or Settings sheet raises a raw error with no friendly message. | Ops sees "nothing happened" | `bot.py:52-63`, `bot.py:169` |
| 16 | A missing ClaimDesk path setting causes a raw error for every clinic. The alert mail setting in `.env` is never used, so nobody is notified of anything. | Silent failures | `bot.py:74`, `.env` |
| 17 | There is no Stop button or clean stop. The launcher is not in the repo, so nobody can confirm whether closing it ends the bot process. | Ops has no safe way to stop a run | `bot.py:157-180`; launcher code missing |
| 18 | The code never creates the database tables | A new machine fails at the first query | `bot.py:166-167` |
| 19 | The launcher and update code are not in the repo. Commit d840396 (users stuck on 1.3.0) shows only a comment. | The update path can't be documented or checked | `report_screen.py:14` |
| 20 | Clinic names with "&" are suspected to fail the title check every time (not confirmed) | The clinic is never posted (E08) | `bot.py:91-92` |
| 21 | `.env` (with a password key) and a run log containing patient data are committed to git. The ClaimDesk password also sits in plain text in the input Excel. | Credential and PHI exposure | `.env`, `logs/run_20260901_101500.log:3`, `bot.py:56` |
| 22 | The committed log doesn't match the current code's messages | The incident evidence comes from a different build | `logs/run_20260901_101500.log` |