Rpa_Skills/tests/evals/results/handoff/h-packaged-desktop-screens-r2.md

# LedgerBot - ops handover

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

## 1. What the bot does

LedgerBot reconciles the day's bank statement against LedgerPro, the desktop accounting app. You give it the bank statement Excel. It opens LedgerPro, exports LedgerPro's entries to Excel, and compares each reference and amount in the statement with that export. When a statement entry is not in LedgerPro, the bot creates it in LedgerPro (New Entry → reference → amount → Save). When the amounts differ, it only reports the difference. The output is one Excel file per run, `Reconcile_<date>_<time>.xlsx`, in the output folder. The bot runs once per statement, whenever ops starts it. It drives one app: **LedgerPro**. It finds LedgerPro's buttons by matching pictures of them on the screen.

## 2. How it works

```
launcher.exe (what you start)
   ├─ checks for an update → installs it into the bot folder
   └─ starts → LedgerBot.exe ──drives (mouse + keyboard)──> LedgerPro
                    │                                   (do not touch while it runs)
                    ├─ reads  → your bank statement Excel
                    ├─ reads  → LedgerPro's export file
                    └─ writes → data\output\Reconcile_<date>_<time>.xlsx (at the very end only)
```

- **launcher.exe** checks the update server for a new version, installs it if there is one, then starts the bot. It does not wait for the bot or tell you whether the bot succeeded.
- **LedgerBot.exe** is the bot itself. It has **no window of its own**: no screen, no progress bar, no Stop button. All you see is LedgerPro being driven.
- **LedgerPro** is the accounting app. The bot clicks its buttons and types into its forms, so the mouse and keyboard belong to the bot during a run.
- **The output file** is written only when the bot has gone through every row. If no new file appears, the run did not finish.

**One run, step by step:**
1. The launcher checks for an update and starts the bot.
2. The bot opens LedgerPro from the `LedgerPro` shortcut on the Desktop, then waits 15 seconds.
3. It clicks LedgerPro's Export to Excel button, then waits 10 seconds for the export.
4. It reads the export and your bank statement.
5. It goes through the statement row by row: matching amount → OK; different amount → Mismatch; not in LedgerPro → it posts the entry.
6. It writes the output file to the output folder.

## 3. Before a run

- [ ] **Windows display scaling is 100%** and the screen resolution is **1920 x 1080** (Settings → System → Display). The button pictures were taken at that setting. At 125% the bot cannot find the buttons. Nothing checks this for you.
- [ ] LedgerPro's shortcut, named exactly `LedgerPro`, is on your Desktop or the Public Desktop. Without it, LedgerPro never opens (E01).
- [ ] LedgerPro opens fully within 15 seconds on this machine, with no login box, update prompt or popup in front. The bot does not handle popups.
- [ ] LedgerPro's export saves to the bot's usual export location (as set up by dev). The bot does not check that the export file is from today (E08).
- [ ] Only one monitor is in use, or LedgerPro is on the main monitor. The bot only looks at the main screen.
- [ ] Bank statement Excel, first sheet:
  - Row 1 is a header. Data starts on row 2.
  - Column A = reference, column B = amount. Nothing else is read.
  - **Every row with a reference must have an amount, as a real number.** An empty amount or text like `1,200.00 CR` stops the whole run (E09).
    Bad: `TX-1001 | (blank)` · Good: `TX-1001 | 1200.00`
  - **Each reference once.** If a reference appears twice, only the last row is used and the other is silently dropped.
  - Type references as text, exactly as LedgerPro shows them. A reference typed as a plain number can be read as `1001.0` and will not match LedgerPro's `1001`.
    Bad: `1001` stored as a number · Good: `1001` stored as text (or `TX-1001`)
  - Use only plain English letters, digits and punctuation in references. The bot cannot type accented or other special characters.
- [ ] Start the run by **dragging the statement Excel onto `launcher.exe`** (or the shortcut ops was given). Starting it without a file does nothing visible and produces no output.
- [ ] Version check: the bot has no screen that shows its version today (see section 10). Ask dev to confirm the version after each release.

