# LedgerBot - ops handover

Version 3.2.0 · Written 2026-10-23 · Escalation: RPA dev team, Teams channel **#rpa-support**

## 1. What the bot does

LedgerBot reconciles the daily bank statement Excel against the LedgerPro desktop accounting app. You give it the statement file. It opens LedgerPro, exports LedgerPro's entries to Excel, and compares the two by reference:
- When the reference and amount match, it does nothing.
- When the amount differs, it reports the difference and changes nothing.
- When the reference is not in LedgerPro, it **types the entry into LedgerPro and saves it**.

It writes one result file per run, `data/output/Reconcile_<date>_<time>.xlsx`. It drives one app, **LedgerPro**, by finding buttons on the screen from pictures and clicking them. Entries that are in LedgerPro but not in the statement are ignored and are not reported.

## 2. How it works

```
launcher.exe (what you start, with the statement file)
   ├─ checks the update server → downloads and unpacks a new build if there is one
   └─ starts → LedgerBot.exe (no window of its own) ──drives──> LedgerPro
                    │                                  (do not touch while it runs)
                    ├─ writes → data/output/Reconcile_<date>_<time>.xlsx   (only at the very end)
                    ├─ writes → logs/ledger_<date>.log                     (one line per entry)
                    └─ writes → logs/notfound_<button>.png                 (screenshot when a button is not found)
```

- **launcher.exe** checks for an update, then starts the bot and closes itself straight away.
- **LedgerBot.exe** does all the work. It has no window and no Stop button.
- **LedgerPro** is the app the bot clicks and types in. While the bot runs, the mouse and keyboard belong to the bot.
- **The Reconcile file** is the result of the run. It is saved only after the last entry is done.
- **The daily log** gets one line per entry: the reference, the result and the note.
- **The screenshot** is a picture of the whole screen at the moment a button could not be found.

**One run, step by step:**
1. Starts LedgerPro from the LedgerPro shortcut on the Desktop.
2. Waits 15 seconds, then clicks LedgerPro's Export to Excel button.
3. Waits 10 seconds, then reads the LedgerPro export.
4. Reads the bank statement.
5. For each statement row: OK, Mismatch, or a missing entry, which it posts with New Entry → reference → Tab → amount → Save.
6. Saves the Reconcile file.

## 3. Before a run

- [ ] **Windows display scaling is 100% and the resolution is 1920x1080** (Settings → System → Display). At 125% the bot cannot find the buttons (incident in section 9). LedgerPro must open on that screen.
- [ ] The **LedgerPro shortcut** (named exactly `LedgerPro`) is on your Desktop or the Public Desktop.
- [ ] LedgerPro **opens already signed in** and ready within 15 seconds. The bot does not sign in.
- [ ] LedgerPro's Export to Excel saves to the bot's `data` folder as `ledger_export.xlsx`, overwriting the old one. The bot only clicks Export. If an old export is still there, **the bot compares against yesterday's ledger and can post entries twice** (E07). Ask dev to confirm this is set up on your machine.
- [ ] The `logs`, `data` and `data/output` folders exist next to `LedgerBot.exe`. If `logs` is missing, nothing starts. If `data/output` is missing, the whole run's results are lost at the end.
- [ ] The statement Excel follows these rules. The bot reads the first sheet, starting from row 2:

| Rule | Good | Bad |
|---|---|---|
| Row 1 is a header | `Reference \| Amount` | The first entry in row 1. It is skipped. |
| Column A holds the reference, column B the amount | `TX-1001 \| 250.00` | Amount in column C |
| The amount is a plain number | `250.00` | `$250.00`, `250,00`, `n/a`. The whole run stops with no result file. |
| Each reference appears once | One row per reference | The same reference twice. Only the last one is checked, and the other disappears from the result file. |
| No blank reference in the middle | Every row has a reference | A blank reference. That row is skipped without any message. |

