# 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 compares the day's bank statement Excel with the LedgerPro desktop accounting app. Every reference in the statement that LedgerPro does not have is typed into LedgerPro and saved. References whose amount differs are only reported, never changed. It runs once per statement file, when an operator starts it. Input: one bank statement Excel file. Output: one Excel report, `data/output/Reconcile_<date>_<time>.xlsx`, with one row per statement reference. It drives one desktop app: **LedgerPro**, by finding its buttons on the screen from pictures and clicking them.

## 2. How it works

```
launcher.exe (what you start)
   └─ checks for an update, then starts → LedgerBot.exe ──clicks and types into──> LedgerPro
                                              │                                   (do not touch while it runs)
                                              ├─ reads  → the bank statement Excel you gave it
                                              ├─ reads  → LedgerPro's Excel export (data folder)
                                              ├─ writes → data/output/Reconcile_<date>_<time>.xlsx  (only at the very end)
                                              └─ writes → logs/ledger_<date>.log, and a screenshot when a button is not found
```

- **launcher.exe** looks for a newer LedgerBot version, installs it if found, starts LedgerBot.exe and closes itself.
- **LedgerBot.exe** is the bot. It has no window of its own; at most a black console window, which prints a one-line summary of counts at the end.
- **LedgerPro** is the accounting app. The bot opens it from the Desktop shortcut and moves the mouse and keyboard in it.
- **The report** in the output folder is the only record ops can open.
- **The log and screenshots** are in the bot's `logs` folder. Ops cannot open it; the dev team reads it.

**One run, step by step:**
1. The launcher checks for an update and starts the bot with the statement file.
2. The bot opens LedgerPro from the "LedgerPro" shortcut on the Desktop, then waits a fixed 15 seconds.
3. It clicks LedgerPro's "Export Excel" button, then waits a fixed 10 seconds for the export file.
4. It reads the export and the statement, and compares them reference by reference.
5. For each reference LedgerPro does not have, it clicks "New entry", types the reference, presses Tab, types the amount and clicks "Save".
6. After the **last** row it writes the report to the output folder. Nothing is written there before that.

## 3. Before a run

- [ ] The "LedgerPro" shortcut is on your Desktop or on the Public Desktop, named exactly **LedgerPro**. Otherwise the bot closes at once with no report (E01).
- [ ] Windows display scaling is **100%** and the screen is **1920 x 1080**. The button pictures were captured at that setting; at 125% the bot cannot find the buttons (E08, E09).
- [ ] Next to LedgerBot.exe there is a `logs` folder and a `data\output` folder. The bot does not create them. Without `logs` it closes at once (E02); without `data\output` it posts every entry and then fails to write the report (E12). Ask dev to confirm both at install.
- [ ] LedgerPro opens to the screen that shows the "Export Excel" button, without a login or a popup in front of it. The bot does not sign in and does not close popups.
- [ ] Statement Excel rules:
  - The data is on the sheet that was **selected when the file was last saved**. The bot reads only that sheet.
  - Row 1 is a header. From row 2: **column A = reference, column B = amount**. Other columns are ignored.
  - Amount is a plain number. Bad: `₹ 410.00`, `410,00`, `n/a`. Good: `410.00`. One bad amount stops the whole run with no report (E06).
  - Each reference appears **once**. If it appears twice, only the last row is used and the other is silently dropped (E07).
  - Type references exactly as LedgerPro stores them, and as text. Bad: `1001` stored as a number when LedgerPro has `TX-1001`. A reference written differently counts as "not in LedgerPro" and is **posted again** (E07).
  - A row with an empty column A is skipped.
- [ ] The update check has run and the version is the one dev announced (section 10).

## 4. During a run

- **Hands off the machine.** Don't move the mouse or type. The bot clicks wherever it sees a matching button on the screen and types into whatever has focus, so a moved window or a click from you sends its typing into the wrong place.
- Keep only LedgerPro open. Close other windows that could show a similar "New entry" or "Save" button, and don't let anything cover LedgerPro.
- Moving the mouse into a **corner of the screen** stops the bot immediately (a built-in safety switch). Don't do this by accident.
- **To stop the bot:** move the mouse into the top-left corner of the screen, or end **LedgerBot.exe** in Task Manager. Closing the launcher does not stop it; closing LedgerPro does not stop it either - it keeps clicking for each remaining row. Any way you stop it, **no report is written**, and entries already saved stay in LedgerPro (E13).
- A run looks stuck when the mouse has not moved for more than about 1 minute. There is no watchdog: the bot never gives up on its own except by failing a button search (20 seconds per button). If nothing moves for 2 minutes, stop it as above and raise a ticket.

## 5. Where to look when something goes wrong

