# 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 checks the daily bank statement against LedgerPro, the desktop accounting app. You give it the bank statement Excel when you start it. It opens LedgerPro, exports LedgerPro's entries to Excel and compares each statement line with them by reference and amount. Any statement line that is not in LedgerPro gets posted there by the bot: it clicks **New entry**, types the reference and amount, and clicks **Save**. At the end it writes one result file, `Reconcile_<date>_<time>.xlsx`, in the output folder. Each statement line gets a Result there: OK, Missing, Mismatch or Error. The only app it drives is **LedgerPro**. It runs once per statement, whenever ops starts it.

## 2. How it works

```
launcher.exe (what you start, with the statement file)
   ├─ checks for a newer LedgerBot build, installs it if found
   └─ starts → LedgerBot.exe ──drives (mouse + keyboard)──> LedgerPro
                    │                                       (do not touch while it runs)
                    ├─ reads → your bank statement Excel
                    ├─ reads → LedgerPro's export (data\ledger_export.xlsx)
                    └─ writes → output folder: Reconcile_<date>_<time>.xlsx
```

- **launcher.exe** checks the update server, installs a new version if there is one, then starts LedgerBot. It shows nothing on screen.
- **LedgerBot.exe** does the work. It has no window of its own, no buttons and no progress display. It works by finding LedgerPro's buttons on the screen *by their picture* and clicking them.
- **LedgerPro** is the accounting app. While the bot runs, the mouse and keyboard belong to the bot.
- **Output folder** (`data\output`) gets one result file per run. It is the only record ops can open.

**One run, step by step:**
1. The bot opens LedgerPro from its Desktop shortcut and waits 15 seconds.
2. It clicks LedgerPro's **Export to Excel** button and waits 10 seconds.
3. It reads LedgerPro's exported entries and your statement (column A = reference, column B = amount, from row 2).
4. It compares each statement line with LedgerPro: OK, Missing or Mismatch.
5. For each Missing line it posts the entry: New entry → type reference → Tab → type amount → Save.
6. **Only at the very end** it saves the result file to the output folder. If the run stops earlier, there is no result file at all.

## 3. Before a run

- [ ] **Display: Scale 100% and resolution 1920 x 1080** (Windows Settings → System → Display). Check this again after docking the laptop, adding a monitor or a Windows update. At any other setting the bot cannot find LedgerPro's buttons (E03, E07, E08).
- [ ] The **LedgerPro** shortcut is on your Desktop or on the Public Desktop, and its name is exactly `LedgerPro`. Without it nothing happens (E02).
- [ ] LedgerPro opens straight to its main screen with **no sign-in prompt and no popup**. The bot does not sign in and does not close popups.
- [ ] LedgerPro is **closed** before you start; the bot opens it itself.
- [ ] The folders `logs`, `data` and `data\output` exist next to `LedgerBot.exe`. The bot does not create them. If one is missing, the run fails (E01, E05). Ask dev/IT to set them up once; ops does not need to open `logs`.
- [ ] Statement Excel rules:
  - The data is on the **first sheet** (the one that opens by default). Row 1 is a header; data starts on row 2.
  - Column A = reference, column B = amount. **Every row with a reference must have a number in column B**: no text, no blanks, no "1,234.00 CR". Otherwise the whole run fails with no output (E04).
  - **Each reference only once.** If a reference appears twice, the bot silently keeps only the last line (E10).
  - Type references **exactly as LedgerPro shows them**, and format column A as Text. Bad: `123` when LedgerPro has `00123` (Excel drops the zeros), or `INV-55 ` with a trailing space. Good: `00123`, `INV-55`. A reference that doesn't match exactly is treated as Missing and **posted again** (E15).
- [ ] Version: there is no place where ops can see the version today (see section 10).

## 4. During a run

