# 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 bank statement Excel against the LedgerPro desktop accounting app and posts any entries LedgerPro is missing. It runs on demand, once per statement. You give it the statement Excel file. It opens LedgerPro, exports LedgerPro's entries to Excel, and compares the two files by reference number. It posts each missing entry into LedgerPro by clicking LedgerPro's buttons and typing the reference and amount. It reports amount differences but does not fix them. The output is one Excel file per run, `data/output/Reconcile_<date>_<time>.xlsx`. It drives one app: **LedgerPro**.

## 2. How it works

```
launcher.exe (what you start, with the statement Excel)
   └─ checks for an update, then starts → LedgerBot.exe ──clicks & types──> LedgerPro
                                             │                     (do not touch while it runs)
                                             ├─ reads  → the export LedgerPro saves (data/ledger_export.xlsx)
                                             ├─ writes → data/output/Reconcile_<date>_<time>.xlsx (at the very end)
                                             └─ writes → logs/ledger_<date>.log, logs/notfound_<button>.png
```

- **launcher.exe** looks for a newer build on the update server and installs it if it finds one. It then starts LedgerBot and closes. It shows nothing on screen.
- **LedgerBot.exe** is the bot. It has no screen of its own. It works by finding LedgerPro's buttons on screen from saved pictures of them, then clicking and typing like a person would.
- **LedgerPro** is the app being driven. While the bot runs, the mouse and keyboard belong to the bot.
- **The export file** is the list of entries LedgerPro already has. The bot reads it to decide what is missing.
- **The Reconcile file** is the result. There is one row per statement line.
- **The log** has one line per statement line. The **notfound picture** is a screenshot taken when a button could not be found.

**One run, step by step:**
1. The launcher checks for an update and starts the bot.
2. The bot opens LedgerPro from its Desktop shortcut and waits 15 seconds.
3. It clicks LedgerPro's Export to Excel button and waits 10 seconds.
4. It reads LedgerPro's export and your statement.
5. It goes through every statement line:
   - Same reference and same amount: **OK**.
   - Same reference, different amount: **Mismatch**. Nothing is posted.
   - Reference not in LedgerPro: the bot clicks New entry, types the reference and amount, and clicks Save.
6. It saves the Reconcile file. This happens only after the last line.

## 3. Before a run

- [ ] The display is at **100% scaling and 1920 x 1080** (Settings > System > Display). At any other setting, for example 125% or a docking station with another monitor, the bot cannot find LedgerPro's buttons (see E03, E07 and E08).
- [ ] A shortcut named exactly **LedgerPro** is on your Desktop or the Public Desktop. Otherwise the bot stops at once (E02).
- [ ] The folders `logs` and `data\output` exist next to LedgerBot.exe. Without `logs` the bot stops before doing anything (E01). Without `data\output` the bot posts everything and then stops without saving the results (E11).
- [ ] LedgerPro opens without a login prompt, update notice or popup within 15 seconds, and its buttons are visible on screen (window maximised).
- [ ] Start the bot **with the statement file**, for example by dragging the statement Excel onto launcher.exe. If you start it without a file, it stops at once (E01).
- [ ] Statement layout: **reference in column A, amount in column B, headers in row 1, data from row 2.** The bot reads the first sheet only.
- [ ] References must be written exactly as LedgerPro has them:
  - No spaces before or after the reference. Bad: `INV1001 ` with a trailing space. Good: `INV1001`.
  - The same format as in LedgerPro. Bad: `1001` stored as a number when LedgerPro has `001001`. Good: `001001` stored as text.
  - A reference that doesn't match exactly is treated as missing and **posted again** (E12).
- [ ] Every row that has a reference must have a numeric amount. Bad: blank, `1,234.00 CR` or `n/a`. Good: `1234.00`. One bad amount stops the whole run before anything is posted (E05).
- [ ] Each reference appears only once in the statement. When a reference appears twice, the bot keeps only the last row and silently ignores the other one (E12).
- [ ] The launcher installed the current release (see section 10).

## 4. During a run