| Question | Where to look |
|---|---|
| Did the run finish? | Output folder: a new `Reconcile_<date>_<time>.xlsx` with the run's start date and time. No new file = the run did not finish (E01-E06, E12, E13). The console window, if shown, prints a summary of counts at the very end. |
| Which items failed? | The report, **Result** column = `Error` (failed) or `Mismatch` (amounts differ). |
| Why did one item fail? | The report, **Note** column. For anything deeper, raise a ticket - the log and screenshots are in a folder ops cannot open. |
| Did the bot already retry? | It does not retry. Each button is searched for up to 20 seconds, once (section 8). |
| Which version is running? | Ops cannot see it today (section 10). Ask in the ticket. |
| What was actually posted? | **LedgerPro itself.** The report says `Posted` when the bot clicked Save, not when LedgerPro confirmed it (E10). |

## 6. Statuses

The report is plain Excel with no colours. Columns: Reference, Amount, Result, Note.

| Result - Note | Colour | Meaning | What ops does |
|---|---|---|---|
| `OK` - (empty) | none | LedgerPro has this reference with the same amount (within 0.01). | nothing |
| `Missing` - `Posted` | none | LedgerPro did not have it, **and the bot typed it in and clicked Save**. Despite the word "Missing", this is the row the bot posted. Save was not confirmed. | Spot-check a few in LedgerPro (E10). |
| `Mismatch` - `LedgerPro has <amount>` | none | LedgerPro has the reference with a different amount. **The bot changed nothing.** | Needs follow-up: correct it by hand in LedgerPro, or with the finance team (E11). |
| `Error` - `Button new_entry.png not found on screen` | none | The bot could not open a new entry. Not posted. | E08 |
| `Error` - `Button save_btn.png not found on screen` | none | The bot typed the entry but could not click Save. Probably not saved; the entry form may still be open. | **Check LedgerPro first** (E09). |
| `Missing` - `Not in LedgerPro - posting` | none | Never appears in a finished report: the bot always replaces it with `Posted` or turns the row into `Error`. | If you see it, raise a ticket. |
| (no report at all) | - | The run stopped before the end. | E01-E06, E12, E13 |

References that are in LedgerPro but not in the statement are **not listed anywhere**. The bot ignores them.

## 7. Exception catalogue

"Raise a ticket" always means a ticket in the RPA Support queue with the items in section 11.