- **Hands off the mouse and keyboard.** The bot types into whatever window is in front. If you click into another window (email, chat), the reference and amount get typed there and LedgerPro is not updated (E12).
- Don't cover, move or minimise LedgerPro, and don't open other windows on top of it.
- **Don't move the mouse into the top-left corner of the screen.** That is the bot's emergency stop: the run ends at once, with no result file.
- **To stop the bot:** move the mouse pointer into the top-left corner of the screen, or end `LedgerBot.exe` in Task Manager. **Closing LedgerPro does not stop it**; the bot keeps clicking and typing. After a stop, there is no result file. Check LedgerPro by hand for entries already posted before you re-run (E05).
- A run looks stuck when the mouse hasn't moved for more than a minute. The bot waits at most **20 seconds** for any button, so a real run never sits still that long. If nothing has happened for a few minutes, the run has ended, maybe without a result file. Check the output folder.

## 5. Where to look when something goes wrong

| Question | Where to look |
|---|---|
| Did the run finish? | Output folder `data\output`: a new `Reconcile_<date>_<time>.xlsx` with the time of your run. **No new file = the run did not finish** (E01-E05). |
| Which lines failed? | The Reconcile file → filter the **Result** column for `Error` and `Mismatch`. |
| Why did one line fail? | The **Note** column on the same row. |
| Was the entry really posted? | LedgerPro itself: search for the reference. The bot does not check after Save. |
| Did the bot already retry? | It never retries a line. For each button it keeps looking for 20 seconds; after that the line is Error. |
| Which version is running? | Ops cannot see it today (see section 10 and *Fix before handover*). |
| Why did a run end with no result file? | Nothing ops can open says why. Raise a ticket (section 11). |

## 6. Statuses

The Reconcile file is plain Excel, so there are no colours.

| Result | Note | Meaning | What ops does |
|---|---|---|---|
| OK | (empty) | Reference and amount match LedgerPro (within 0.01). | Nothing. |
| Missing | Posted | The line was not in LedgerPro and **the bot posted it**. "Missing" here means "was missing, now posted". The bot clicked Save but **did not check the save worked**. | Spot-check a few in LedgerPro. Nothing else if they are there. |
| Mismatch | LedgerPro has `<amount>` | The reference exists in LedgerPro with a different amount. **The bot changes nothing.** | Correct it by hand in LedgerPro or with Finance (E09). |
| Error | Button new_entry.png not found on screen | The line was Missing, but the bot could not find LedgerPro's **New entry** button. Probably not posted. | E07 |
| Error | Button save_btn.png not found on screen | The bot typed the entry but could not find **Save**. **It may or may not be saved.** | E08: check in LedgerPro before any re-run. |
| (no file) | - | The run stopped before the end. **Nothing is recorded for any line**, even lines already posted. | E01-E05 |

Not reported at all: entries that are in LedgerPro but **not** on the statement. The bot ignores them.