- [ ] Start the bot by **dropping the statement Excel onto `launcher.exe`**, or by starting `launcher.exe` with the file path. If no file is given, the bot stops at once and nothing happens.
- [ ] After a new release, check the version (section 10).

## 4. During a run

- **Don't use the mouse or keyboard on this machine.** The bot types into whatever window has focus. If you click elsewhere, the reference and amount are typed into that window.
- Don't open other windows over LedgerPro, and don't move LedgerPro to another monitor.
- **Don't move the mouse into a screen corner.** That is the emergency stop, see below.
- To stop the bot there is no Stop button. Use one of these:
  - Move the mouse hard into a corner of the screen. The bot stops at its next click or keystroke.
  - Or end **LedgerBot.exe** in Task Manager.
  - Closing LedgerPro does **not** stop the bot. It keeps clicking and typing into whatever is on the screen.
  - Closing launcher.exe does nothing, because it has already exited.
  - **Either way, no Reconcile file is written.** Use the log (E05).
- A run looks stuck when LedgerPro does nothing for more than about 20 seconds. The bot waits 20 seconds for each button, then gives up on that entry. There is no other watchdog. The bot finishes or stops by itself, so wait for it.
- The run is finished when a new `Reconcile_<date>_<time>.xlsx` appears in `data/output`.

## 5. Where to look when something goes wrong

| Question | Where to look |
|---|---|
| Did the run finish? | A new `Reconcile_<date>_<time>.xlsx` in `data/output` with the time of this run. No new file means the run stopped early (E04 / E05). |
| Which entries failed? | The Reconcile file, Result column = `Error` or `Mismatch` |
| Why did one entry fail? | The Reconcile file, Note column. Then `logs/ledger_<date>.log`: search for the reference. |
| What did the screen look like when a button was not found? | `logs/notfound_new_entry.png`, `logs/notfound_save_btn.png`, `logs/notfound_export_excel.png`. Each one shows **only the most recent** failure for that button. Check its time. |
| The run stopped early. What was done? | `logs/ledger_<date>.log`. Each line written during this run is an entry the bot finished. A line saying `Missing Posted` means the bot posted that entry. |
| Did the bot already retry? | It never retries an entry. It only waits up to 20 s for each button (section 8). |
| Was the entry really saved in LedgerPro? | Only LedgerPro can tell you. The bot does not check after Save (E06). |
| Which version is running? | Nothing on screen shows it. See section 10. |

## 6. Statuses

The Reconcile file has no colours. Each row's status is the Result column plus the Note column.

| Result | Note | Colour | Meaning | What ops does |
|---|---|---|---|---|
| `OK` | (empty) | none | The reference and amount match LedgerPro | nothing |
| `Missing` | `Posted` | none | **The entry was not in LedgerPro and the bot posted it.** "Missing" here means "was missing, now posted". The bot did not confirm that the save worked. | Spot-check a few in LedgerPro (E06) |
| `Missing` | `Not in LedgerPro - posting` | none | Temporary note. It is always replaced by `Posted` or by an error before the file is saved. | You should never see it. If you do, contact Dev. |
| `Mismatch` | `LedgerPro has <amount>` | none | **Needs follow-up.** The reference exists, but the amount in LedgerPro differs by more than 0.01. The bot changed nothing. | Correct it by hand (E01) |
| `Error` | `Button new_entry.png not found on screen` | none | The entry was not posted. The bot could not find New Entry. | E02 |
| `Error` | `Button save_btn.png not found on screen` | none | The entry was typed but **not saved**. A half-filled form may still be open in LedgerPro. | E03 |