| ID | What you see | How the bot identifies it | Where it is recorded | Type | Who acts | What to do | Escalate when |
|---|---|---|---|---|---|---|---|
| E01 | Bot closes at once, LedgerPro never opens, no report | It looks for a "LedgerPro" shortcut on your Desktop and the Public Desktop; if neither has one, it stops | Console window only (message "LedgerPro shortcut not found on the Desktop"); not in the log | System | Ops | Put a shortcut named exactly LedgerPro on the Desktop, run again | The shortcut is there and it still happens. Send: time, machine name. |
| E02 | Bot closes at once, nothing happens, no report | It cannot open its log file because the `logs` folder next to it is missing | Nowhere ops can see | System | Dev | Raise a ticket | Always. Send: time, machine name. |
| E03 | LedgerPro opens, nothing is clicked, bot ends, no report | It looks for the "Export Excel" button for 20 seconds; if it is not on screen, it saves a screenshot and stops | Screenshot in the logs folder; console message "Button export_excel.png not found on screen" | System | Ops, then Dev | Check: display scaling 100%, LedgerPro fully open with no popup or login in front, nothing covering it. Run again. | It happens again. Send: time, machine name, and say the screenshot is there. |
| E04 | LedgerPro export runs, then the bot ends, no report | It reads LedgerPro's export file from its data folder after a fixed 10 s; if the file is not there or not readable, it stops | Nowhere ops can see | System | Dev | Raise a ticket. Do not re-run repeatedly. | Always. Send: time, machine name. |
| E05 | Entries posted twice in LedgerPro; the report shows `Posted` for references LedgerPro already had | **Not identified.** If LedgerPro's export did not refresh the export file in 10 s, the bot compares against the previous run's file and treats today's existing entries as missing | Nowhere | System | Ops, then Dev | After every run, check that the number of `Posted` rows looks right for the day. If it is suspiciously high, check those references in LedgerPro for duplicates and remove them by hand. | Any duplicate found. Send: report file, time, machine name. |
| E06 | LedgerPro opens and exports, then the bot ends, no report, no entries posted | It cannot read the statement: wrong file, or an amount cell that is not a number | Console window only | Business | Ops | Check the statement against the rules in section 3 (plain numbers in column B, data on the selected sheet), fix, run again | The file follows the rules and it still happens. Send: time, machine name, statement attached to the ticket (not in chat). |
| E07 | A statement line missing from the report, or a reference posted although LedgerPro already had it under another spelling | **Not identified.** Duplicate references keep only the last row; references are compared as exact text | Nowhere | Business | Ops | Remove duplicates and write references exactly as in LedgerPro before the run. If a duplicate entry was posted, delete it by hand in LedgerPro. | - |
| E08 | Row `Error` - "Button new_entry.png not found on screen" | It looks for LedgerPro's "New entry" button for 20 seconds after each row; not found = Error, next row | Report, Result and Note columns; screenshot in logs folder | System | Ops | Not posted. Check display scaling (100%) and that LedgerPro is still open and in front. Run again - the next run posts it if it is still missing. | Several rows in one run, or again on the next run. Send: report file, time. |
| E09 | Row `Error` - "Button save_btn.png not found on screen" | It typed the reference and amount, then looked for "Save" for 20 seconds; not found = Error, next row | Report, Result and Note columns; screenshot in logs folder | System | **Ops** | **Check LedgerPro first.** The entry form may still be open with this row's data, and the following rows may have been typed into it. Close or cancel any open entry form, confirm whether this reference exists in LedgerPro, then run again. Expect the rows after it to also fail. | Rows after it show `Posted` but are not in LedgerPro. Send: report file, time. |
| E10 | Row `Missing` - `Posted`, but the entry is not in LedgerPro (or has a wrong amount) | **Not identified.** The bot writes `Posted` right after clicking Save; it does not wait for LedgerPro to confirm | Report says `Posted` | System | Ops | Spot-check posted rows in LedgerPro. A missing one is posted by the next run; a wrong amount must be fixed by hand. | More than one per run. Send: report file, references concerned (in the ticket, not chat). |
| E11 | Row `Mismatch` - "LedgerPro has <amount>" | The reference exists in LedgerPro but the amounts differ by more than 0.01 | Report, Result and Note columns | Business | Ops | Decide which amount is right with finance and correct it by hand. The bot never changes existing entries and will report it again until fixed. | - |
| E12 | The bot clicks through every row, then ends with **no report** | It writes the report to `data\output` only at the end; if the folder is missing, it fails there | Nowhere ops can see | System | Dev | Entries **were** posted. Do not re-run until dev creates the folder. Check today's entries in LedgerPro. | Always. Send: time, machine name. |
| E13 | Run stopped midway (you stopped it, the PC locked, or it crashed); no report | Any problem other than a row's button search stops the whole run | Nowhere ops can see | System | Ops | Entries saved before the stop stay in LedgerPro. Check the last entries in LedgerPro, close any open entry form, then run again with the same statement. | It stops again at the same point. Send: time, machine name. |
| E14 | A new version was announced but the bot behaves as before | The launcher hides every update error (no internet, untrusted certificate) and silently runs the old version | Nowhere | System | Dev | Raise a ticket; ops cannot check the version (section 10) | Always. Send: machine name, date of the announced update. |

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| A button is not on screen yet | Looks again every second | 20 seconds per button | "New entry" or "Save": row = Error, next row. "Export Excel": whole run stops, no report. |
| LedgerPro slow to open | Waits a fixed time, does not check | 15 seconds | Continues anyway; usually ends in E03 |
| Export slow | Waits a fixed time, does not check | 10 seconds | Continues anyway; ends in E04 or silently in E05 |
| Anything else | Nothing. No retries, no restarts, no resume. | - | Run stops, no report |

Ops never has to wait for a hidden retry: if the mouse has stopped for 2 minutes, nothing more will happen.

## 9. Known incidents

From the repository history. Each fix below is recorded in the history, but the change kept in the code is only a note, so **treat every fix as unconfirmed** until dev confirms it.

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| Before 3.2.0 | The bot never found its buttons (assets missing in the built exe) | The packaging file did not include the button pictures | Raise a ticket if every run ends at E03 straight after an update | No |
| Before 3.2.0 | Clicks missed "Save" on laptops set to 125% display scaling | Button pictures captured at 100% | Keep display scaling at **100%** (section 3) | Yes |
| Before 3.2.0 | Two laptops never received updates | The launcher hid the certificate error from the update server | Still possible today (E14). Raise a ticket when an update does not arrive. | Partly |
| 2026-09-05 | One row `Error` "Button save_btn.png not found on screen" in the same run as OK and Mismatch rows | Save button not found within 20 s | Follow E09 | Yes |

## 10. Releases and version check

- How an update arrives: every time you start **launcher.exe**, it asks the update server for the latest version and, if different, downloads and installs it over the bot's folder before starting the bot.
- How to confirm it applied: **ops cannot today.** The bot shows its version nowhere (it has no window title, and the report does not include it). Ask dev in the ticket.
- If an update did not arrive: raise a ticket (E14). Don't copy files over the bot's folder yourself.
- Start the bot only through **launcher.exe**, never LedgerBot.exe directly, so updates are applied.

## 11. Escalating to dev