## 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 | You start the bot and **nothing happens at all**: LedgerPro doesn't open, no result file | The bot stops before it begins: no statement file was given, or the `logs` folder is missing next to the exe | Nowhere ops can open | System | Ops, then Dev | Start it again with the statement file (for example, drag the statement Excel onto `launcher.exe`). | It still does nothing → ticket: laptop name, time, "E01". |
| E02 | Nothing opens; no result file | It looks for a shortcut named `LedgerPro` on your Desktop and the Public Desktop; if none, it stops | Nowhere ops can open | System | Ops | Put the LedgerPro shortcut back on the Desktop with the exact name `LedgerPro`, then re-run. | The shortcut is there and it still fails → ticket: laptop name, time. |
| E03 | LedgerPro opens, **nothing gets clicked**, the run ends with no result file | It looks for the **Export to Excel** button picture for 20 s; if it never matches, the run stops. Nothing was posted. | A screenshot in the dev log folder (ops can't open it) | System | Ops, then Dev | Check: Display scale 100% and 1920 x 1080; LedgerPro on its main screen with no sign-in or popup; nothing covering it. Fix that, then re-run once. | Fails again with the settings right, **or** it happens on every laptop right after an update (broken build) → ticket: laptop name, time, screenshot of the screen. |
| E04 | LedgerPro opens, Export is clicked, then **the run ends with no result file** and nothing is posted | It could not read the data: an amount that is not a number in your statement or LedgerPro's export, or the export file is not where it expects it | Nowhere ops can open | Business or System | Ops, then Dev | Check that every row of your statement has a plain number in column B, fix it, then re-run. | The statement is clean and it still fails → ticket: laptop name, time, the statement file (send it through the ticket, not chat). |
| E05 | Some entries were posted in LedgerPro but **there is no result file** | The run stopped part-way: someone stopped it, the mouse hit the top-left corner, a button error the bot can't handle, or the `data\output` folder is missing (then it fails at the very end, after posting everything) | Nowhere. The posted entries are in LedgerPro only. | System | Ops, then Dev | **Don't re-run straight away.** In LedgerPro, look up the statement references to see which were posted. Check `data\output` exists. Then re-run once: the bot re-exports, so posted lines should come back OK. | It happens twice → ticket: laptop name, time, which references were posted. |
| E07 | Result **Error**, note "Button new_entry.png not found on screen" | It looks for LedgerPro's **New entry** button for 20 s; if it never matches, it marks the line Error and goes to the next line | Reconcile file, Result + Note | System | Ops | Check display scale/resolution. Look the reference up in LedgerPro; if it isn't there, re-run (only Missing lines get posted). | Every Missing line errors with the settings right → ticket: Reconcile file, laptop name. |
| E08 | Result **Error**, note "Button save_btn.png not found on screen" | It typed the reference and amount, then looked for **Save** for 20 s and didn't find it. The half-filled form is **left open**, and the **next** line is typed on top of it. | Reconcile file, Result + Note | System | **Ops** | **Check in LedgerPro first**: is this reference saved, and is the amount right? Also check the **next** line's entry. Delete or fix any wrong or half-done entry by hand. Only then re-run. Re-running without checking can post it twice. | Several lines in one run → ticket: Reconcile file, laptop name, time. |
| E09 | Result **Mismatch**, note "LedgerPro has 123.45" | The reference is in LedgerPro but the amounts differ by more than 0.01 | Reconcile file | Business | Ops | Find out which amount is right (statement or LedgerPro) and correct it by hand. The bot never changes amounts. | Never; it is a business task. |
| E10 | A statement line has **no row** in the Reconcile file; fewer rows than the statement | The same reference appears twice in the statement (or in LedgerPro); the bot silently keeps only the last one | Nowhere; count the rows to notice | Business | Ops | Before the run, remove or merge duplicate references. After the run, compare row counts: statement vs Reconcile file. | - |
| E11 | **The same entry posted twice** in LedgerPro | Nothing detects it. Causes: re-running after E08 without checking, or LedgerPro's export not saving fresh, so the bot compares against an old export | Nowhere | System | Ops, then Dev | Delete the duplicate in LedgerPro by hand. | It happens with no E08 before it (stale export) → ticket: Reconcile file, time, references. |
| E12 | Reference and amount **typed into another window** (email, chat); entries missing in LedgerPro, maybe marked Missing/Posted | The bot types into whatever window is in front; it never checks it is LedgerPro | Nowhere; the Reconcile file may still say Posted | System | Ops | Check those references in LedgerPro and post them by hand, or re-run. Hands off during runs (section 4). | - |
| E13 | After a release, **the laptop still runs the old version** | The launcher couldn't reach the update server (offline, or the server's certificate not trusted) and starts the old version without saying so | Nowhere | System | Dev | Raise a ticket naming the laptop. | Always, once dev announces a release. |
| E14 | After a release, **double-clicking launcher.exe does nothing**; the bot never starts | The update was found but the download or unzip failed; the launcher stops | Nowhere | System | Dev | Raise a ticket: laptop name, time. | Always. |
| E15 | A line that **is** in LedgerPro shows **Missing / Posted**, so there is now a duplicate | The reference doesn't match LedgerPro character for character (lost leading zeros, extra space, different case) | Reconcile file shows Posted | Business | Ops | Delete the duplicate in LedgerPro. Fix the reference in the statement (column A as Text, exact spelling). | - |