## 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 | Row `Mismatch`, note "LedgerPro has 240.00" | The reference is in both files, but the amounts differ by more than 0.01 | Reconcile file; log line | Business | Ops | Check the bank statement and LedgerPro, then correct the right one by hand. The bot never fixes amounts. | Many rows mismatch by the same pattern, which suggests a wrong export or a wrong file |
| E02 | Row `Error`, note "Button new_entry.png not found on screen" | It looks for the New Entry button picture for 20 s. When it is not found, it saves a screenshot and moves on to the next entry. | Reconcile file; log line; `logs/notfound_new_entry.png` | System | Ops, then Dev | 1) Check that display scaling is 100% and 1920x1080. 2) Open the screenshot: was a popup or another window covering LedgerPro? 3) Post the entry by hand in LedgerPro, or re-run (see E07 first). | Scaling is 100%, nothing covered LedgerPro, and it still happens. Send the time, the reference, the screenshot and the log file. |
| E03 | Row `Error`, note "Button save_btn.png not found on screen" | The bot clicked New Entry and typed the reference and amount. It then could not find Save for 20 s, saved a screenshot and moved on. | Reconcile file; log line; `logs/notfound_save_btn.png` | System | Ops | 1) In LedgerPro, look for an **unsaved, half-filled entry** and cancel it, or save it if it is correct. 2) **Check the next entry after this one too.** The bot may have typed it into the same open form. 3) Check scaling as in E02. 4) Post the entry by hand. | Same as E02 |
| E04 | **No new Reconcile file, and no new lines in today's log** | The run stopped before checking any entry. Possible causes: LedgerPro shortcut not found; LedgerPro not ready within 15 s; Export button not found (a new `logs/notfound_export_excel.png` appears); the export file missing; a statement amount that is not a number; no statement file given. **The cause is not written anywhere.** | Nothing, except possibly the export screenshot | System | Ops, then Dev | Work through section 3: shortcut, LedgerPro signed in, scaling, the statement amounts are plain numbers, you dropped the file onto launcher.exe. Then run again. Nothing was posted, so a re-run is safe. | It still fails after the checklist. Send the time, the statement file name (not its contents) and any `notfound_export_excel.png`. |
| E05 | **No new Reconcile file, but today's log has entry lines from this run** | The run stopped part-way, or at the end while saving: you used the corner stop or Task Manager, the `data/output` folder is missing, or an unexpected error happened. The cause is not written anywhere. | Log lines only | System | Ops, then Dev | 1) Use the log as the result. Every `Missing Posted` line **was posted**. 2) Entries with no line were not handled. 3) Re-run **only** with a fresh LedgerPro export (E07), or post the rest by hand. | Always report it unless you stopped the bot yourself. Send the time, the last log line and the log file. |
| E06 | An entry marked `Missing` / `Posted`, but it is not in LedgerPro | After clicking Save, the bot does not check that LedgerPro saved the entry. It writes "Posted" as soon as the Save click happens. | Reconcile file says Posted. LedgerPro is the only proof. | System | Ops | Search LedgerPro for the reference. If it is not there, post it by hand. | More than one in a run. Send the time, the references and the log file. |
| E07 | The same entry appears **twice** in LedgerPro | The bot posts every statement reference that is not in `ledger_export.xlsx`. If that export is old (the export didn't save over it, or a re-run happened after a partial run), entries already posted look "missing" again. | LedgerPro; two runs' Reconcile files or log lines both say Posted | System | Ops, then Dev | Delete the duplicate in LedgerPro. Before any re-run, make sure LedgerPro's export overwrites `ledger_export.xlsx`. | Always. The export setup needs fixing. Send both run times and the references. |
| E08 | Typing appears in the wrong window, or LedgerPro gets odd values | The bot types blind into the window that has focus. It does not check that the window is LedgerPro. | Nowhere | System | Ops | Find and undo the stray typing. In LedgerPro, check the entries posted around that time. Keep hands off during runs (section 4). | It happens with nobody touching the machine |
| E09 | launcher.exe shows an error or closes, and the bot never starts | Downloading or unpacking an update failed. The launcher has no error handling for this. | Nowhere, except the error box, if any | System | Dev | Take a screenshot of the error. Don't keep retrying. | Always. Send the time, the screenshot and the machine name. |
| E10 | A fix that dev announced isn't working on this machine | The launcher could not reach the update server. It may be offline, or the machine may not trust the server's certificate. The launcher then runs the old build **without any message**. | Nowhere | System | Dev | Check the bot files' date (section 10). | The date did not change after a release. Send the machine name. |
| E11 | A statement row is missing from the Reconcile file | The same reference appears twice in the statement, so only the last row is checked. Or the reference cell is blank. | Nowhere | Business | Ops | Fix the statement (section 3 rules) and check those rows by hand | - |

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| A button (Export, New Entry, Save) is not on screen yet | Looks again every second | 20 s per button | New Entry / Save: row = Error, screenshot saved, next entry. Export: the run stops (E04). |
| LedgerPro slow to start | Nothing. It waits a fixed time. | 15 s | Carries on regardless. The usual result is E04. |
| Export slow to save | Nothing. It waits a fixed time. | 10 s | Reads whatever `ledger_export.xlsx` is there, possibly an old one (E07) |
| Failed entry | **No retry** | - | Ops posts it by hand or re-runs |
| Run stopped | **No restart, no resume** | - | Ops follows E04 / E05 |

The longest the bot ever waits on one thing is 20 seconds. If nothing has happened for a minute, the run has ended. Check for the Reconcile file.

## 9. Known incidents

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| 2026-09 (fix 3b3625f) | Rows `Error` "Button save_btn.png not found on screen" on some laptops | Windows display scaling at 125%. The button pictures are matched at 100% only. | Button pictures were re-captured at 100%. **Keep scaling at 100% and 1920x1080** (section 3). Follow E03 for affected rows. | Yes |
| (fix 30cb604) | Two laptops never received an update and kept running the old build | The update server's certificate isn't trusted on those laptops. The launcher hides the error and runs the old build. | **Not fixed in code:** the error is still hidden. After every release, check the version on each machine (section 10), then E10. | Partly |
| (fix 6694f19) | The packaged bot could not find any buttons | The button pictures were left out of the exe build | Build fix. Do a test run after each new release. | No |

## 10. Releases and version check

- **How an update arrives:** launcher.exe checks the update server on every start. When the server reports a different version, the launcher downloads it and unpacks it into the bot folder.
- **How to confirm it applied:** the bot has no window, so **the version is not shown anywhere**. The only sign is the *Date modified* of `LedgerBot.exe` in the bot folder. It should match the release date dev announced in #rpa-support.
- **If the date did not change:** the update was skipped without any message (E10). Post the machine name in #rpa-support. Dev will copy the build over by hand or fix the certificate on the machine.
- After any release, do one test run with a small statement. Confirm a Reconcile file appears and that the rows are not all `Error`.

## 11. Escalating to dev

Post in Teams **#rpa-support**. Send:
- the exception ID from section 7 (for example "E05")
- the date and time of the run, and the machine name
- the `logs/ledger_<date>.log` file
- the matching `logs/notfound_*.png` screenshot, if there is one
- the Reconcile file name (attach it only if your team allows sharing it)

Never send passwords, the bot's settings file, or bank statement or ledger contents pasted into chat. The screenshots and logs show financial data, so share them only in #rpa-support.

## 12. Failure-class check

- F1 covered in section 3 (shortcut, folders, LedgerPro signed in, how to start) and E04, E09.
- F2 covered in section 4 (hands off, nothing over LedgerPro) and E08; no window check is in Fix #6.
- F3 covered in section 3 (100% / 1920x1080), E02, E03 and E04, and section 8 (20 s, 15 s and 10 s limits); fixed waits are in Fix #7.
- F4 covered in the section 3 input table and E11; fix in Fix #8.
- F5 covered in E06; fix in Fix #2.
- F6 covered in E03 and E06 (check in LedgerPro before re-posting); fix in Fix #2.
- F7 covered in section 6 ("Missing / Posted" means posted; Mismatch needs follow-up); fix in Fix #9.
- F8 not applicable: there is no automatic re-run and no watchdog. The risk from a manual re-run (double posting) is covered in E07.
- F9 covered in section 4 (corner stop or Task Manager; closing LedgerPro does not stop it).
- F10 not applicable: there are no batches, queues or locks, and each run stands alone. The one case of an item spilling into the next one (a half-filled form) is in E03.
- F11 covered in Fix #3, #4 and #5 (crash cause not recorded, summary not saved, screenshots overwritten).
- F12 covered in section 10, E09 and E10; fixes in Fix #1 and #10.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | The update check swallows every error (SSL, offline, bad JSON) and runs the old build without a message. The 30cb604 "fix" only added a comment. | Machines stay on old builds without anyone knowing (E10) | `launcher.py:15-20` |
| 2 | "Posted" is written right after the Save click. Nothing confirms that LedgerPro saved the entry. | Rows show Posted when nothing was posted (E06) | `app.py:89-90`, `app.py:65-70` |
| 3 | Crashes are not logged and not caught outside the posting step: missing shortcut, Export not found, missing export file, bad amount, missing argument, missing `data/output`. Only `RuntimeError` is caught. pyautogui's own exceptions (newer `ImageNotFoundException`, `FailSafeException`) also crash the run. | No result file and no cause anywhere (E04 / E05) | `app.py:34`, `app.py:77-81`, `app.py:91`, `app.py:96`, `app.py:101` |
| 4 | The Reconcile file is saved only at the end. A stop mid-run loses every result, including what was already posted. | Ops must rebuild the result from the log (E05) | `app.py:96` |
| 5 | Screenshots are named per button only, with no time or reference, so they overwrite each other. The run summary goes to stdout only, and nothing reads it. | Evidence is lost. There is no run start/end marker in the log. | `app.py:45`, `app.py:97`, `app.py:95` |
| 6 | No check that LedgerPro has focus before typing. A Save failure leaves a half-filled form, and the next entry types into it. | Stray or merged entries (E03, E08) | `app.py:65-70`, `app.py:91-92` |
| 7 | Fixed sleeps (15 s and 10 s) instead of waiting for LedgerPro or the export. The export file's freshness is never checked, and nothing in the code saves the export to `data/ledger_export.xlsx`, although the docstring says the bot does. | Stale export leads to double posting (E07) | `app.py:76-79`, `app.py:50` |
| 8 | Duplicate references in the statement or the export silently collapse into one. Blank references are skipped. A non-numeric amount crashes the run. | Rows vanish from the result (E11) | `app.py:52`, `app.py:81` |
| 9 | Posted entries keep Result = "Missing". Ops reads "Missing" as "not done". | Misleading status | `app.py:87-90` |
| 10 | No version is visible anywhere. The comment claims a window title, but the bot has no window. The spec is a commented-out stub, so the 6694f19 asset fix can't be verified from this repo. The launcher compares against the VERSION frozen into its own exe, and a running launcher.exe can't overwrite itself if the zip contains it (likely re-download on every start, or an unpack error). The download and unpack have no error handling. | Ops can't confirm a release; possible E09 | `app.py:15`, `ledgerbot.spec:1-3`, `launcher.py:9`, `launcher.py:25-29` |
| 11 | No display-scaling or resolution check at startup. Ops must remember the 100% rule. | E02 / E03 at any other scaling | `app.py:20` |
| 12 | `.env` with LedgerPro credentials is committed to git, and no code reads it. | Credential exposure in the repo | `.env` (tracked) |
| 13 | The existing log from 2026-09-05 has a counterparty name in a Mismatch line, which the current code doesn't write. It came from an older build. | Logs may hold customer data. Purge or restrict the old logs. | `logs/ledger_20260905.log:3` |
| 14 | `requirements.txt` doesn't pin pyautogui or pyscreeze. Newer versions raise an exception instead of returning "not found", which breaks the 20 s wait and the screenshot. | E02 / E03 could become run crashes after a rebuild | `requirements.txt`, `app.py:40` |