## 4. During a run

- **Hands off the mouse and keyboard** for the whole run. The bot types into whatever window has focus. If you click elsewhere, it types references and amounts into that window.
- Do not open or move other windows over LedgerPro. A window covering a button makes the bot fail that row.
- **Do not move the mouse into a corner of the screen.** That is the emergency stop: the bot stops at once and **writes no output file**, but anything it already posted stays posted in LedgerPro.
- **To stop the bot:** there is no Stop button. Move the mouse into a corner of the screen, or end `LedgerBot.exe` in Task Manager. Closing LedgerPro does **not** stop the bot. After stopping, do the checks in E07 before running again.
- **How long a run takes:** about 30 seconds of start-up, then a few seconds per posted entry. Every row that fails costs an extra 20 seconds or more. If one Save fails, the following rows often fail too (E04), so a run with many failures can take a long time. There is no watchdog. If LedgerPro has shown no movement for more than 2 minutes and no output file has appeared, stop the bot as above and follow E07.

## 5. Where to look when something goes wrong

Ops can open the output folder and the output files only. The bot has no screens of its own, and the log folder is not open to ops (see *Fix before handover*).

| Question | Where to look |
|---|---|
| Did the run finish? | Output folder `data\output\`: is there a new `Reconcile_<date>_<time>.xlsx` with the time of this run? No new file = the run did not finish (E01, E02, E07, E09). |
| Which items failed? | The output file, **Result** column = `Error`. Also check `Mismatch` rows: they need a person. |
| Why did one item fail? | The output file, **Note** column of that row. Then look at LedgerPro itself. |
| Was an entry really posted? | Only LedgerPro can tell you. The bot writes `Posted` after clicking Save, without checking (E05). |
| Did the bot already retry? | It never retries an item or a run. It only searches for a button for 20 seconds before giving up on that row. |
| Which version is running? | Not visible to ops today. Ask dev (section 10). |

## 6. Statuses

The output file has no colours. Statuses are the text in the **Result** and **Note** columns.

| Result | Note | Meaning | What ops does |
|---|---|---|---|
| `OK` | (empty) | The reference is in LedgerPro with the same amount (within 1 cent). | Nothing. |
| `Missing` | `Posted` | The reference was not in LedgerPro, and the bot entered it and **clicked Save**. Despite the word "Missing", the bot **believes it posted the entry**. It did **not** check that the save worked. | Spot-check a few in LedgerPro. Check all of them if any Save-related errors appear in the same run (E04, E05). |
| `Mismatch` | `LedgerPro has <amount>` | The reference exists in LedgerPro with a different amount. **The bot changed nothing.** | **Needs follow-up.** Investigate and correct by hand in LedgerPro (E06). |
| `Error` | `Button new_entry.png not found on screen` | The bot could not find LedgerPro's New Entry button. Nothing was entered for this row. | E03. |
| `Error` | `Button save_btn.png not found on screen` | The bot typed the entry but could not find the Save button. The entry is **most likely not saved**, and the form may still be open. | E04. |
| (no output file) | - | The run stopped before the end. Nothing is recorded for any row, even rows already posted. | E07. |

`Not in LedgerPro - posting` is a note the bot sets internally before posting. It is always replaced, so you will never see it in the output.

## 7. Exception catalogue

| ID | What you see | How the bot identifies it | Where it is recorded | Type | Who acts | What to do | Escalate when |
|---|---|---|---|---|---|---|---|
| E01 | LedgerPro never opens; no output file appears | It looks for a shortcut named `LedgerPro` on your Desktop and the Public Desktop. If neither has one, it stops at once. | Nowhere ops can see. No output file. | System | Ops | Put the `LedgerPro` shortcut on the Desktop (exact name), then run again. | The shortcut is there and LedgerPro still does not open. |
| E02 | LedgerPro opens, but nothing is clicked; no output file appears | After 15 s it looks for the Export to Excel button for 20 s. If it never matches the button picture, it stops the run. | Nowhere ops can see. No output file. | System | Ops, then Dev | Check scaling is 100% and resolution 1920 x 1080; close any popup or login box in LedgerPro; make sure LedgerPro is maximised on the main screen; run again. | It still happens with the right settings, or it happens on a fresh install or right after an update (the button pictures may be missing from the build, see incident #3). |
| E03 | Result `Error`, Note `Button new_entry.png not found on screen` | When posting, it looks for the New Entry button for 20 s and gives up on that row. | Output file, Result and Note | System | Ops | Check scaling and popups as in E02. Check in LedgerPro that the reference is not there, then run again with the statement. | Several runs in a row fail this way with correct settings. |
| E04 | Result `Error`, Note `Button save_btn.png not found on screen`, often followed by more Errors on later rows | It clicked New Entry and typed the reference and amount, then looked for Save for 20 s and gave up. It does not close the half-filled form, so later rows may type into the wrong place. | Output file, Result and Note | System | Ops | 1. In LedgerPro, close any open New Entry form without saving. 2. **Search LedgerPro for each Error reference and for the `Missing / Posted` rows after it**, to see what was really saved. 3. Fix or delete stray entries by hand. 4. Run again. | It happens again after a clean restart with correct settings. |
| E05 | Result `Missing`, Note `Posted`, but the entry is not in LedgerPro or has the wrong amount | The bot writes `Posted` as soon as it clicks Save. It does not check for a save confirmation, a validation message, or that the typed text landed in the right fields. | Output file says `Posted`; the truth is only in LedgerPro | System | Ops | **Check in LedgerPro before re-running.** Enter or correct the entry by hand, or run again with a statement holding only the missing rows. | More than one or two per run, or wrong amounts typed. Send the output file. |
| E06 | Result `Mismatch`, Note `LedgerPro has <amount>` | The reference is in LedgerPro, but the amounts differ by more than 1 cent. | Output file, Result and Note | Business | Ops | Find out which amount is right (statement or LedgerPro) and correct it by hand. The bot never changes existing entries. | Never for dev, unless the amounts are clearly read wrongly (e.g. every row mismatches). |
| E07 | The run stops midway: LedgerPro stops moving and no output file appears | Any unexpected problem stops the whole run: the mouse touched a screen corner, an amount could not be read, an unexpected error in LedgerPro. Nothing is recorded. | Nowhere. No output file, even for rows already posted. | System | Ops, then Dev | 1. **Do not re-run straight away.** 2. In LedgerPro, close any open form. 3. Check which statement references are already in LedgerPro. 4. Check the statement against the input rules in section 3. 5. Run again. | It stops again with a clean statement and nobody touching the machine. |
| E08 | Many rows `Missing / Posted` that were already in LedgerPro, or duplicate entries in LedgerPro after a run | The bot reads the last export file 10 s after clicking Export. If the export was slower, or saved elsewhere, it reads an older export without noticing. | Output file looks normal; duplicates only show in LedgerPro | System | Dev | Remove the duplicate entries in LedgerPro by hand. Do not run again until dev has checked the export. | Always. |
| E09 | No output file, right after LedgerPro exports | The bot could not read the statement: an empty or text amount, no file given, or the file is not an Excel workbook. | Nowhere. No output file. | Business | Ops | Fix the statement as per section 3 (every amount a number, one reference per row), then run again. | The statement is clean and it still fails. |
| E10 | A row you expected is missing from the output file | The statement had the same reference twice. The bot keeps only the last one. | Not recorded | Business | Ops | Remove duplicates from the statement, or post the dropped row by hand. | - |
| E11 | Text appears in another window; references or amounts typed in the wrong place | Someone used the mouse or keyboard, or another window came in front. The bot types into whatever has focus. | Not recorded | System | Ops | Undo the stray typing. Check LedgerPro for half-entered entries. Run again hands-off. | - |
| E12 | After a release, this machine behaves like the old version | The launcher could not reach the update server (offline, or the server's certificate is not trusted on this machine). It ignores the problem and starts the old version. | Not recorded | System | Dev | Raise a ticket so dev can check the version and update this machine. | Always, after every release where behaviour does not change. |
| E13 | Double-clicking the launcher does nothing; the bot never starts | The update download or install failed, and the launcher stopped before starting the bot. | Not recorded | System | Dev | Raise a ticket. Do not copy files into the bot folder yourself. | Always. |

## 8. What the bot recovers by itself

Very little. Ops should not expect it to fix anything on its own.

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| A button is not on screen yet | Looks for it once a second | 20 s per button | Export button: the whole run stops (E02). New Entry or Save: that row is `Error`, next row (E03, E04). |
| LedgerPro is slow to open | Nothing; it simply waits | Fixed 15 s | Same as above. |
| Export is slow | Nothing; it simply waits | Fixed 10 s | Reads whatever export file is there (E08). |
| Update server unreachable | Starts the old version without telling you | 10 s | Old version keeps running (E12). |
| Anything else | No retry, no restart, no resume | - | Run stops with no output file (E07). |

## 9. Known incidents

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| Up to v3.2.0 (#3) | The packaged bot failed at its very first button on every machine | The button pictures were left out of the packaged build | Dev says this is fixed, but the current build file does not show it. If the bot fails at the first button on a fresh install or after an update, raise a ticket (E02). | No |
| Up to v3.2.0 (#2) | Rows `Error` "Button save_btn.png not found on screen" on some laptops | Laptops at 125% display scaling. The button pictures only match at 100%. | Keep scaling at 100% and resolution 1920 x 1080 (section 3). Check this first for any "not found" error. | Yes |
| Up to v3.2.0 (#1) | Two laptops stayed on the old version after a release; no error | The launcher could not trust the update server's certificate and quietly ran the old version | Still possible: the code still hides this. After each release, ask dev to confirm every machine's version (E12). | Partly |

## 10. Releases and version check

- **How an update arrives:** each time you start `launcher.exe`, it asks the update server for the latest version. If it differs, it downloads it and installs it into the bot folder, then starts the bot.
- **How to confirm it applied:** ops cannot see the version today. The bot has no window or title bar. Ask dev to confirm through the RPA Support ticket after each release.
- **If the version did not change** (behaviour after a release is unchanged): raise a ticket (E12). Do not copy files into the bot folder by hand.
- All machines should run the same version, so that results from different machines are comparable.

## 11. Escalating to dev

Raise a ticket in the **RPA Support** queue. Send:
- the exception ID from section 7 (e.g. E04),
- the machine name and the date and time the run started,
- the file name of the bank statement used (not its contents in chat),
- the output file `Reconcile_<date>_<time>.xlsx`, if one was produced, or "no output file",
- the Result and Note of the failing rows,
- what LedgerPro showed at the time (a description, or a screenshot that shows no customer data).

Dev collects the bot's own log and "not found" screenshots from the machine; ops does not have access to them.

Never send: passwords, the bot's settings files, or customer or account data in chat.

## 12. Failure-class check

- **F1** missing prerequisite: covered in section 3 (shortcut, scaling, single screen) and E01, E02, E13; required folders and build contents in *Fix before handover* #9, #11.
- **F2** wrong window or focus: covered in section 4 (hands off, nothing over LedgerPro) and E11. The bot does not look for windows by title; it clicks wherever the button picture matches on the main screen.
- **F3** target app slower or different: covered in E02, E03, E04, section 8 (fixed 15 s and 10 s waits, 20 s per button) and section 3 (scaling, resolution, popups); *Fix before handover* #2, #6.
- **F4** input read differently: covered in section 3 input rules, E09, E10; *Fix before handover* #10.
- **F5** marked done when nothing was done: covered in E05 and E08; *Fix before handover* #1, #2.
- **F6** action happened but not confirmed: covered in E04, E05 and E07 (check in LedgerPro before re-running); *Fix before handover* #1, #5.
- **F7** business exception shown as success: covered in section 6. `Mismatch` needs follow-up but has no colour, and posted rows keep the result `Missing`; *Fix before handover* #7.
- **F8** endless re-runs or watchdog: covered in section 4. The bot has no re-runs and no watchdog, so a hung run has no time limit; *Fix before handover* #3.
- **F9** stopping the wrong way: covered in section 4 (corner or Task Manager; closing LedgerPro does not stop it) and E07.
- **F10** one stuck item blocks the queue: covered in E04. A failed Save leaves the form open and later rows fail too. There are no batches or locks between runs; *Fix before handover* #5.
- **F11** cause hidden from ops: covered in section 5. Crash reasons, the log and the screenshots are not reachable by ops; *Fix before handover* #3, #4, #8.
- **F12** update did not arrive: covered in section 10, E12, E13 and incident #1; *Fix before handover* #12, #13, #14.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | `Posted` is written as soon as Save is clicked; no save confirmation or check that the entry exists | Ops trusts entries that may not be in LedgerPro (E05) | `app.py:65-70`, `app.py:89-90` |
| 2 | Fixed sleeps for LedgerPro start (15 s) and export (10 s); the export file's date is never checked | A slow export means an old export is read, giving false `Missing` rows and duplicate posts (E08) | `app.py:75-79` |
| 3 | Output is written only at the end; a crash leaves no file and no reason anywhere; no watchdog | Ops cannot tell what was posted before a crash (E07) | `app.py:82-96`, `app.py:100-101` |
| 4 | Only one error type is caught per row; any other error (fail-safe corner, bad amount, image-library exception) ends the run | One bad row loses the whole run's results | `app.py:91`, `app.py:52`, `app.py:81` |
| 5 | After "Save not found" the half-filled form is left open; no reset before the next row | One failure spreads to later rows (E04) | `app.py:65-70`, `app.py:88-92` |
| 6 | No check of display scaling or resolution at start; images match only at 100% / 1920x1080 | Wrong setting shows up as many 20 s failures | `app.py:20` |
| 7 | Rows the bot posted keep Result `Missing`; nothing in the file is coloured; `Mismatch` is not flagged as needing follow-up | Ops reads `Missing` as "not done" and may post twice | `app.py:58`, `app.py:87-94` |
| 8 | The log and "not found" screenshots are in the log folder, which ops cannot open. Screenshots overwrite each other (no time or reference in the name) and may show customer data. All lines are INFO, with no start, end or error lines. The run summary goes only to the console. | Ops has no way to see the cause beyond the Note column | `app.py:24-25`, `app.py:45`, `app.py:95`, `app.py:97` |
| 9 | `logs\` and `data\output\` must already exist; missing `logs\` crashes at start, missing `data\output\` crashes after all posting | All posting done, no record of it | `app.py:24`, `app.py:96` |
| 10 | Statement input not validated: empty or text amount crashes the run; duplicate references silently collapse; numeric references become `1001.0`; no file argument crashes; non-ASCII cannot be typed | Silent skips and lost runs (E09, E10) | `app.py:81`, `app.py:67`, `app.py:101` |
| 11 | The build spec is only comments; the line that bundles the button pictures is commented out. The "assets missing" fix commit is not in the code. | A rebuild brings back incident #3 | `ledgerbot.spec:1-3` |
| 12 | The launcher still hides every update error (offline, SSL, bad reply). The "SSL error" fix commit only added a comment. | Machines stay on old versions unnoticed (E12) | `launcher.py:15-20`, `launcher.py:35` |
| 13 | The launcher compares versions with "not equal" and its own version is fixed at build time, so it can reinstall on every start, or install an older version. No checksum on the download; `update.zip` is left behind. | Slow starts, wrong versions, launcher crash (E13) | `launcher.py:9`, `launcher.py:25-29` |
| 14 | No visible version. The comment says the window title shows "LedgerBot v3.2.0", but there is no window. | Ops cannot do a version check (section 10) | `app.py:15` |
| 15 | No guard against posting twice when a run is repeated after a crash or with an old export | Duplicate entries in LedgerPro | `app.py:86-92` |
| 16 | Library versions are not pinned; newer versions of the image library raise an error instead of "not found", which would crash runs on any missing button | A rebuild can change behaviour silently | `requirements.txt` |
| 17 | The marker file `BOT_WAS_RUN` is written at start but never read | None today; misleading if someone relies on it | `app.py:74` |