(E06 is not used.)

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| A LedgerPro button is not on the screen yet | Looks again every second | 20 s per button | Export button: the run stops, no result file (E03). New entry / Save: the line is Error, next line (E07, E08). |
| LedgerPro slow to open | Fixed wait, no check | 15 s | Goes on regardless; usually ends as E03 |
| Export slow to save | Fixed wait, no check | 10 s | Goes on regardless; may read an old export (E11) |
| Update server unreachable | Starts the current version | 10 s | Old version keeps running (E13) |

There are **no** retries per line, no restarts and no resume. A failed line is retried only when ops re-runs the whole statement. Lines already posted then come back OK, as long as LedgerPro's export is fresh.

## 9. Known incidents

All three are recorded in the history as fixed on 2026-10-23. In the code, though, each "fix" is only a note; the bot's behaviour is unchanged (see section 13).

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| 2026-10, 3.2.0 | Lines Error "Button save_btn.png not found on screen" on some laptops | Laptops at 125% display scaling; the button pictures were taken at 100% | **Keep 100% scale and 1920 x 1080** (section 3). Check each Error line in LedgerPro (E08). | Partly |
| 2026-10, 3.2.0 | Two laptops stayed on the old version, with no message | Update server's certificate not trusted; the launcher hid the error | Raise a ticket after every release if a laptop didn't update (E13). Ops can't confirm the version yet. | Partly |
| 2026-10, 3.2.0 | Exe build couldn't find any button (every run fails at Export) | The button pictures were left out of the exe build | Dev rebuild. Ops: E03 on every laptop right after an update → ticket. | No |

## 10. Releases and version check

- **How an update arrives:** `launcher.exe` checks the update server every time you start it. If there is a different version, it downloads and installs it next to the exe, then starts the bot. It shows nothing on screen.
- **How to confirm it applied:** today **ops cannot see the version**. The bot has no window and no title bar, and neither the log nor the result file records the version. Ask dev to confirm per laptop.
- **If the version did not change:** raise a ticket with the laptop name (E13). Don't copy files between laptops yourself.
- Laptops on different versions don't break each other; the bot shares nothing between machines.

## 11. Escalating to dev

Raise a ticket in the **RPA Support** queue. Send:
- the exception ID from section 7 (for example "E08"),
- the laptop name,
- the date and time you started the run,
- the statement file name,
- the Reconcile file from `data\output`, if there is one,
- a screenshot of the screen if the bot stopped on something.

Dev collects the log and the "button not found" screenshot from the laptop themselves.
Never send: passwords, the bot's settings file, or bank or customer data in chat. Attach files to the ticket only.

## 12. Failure-class check