- Hands off the machine. Don't use the mouse or keyboard and don't open other windows. The bot types into **whatever window is in front**. It never checks that LedgerPro is the active window (E13).
- Don't lock the screen or let it sleep. The bot needs to see LedgerPro's buttons.
- Don't close or minimise LedgerPro. Closing LedgerPro **does not stop the bot**, which keeps looking for buttons and typing.
- **To stop the bot:**
  - Move the mouse into the **top-left corner of the screen**. The bot stops at its next click or keystroke.
  - Or end **LedgerBot.exe** in Task Manager (Details tab).
  - A stopped run saves no Reconcile file. The log still lists the lines finished before the stop. Afterwards, check LedgerPro for a half-typed, unsaved entry and cancel it.
- **A run looks stuck** when the mouse hasn't moved for more than a minute. The bot never waits longer than 20 seconds for one button and has no watchdog. If nothing moves for a minute, it has stopped. Check Task Manager for LedgerBot.exe and look for a new Reconcile file.

## 5. Where to look when something goes wrong

| Question | Where to look |
|---|---|
| Did the run finish? | `data\output\`: there is a new `Reconcile_<date>_<time>.xlsx` with the run's time. No new file means the run stopped early (E01-E05, E11). |
| Which lines failed? | The Reconcile file, filter the **Result** column for `Error` or `Mismatch` |
| Which lines did the bot post? | The Reconcile file: Result `Missing` and Note `Posted` |
| Why did one line fail? | The **Note** column. Then `logs\ledger_<date>.log`: search for the reference. Each line reads `<time> INFO <reference> <Result> <Note>`. Search for " Error ", not "ERROR". |
| What was on screen when a button wasn't found? | `logs\notfound_<button>.png`, for example `notfound_save_btn.png`. Only the **latest** failure of each button is kept. |
| What happened if the run stopped with no Reconcile file? | The log lists the lines finished before the stop. The reason the run stopped is **not recorded anywhere** (section 13). |
| Did the bot already retry? | It doesn't retry lines. It only keeps looking for each button for 20 seconds. Nothing in the log shows the search. |
| Which version is running? | No screen shows the version. Check the **Date modified** of LedgerBot.exe (section 10). |

## 6. Statuses

The Reconcile file has no colours. The statuses are values in the **Result** column, with details in **Note**.

| Result | Note | Meaning | What ops does |
|---|---|---|---|
| OK | (empty) | LedgerPro already has this reference with the same amount (difference of 0.01 or less) | nothing |
| Missing | Posted | **The bot posted this entry.** "Missing" means it *was* missing before this run. The bot clicked Save but never checked that LedgerPro saved it. | Spot-check a few in LedgerPro (E09) |
| Mismatch | LedgerPro has <amount> | The reference exists, but LedgerPro has a different amount. **Nothing was posted or changed.** Needs follow-up. | Review it in LedgerPro and correct it by hand (E10) |
| Error | Button new_entry.png not found on screen | The bot couldn't open a new entry. Nothing was typed or posted. | E07 |
| Error | Button save_btn.png not found on screen | The bot typed the entry but couldn't click Save. **The entry is left unsaved and open in LedgerPro.** | E08 |
| (no file) | - | The run stopped before the end | E01-E05, E11 |

## 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 | The bot closes within a second. LedgerPro never opens. | It doesn't. It stops when there's no `logs` folder, or no statement file was given. | Nowhere | System | Ops | Check that the `logs` folder exists next to LedgerBot.exe. Start again by dragging the statement onto launcher.exe. | Both are correct and it still closes. Send the time and the folder listing. |
| E02 | LedgerPro never opens and the bot closes. A brief message says "LedgerPro shortcut not found on the Desktop". | It looks for a shortcut named LedgerPro on your Desktop, then on the Public Desktop | On screen only, for a moment | System | Ops | Put a shortcut named exactly `LedgerPro` on the Desktop and run again | The shortcut is there and it still fails |
| E03 | LedgerPro opens but no export happens. The bot closes and `logs\notfound_export_excel.png` appears. | It looks for the Export to Excel button for 20 seconds (after a 15-second wait for LedgerPro) | The notfound picture only. No Reconcile file. | System | Ops | Open the picture: (1) a login prompt or popup covers LedgerPro → clear it; (2) LedgerPro still loading → run again; (3) scaling is not 100% → fix the display. Run again. | The picture shows the button clearly at 100% and 1920 x 1080. Send the picture and the time. |
| E04 | LedgerPro exports, then the bot closes. No Reconcile file. | It doesn't. It stops when the export isn't saved at the place the bot reads it, or LedgerPro took longer than 10 seconds to save. | Nowhere | System | Ops, then Dev | Run again once, with nothing else open on the machine | It happens again. Send the time and say whether LedgerPro showed a save dialog. |
| E05 | The bot closes after the export and before posting anything. No Reconcile file and no new log lines. | It doesn't. It stops when the statement can't be read: an amount that isn't a number, or a reference with a blank amount. | Nowhere | Business | Ops | Fix the statement (section 3: numeric amounts, reference in A, amount in B, headers in row 1) and run again. Nothing was posted. | The statement is clean and it still stops |
| E06 | Entries appear **twice** in LedgerPro. Lines you know were already in LedgerPro show Missing / Posted. | It doesn't. If LedgerPro's export didn't finish within 10 seconds, the bot may compare against an **older export** and post entries again. | The Reconcile file: Missing / Posted on lines that shouldn't be there | System | Ops, then Dev | Don't run again yet. In LedgerPro, find the duplicate entries and remove them by your normal correction process. | Always: report it so dev can fix the cause. Send the Reconcile file, the log and the time. |
| E07 | Error - "Button new_entry.png not found on screen" | It looks for the New entry button for 20 seconds | The Reconcile file (Result, Note), the log, `logs\notfound_new_entry.png` | System | Ops | Check the picture: (1) popup → clear; (2) scaling → fix. Then run again with the same statement. Lines already posted come back OK; this one gets posted. | Same line fails on two runs in a row |
| E08 | Error - "Button save_btn.png not found on screen". **Often every line after it is Error too.** | It looks for the Save button for 20 seconds after typing the reference and amount | The Reconcile file, the log, `logs\notfound_save_btn.png` | System | **Ops** | **Check LedgerPro first.** An unsaved entry with that reference is probably still open. Cancel it. Make sure no entry with a garbled reference or amount was saved. The bot may have typed later lines into the open form. Then run again. | A wrong entry was saved, or it happens again at 100% scaling. Send the picture, the Reconcile file and the time. |
| E09 | Missing / Posted, but the entry isn't in LedgerPro | It doesn't. The bot treats clicking Save as success and never checks that LedgerPro saved it (for example, when LedgerPro showed a validation popup). | The Reconcile file says Posted, wrongly | System | Ops | Run again with the same statement. A fresh export will show the entry as missing and the bot posts it again. If LedgerPro shows a popup for that entry, enter it by hand. | It's not posted after two runs |
| E10 | Mismatch - "LedgerPro has <amount>" | The reference exists in both, but the amounts differ by more than 0.01 | The Reconcile file, the log | Business | Ops | Check the entry in LedgerPro against the bank statement and correct it by hand. The bot never changes amounts. | Never, unless the amounts actually match. Then it's a reading problem: send the line. |
| E11 | The bot posted entries in LedgerPro but closed at the end. No Reconcile file. | It doesn't. It stops when the `data\output` folder is missing at save time. | The log only (one line per statement line) | System | Ops | Create the `output` folder inside `data`. Use the log to see what was posted. Running again with the same statement is safe: posted entries come back OK. | The folder exists and it still happens |
| E12 | A statement line is missing from the Reconcile file, or a line already in LedgerPro is posted again | It doesn't. Rows with an empty reference are skipped. For a repeated reference, only the last row is kept. A reference written differently from LedgerPro (spaces, number vs text, leading zeros) counts as missing. | Nowhere. Compare row counts. | Business | Ops | Compare the statement row count with the Reconcile row count. Fix the references (section 3) and remove any duplicates posted in LedgerPro. | The references are exactly as in LedgerPro and it still happens |
| E13 | Text typed into another window, or clicks landing in another app | It doesn't. The bot types into whichever window is in front. | Nowhere | System | Ops | Stop the bot (section 4). Undo anything typed into the other app. Check LedgerPro for half-typed entries. Run again hands-off. | It happens with nobody touching the machine |
| E14 | An old build keeps running after a release was announced | It doesn't. The launcher ignores **any** update error (no network, untrusted certificate) and starts the old build without saying so. | Nowhere | System | Dev | Check the LedgerBot.exe date (section 10). If it's older than the release, report it. | Always. Send the machine name and the LedgerBot.exe date. |
| E15 | After a release, launcher.exe closes and the bot never starts | It doesn't. The update download or unzip failed. | Nowhere | System | Dev | Report it. Don't run the bot from this machine. | Always. Send the machine name and the time. |
| E16 | Right after a new build, **every** line is Error "not found", or E03 on every run, at 100% scaling | It doesn't. The new build is missing the button pictures. | The Reconcile file, notfound pictures | System | Dev | Stop using this machine for the bot until dev ships a fixed build | Always. Send one notfound picture and the LedgerBot.exe date. |

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| A button isn't on screen yet | Looks again every second | 20 seconds per button | Export button: the run stops (E03). New entry / Save: the line is marked Error and the bot moves to the next line (E07, E08). |
| LedgerPro is slow to open | Waits | A fixed 15 seconds, no check | Export button not found (E03) |
| The export is slow to save | Waits | A fixed 10 seconds, no check | The run stops (E04), or the bot reads an old export (E06) |
| Anything else | **Nothing.** There's no line retry, no LedgerPro restart, no automatic re-run, no watchdog and no resume. | - | Ops runs again. Running the same statement again is the recovery. Lines posted earlier come back OK, **provided LedgerPro's export is fresh** (E06). |

## 9. Known incidents

The history has no dates, so the version is the only marker. All three fixes are in the 3.2.0 code history.

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| Before 3.2.0 (log of 2026-09-05) | Lines Error "Button save_btn.png not found on screen". Missing entries not posted. | The laptops were at 125% display scaling. The button pictures only match at 100%. | **Still a rule:** keep 100% scaling and 1920 x 1080 on every bot machine (section 3). Handle as E08. | Yes |
| Before 3.2.0 | Two laptops stayed on an old build, with no error | The update server's certificate isn't trusted, and the launcher hides the error | **Still possible:** the code still hides update errors. Check the version after every release (section 10, E14). | Partly. Ops can spot it, but can't see why it failed. |
| Before 3.2.0 | A build that failed every click | The button pictures weren't packed into the exe | Escalate (E16) | No |

## 10. Releases and version check

- **How an update arrives:** every time launcher.exe starts, it checks the update server. If the version differs, it downloads and installs it before starting the bot. You see nothing either way.
- **How to confirm it applied:** no screen shows the version number. In the bot folder, right-click LedgerBot.exe → Properties → **Date modified**. An update sets this to the day it was installed. If the date is older than the release announcement in #rpa-support, the update didn't apply. A leftover `update.zip` in the same folder shows when the last download happened.
- **If the version did not change:** report it in #rpa-support (E14) with the machine name and the date. Don't keep running an old build if the release fixed something you rely on.

## 11. Escalating to dev

Post in **#rpa-support** (Teams). Send:
- the exception ID from section 7 and the date and time of the run;
- the machine name and the LedgerBot.exe Date modified;
- the files, **attached** rather than pasted:
  - `logs\ledger_<date>.log`
  - any `logs\notfound_<button>.png`
  - the `data\output\Reconcile_<date>_<time>.xlsx` from that run
- a screenshot of LedgerPro if it shows a message.

Never send:
- passwords or the `.env` file;
- statement rows, references, amounts or payee names typed into the chat message.

## 12. Failure-class check

- **F1** (missing prerequisite): section 3 (shortcut, `logs` and `data\output` folders, display) and E01, E02, E11, E16. Silent crashes are item 5 in section 13.
- **F2** (wrong window or focus): section 4 hands-off rule and E13. The missing focus check is item 12 in section 13.
- **F3** (target slower or different): E03, E04, E07, E08, the section 8 waits, and the 100% / 1920 x 1080 rule in section 3. Fixed sleeps are item 6 and hard-coded scaling is item 13 in section 13.
- **F4** (input read differently): section 3 input rules and E05, E12. Parsing gaps are item 10 in section 13.
- **F5** (done when nothing was done): E09, because Posted is written without confirmation. That is item 7 in section 13.
- **F6** (action happened but not confirmed): E08 (unsaved form left open) and E06 (stale export reposts). These are items 6 and 8 in section 13.
- **F7** (business exception shown as success): Mismatch is shown as needing follow-up in section 6. Result "Missing" really means posted, which is item 9 in section 13. There are no colours.
- **F8** (endless re-runs or watchdog): not applicable. There is no auto-rerun and no watchdog, and every wait is capped at 20 seconds. Section 4 gives the "stuck" sign.
- **F9** (stopping the wrong way): section 4. Closing LedgerPro doesn't stop the bot. Use the mouse corner or Task Manager.
- **F10** (one stuck item blocks the queue): there are no batches or locks. The nearest case is one failed Save that cascades into the following lines (E08).
- **F11** (cause hidden from ops): section 5 points only at the output and log folders. Hidden causes are items 4, 5, 10 and 11 in section 13.
- **F12** (update didn't arrive, or old build undid new): section 10, E14 and E15. The missing version display is item 3 and silent update failure is item 1 in section 13. Nothing shared is rewritten on start, so mixed versions don't corrupt each other.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | The launcher catches every exception and returns None, so an SSL or network failure is silent. The "fix" commit f3a0b30 only added a comment. | Machines stay on old builds without anyone knowing (E14) | `launcher.py:16-20`, `launcher.py:35` |
| 2 | The update uses `!=` for the version (it will downgrade), has no hash or signature check, has no rollback, and doesn't catch download or unzip errors | A bad or old zip breaks or downgrades the machine (E15) | `launcher.py:25-29` |
| 3 | The version isn't shown anywhere. The comment claims a window title "LedgerBot v3.2.0", but no window exists. | Ops can't confirm a release applied | `app.py:15` |
| 4 | The spec has `datas` commented out. The fix in commit 9f03d5a isn't in effect in this tree, and there's no spec for launcher.exe. | The next build may ship without button pictures (E16) | `ledgerbot.spec:2` |
| 5 | `main` isn't wrapped in a try/except, so run-level crashes are never logged and the console closes | E01-E05 and E11 leave no reason anywhere | `app.py:100-101` |
| 6 | Fixed sleeps of 15 s and 10 s. The bot never checks that the export file is new, and never deletes the old one before exporting. | A slow export makes the bot reconcile against old data and **post duplicates** (E06) | `app.py:76-79` |
| 7 | "Posted" is written as soon as Save is clicked, with no check in LedgerPro | Entries LedgerPro didn't save show as Posted (E09) | `app.py:70`, `app.py:89-90` |
| 8 | When Save isn't found, the typed entry is left open. There's no cancel or escape, and later lines type into the open form. | Error cascade and possibly garbled saved entries (E08) | `app.py:65-70`, `app.py:91-92` |
| 9 | A posted line is written as Result "Missing". The README says "Missing" is a status of its own. | Ops reads "Missing" as "not done" | `app.py:58`, `app.py:87-90`, `README.md:6` |
| 10 | Statement parsing: `str()` without trimming (`1001.0` vs `1001`), a duplicate reference overwrites silently, blank or text amounts crash the run, and blank references are skipped | Duplicate postings, silently lost lines, whole-run crashes (E05, E12) | `app.py:52`, `app.py:81` |
| 11 | The Reconcile file is written only at the end, and `data/output` and `logs` aren't created if missing | A crash loses every result even though entries were posted (E01, E11) | `app.py:24`, `app.py:96` |
| 12 | There's no check that LedgerPro is the active window before typing | Keystrokes go into other apps (E13) | `app.py:66-69` |
| 13 | The button pictures only match at 100% / 1920 x 1080. The 125% "fix" was recapturing the pictures, not a code change. | Any display change breaks every run | `app.py:20`, `app.py:102` |
| 14 | The notfound screenshot is named by button only and overwritten each time. Line errors are logged at INFO. The run summary is printed to a console nobody sees. | Ops can't match a screenshot to a line, and searching for "ERROR" finds nothing | `app.py:45`, `app.py:95`, `app.py:97` |
| 15 | `.env` is tracked in git although no code reads it. `logs/ledger_20260905.log` is committed and its last line holds a payee name (written by an older build). | Possible secrets and customer data in the repo and in shipped zips | `.env`, `logs/ledger_20260905.log:3` |