Raise a ticket in the **RPA Support** queue. Send: the exception ID from section 7, the date and time of the run, the machine name, the report file from the output folder if there is one, and a screenshot of LedgerPro as it was left. Say which statement file was used; attach it to the ticket only, never paste it into chat. Dev collects the log and screenshots from the bot's `logs` folder.
Never send: passwords, the settings file, bank or customer details in chat.

## 12. Failure-class check

- F1 covered in section 3 (shortcut, display scaling, `logs` and `data\output` folders, LedgerPro screen) and E01, E02, E12; packaging gap in section 13.
- F2 covered in section 4 (hands off, only LedgerPro open) and section 13 #9.
- F3 covered in E03, E04, E08, E09, section 8 (fixed 15 s / 10 s waits, 20 s button search), screen rule in section 3.
- F4 covered in section 3 input rules, E06, E07.
- F5 covered in E05 (stale export makes already-posted items look missing) and E10; section 13 #1, #2.
- F6 covered in E09, E10 (check LedgerPro before re-running).
- F7 covered in section 6 (`Missing` actually means posted; `Mismatch` needs follow-up; LedgerPro-only entries never reported) and section 13 #7, #16.
- F8 not applicable: the bot has no auto-rerun, no restart and no watchdog; it runs each row once and ends.
- F9 covered in section 4 (corner of the screen or Task Manager; closing the launcher or LedgerPro does not stop it).
- F10 not applicable: there is no batch, queue or lock; each run stands alone and one failed row never blocks another run. (A failed Save can make the following rows fail in the same run - covered in E09.)
- F11 covered in section 5 (report only) and section 13 #3, #5, #6.
- F12 covered in E14, section 10, section 13 #10-#13.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | `Posted` is written right after clicking Save, with no check that LedgerPro saved it | Report shows posted when it may not be | `app.py:65-70`, `app.py:90` |
| 2 | Bot reads `data/ledger_export.xlsx` without checking it was refreshed this run (fixed `sleep(10)`, no timestamp check, old file never deleted) | Stale export → existing entries posted twice, silently | `app.py:77-79` |
| 3 | Report is written only at the end; any unhandled error loses the whole report although entries were posted | Ops cannot tell what was posted | `app.py:82-96` |
| 4 | `logs/` and `data/output/` are not created by the code | Instant crash (logs) or crash after posting everything (output) | `app.py:24`, `app.py:96` |
| 5 | Crash errors go to the console only, not to the log (only `RuntimeError` inside posting is caught) | Cause lost once the console closes | `app.py:86-95`, `app.py:100-101` |
| 6 | Log and not-found screenshots are in `logs/`, which ops cannot open; report Note has only the picture file name | Ops cannot see causes themselves | `app.py:24`, `app.py:45`, `app.py:92` |
| 7 | Posted rows keep Result `Missing`; the "Not in LedgerPro - posting" note is dead text | Confusing status for ops | `app.py:58`, `app.py:87-90` |
| 8 | Fixed `sleep(15)` / `sleep(10)` instead of waiting for LedgerPro / the export file | Slow machine → E03/E04/E05 | `app.py:76`, `app.py:78` |
| 9 | No window focus or check that LedgerPro is in front; `pyautogui.write` types into whatever has focus | Typing into the wrong window | `app.py:37-46`, `app.py:65-70` |
| 10 | Launcher still swallows every update error (the "fix" commit only added a comment); version compare is `!=` so an older server build would be installed; download has no timeout or integrity check | Machines silently stay on, or roll back to, a different version | `launcher.py:16-20`, `launcher.py:25-29` |
| 11 | `VERSION` comment says it is in the window title, but nothing displays it; not in the report either | Ops cannot confirm an update | `app.py:15`, `app.py:96` |
| 12 | `ledgerbot.spec` is entirely commented out; asset inclusion cannot be verified from the repo | Repeat of the "assets missing in exe" incident | `ledgerbot.spec:2` |
| 13 | Fix commits b235445 and ba4c1aa changed only a comment line; recaptured 100% button images are not in that commit | Fixes listed in history may not be in the build | `app.py:102`, `launcher.py:35` |
| 14 | `.env` is tracked in git (and the code does not read it) | Possible secret exposure | `.env` |
| 15 | Statement reads the active sheet only; duplicate references collapse silently; a non-numeric amount crashes the run; references compared as raw `str()` (number vs text) | Silent skips or duplicate posts | `app.py:52`, `app.py:80-81` |
| 16 | LedgerPro entries not in the statement are never reported | Ops cannot see extras in the ledger | `app.py:55-62` |
| 17 | After a Save-not-found error the entry form is left open and the next row is typed into it | One failure cascades | `app.py:88-92` |
| 18 | Mouse in a screen corner (pyautogui fail-safe) aborts the run with no report | Accidental stop loses the report | `app.py:12` (default `FAILSAFE`) |