- F1 covered in section 3 (shortcut, folders, no sign-in prompt), E01, E02, E03 (exe build missing pictures), and *Fix before handover* 3, 8.
- F2 covered in section 4 (hands off, don't cover LedgerPro), E12, and *Fix before handover* 6.
- F3 covered in section 3 (100% scale, 1920 x 1080), E03, E07, E08, section 8 (20 s / 15 s / 10 s limits), and *Fix before handover* 7.
- F4 covered in section 3 (statement rules with examples), E04, E10, E15, and *Fix before handover* 9.
- F5 covered in section 6 (Missing/Posted not confirmed) and *Fix before handover* 4.
- F6 covered in E08 (check LedgerPro before re-running), E11, and *Fix before handover* 4, 5.
- F7 covered in section 6: no business exception is shown as success, but "Missing" is the label for successfully posted lines, which is misleading. *Fix before handover* 10.
- F8 not applicable: the bot has no auto-rerun loop and no watchdog; each button wait ends after 20 s.
- F9 covered in section 4 (how to stop; closing LedgerPro doesn't stop it) and *Fix before handover* 6.
- F10 not applicable: there are no batches, locks or completion gates. Each run is independent and nothing blocks the next one. The "was run" marker file the bot writes is never read.
- F11 covered in section 5 (only the Reconcile file is visible to ops), E01-E05, and *Fix before handover* 1, 2.
- F12 covered in section 10, E13, E14, and *Fix before handover* 11, 12.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | Crashes (no statement argument, missing shortcut, Export not found, bad amount, missing folder, failsafe) are not logged and leave no result file. Results are saved only at the end. | Ops sees "no file" with no reason; lines already posted aren't recorded anywhere | `app.py:73-97` (single `out.save` at `:96`) |
| 2 | The per-line log, the "not found" screenshots and the run summary (printed to stdout, which the launcher never captures) all sit where ops has no access. The screenshot has one fixed name per button and is overwritten. | Ops has only the Reconcile file; the cause stays hidden | `app.py:24`, `:45`, `:97` |
| 3 | `logs/`, `data/` and `data/output/` are never created; a missing `logs/` crashes both exes at import | Fresh install fails, or fails after all posting is done | `app.py:24`, `:45`, `:96`; `launcher.py:9` |
| 4 | "Posted" is written after clicking Save, with no check that LedgerPro saved | A Missing/Posted line may not be in LedgerPro | `app.py:65-70`, `:90` |
| 5 | A Save miss leaves the typed form open; the next line types on top of it | One Error can corrupt the next entry | `app.py:65-70`, `:91-92` |
| 6 | No window focus or "is LedgerPro in front" check before typing; no Stop button; closing LedgerPro doesn't stop the bot | Keystrokes land in other windows | `app.py:66-69` |
| 7 | Fixed sleeps (15 s / 10 s) instead of waiting for LedgerPro and the export; nothing checks the export file is fresh or where LedgerPro saves it | Old export means double posting (E11) | `app.py:76-79`, docstring `:50` |
| 8 | Scaling fix is a comment only: no DPI/resolution check at start. Exe build spec is all comments (`datas` commented out). Only `RuntimeError` is caught; newer pyautogui raises its own not-found error and `requirements.txt` is unpinned. | Any scale change or new build breaks every run | `app.py:20`, `:40`, `:91`, `:102`; `ledgerbot.spec:1-3`; `requirements.txt` |
| 9 | Duplicate references silently overwritten; references not trimmed or normalised; non-numeric amount crashes the run | Lines vanish, or are posted twice | `app.py:52`, `:81` |
| 10 | Result "Missing" is kept for lines that were successfully posted; a status like "Posted" would read correctly. The note "Not in LedgerPro - posting" is never shown. | Ops reads done lines as problems | `app.py:58`, `:87-92` |
| 11 | Launcher swallows every update error (incl. the self-signed certificate) with no log; download/unzip unprotected; no checksum; `!=` accepts downgrades; extracts over the running folder | Laptops silently stay old, or the launcher crashes | `launcher.py:15-30` (fix commit only added comment `:35`) |
| 12 | The version is not shown anywhere ops can see (the comment says window title, but the bot has no window); not in the log or the result file | Ops can't confirm an update | `app.py:15` |
| 13 | Two runs in the same minute overwrite each other's result file | A result file is lost | `app.py:96` |
| 14 | `.env` holding LedgerPro credentials and a log file containing business data are committed to git; `.env` is never read by the code | Credential and data exposure | `.env`, `logs/ledger_20260905.log` |
| 15 | The log note can carry counterparty names (seen in the committed log, from an older build) | Business data in logs | `logs/ledger_20260905.log` |