Rpa_Skills/tests/evals/results/handoff/h-packaged-desktop-full-r3.md

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 checks the day's bank statement against the LedgerPro accounting app and adds any entry that is missing from LedgerPro. You give it one bank-statement Excel file. It opens LedgerPro, exports LedgerPro's entries to Excel, compares every statement line with them by reference number and amount, and types each missing entry into LedgerPro (New Entry → reference → amount → Save). At the end it writes one result file, data/output/Reconcile_<date>_<time>.xlsx, with one row per statement line. It drives one desktop app: LedgerPro. It does this by looking for pictures of LedgerPro's buttons on the screen and clicking them, so the screen must look exactly the way it did when those pictures were taken.

2. How it works

launcher.exe (what you start)
   └─ checks for an update, then starts → LedgerBot.exe ──clicks & types──> LedgerPro
                                              │                (do not touch while it runs)
                                              ├─ reads  → your bank statement Excel
                                              ├─ reads  → data/ledger_export.xlsx (LedgerPro's export)
                                              ├─ writes → data/output/Reconcile_<date>_<time>.xlsx
                                              └─ writes → logs/ledger_<date>.log
                                                          logs/notfound_<button>.png (only on a problem)

• launcher.exe asks the update server whether a newer LedgerBot exists, installs it if so, then starts LedgerBot.exe. If it cannot reach the server it starts the current build without telling you.
• LedgerBot.exe does the actual work. It has no window of its own with buttons; it only moves the mouse and types.
• LedgerPro is the accounting app the bot drives. Hands off it while the bot runs.
• Your bank statement Excel is the input (see section 3 for its layout).
• data/ledger_export.xlsx is LedgerPro's own export; the bot reads it as "what LedgerPro already has".
• data/output/Reconcile_….xlsx is the result file: columns Reference, Amount, Result, Note.
• logs/ledger_.log gets one line per statement line (reference, result, note). One log file per day; several runs on the same day go into the same file.
• logs/notfound_.png is a screenshot taken when the bot could not find a button.

One run, step by step:

1. Finds the LedgerPro shortcut on the Desktop and starts LedgerPro.
2. Waits 15 seconds for LedgerPro to open.
3. Clicks LedgerPro's Export to Excel button, then waits 10 seconds.
4. Reads data/ledger_export.xlsx (LedgerPro's entries) and your statement Excel.
5. For each statement line: OK if LedgerPro has the same amount, Mismatch if the amount differs, Missing if LedgerPro does not have the reference at all.
6. For each Missing line: clicks New Entry, types the reference, Tab, types the amount, clicks Save.
7. After the last line, saves the result file. The result file only exists if the bot reaches this step.

3. Before a run

• Start the bot by dragging the bank statement Excel onto launcher.exe (or a shortcut that passes the statement file). Started without a file, the bot stops at once with no result file.
• LedgerPro's Export to Excel saves to data\ledger_export.xlsx next to LedgerBot.exe. Check the file's modified time changes on each run (E08).
• Display scaling is 100% (Settings → System → Display → Scale), screen resolution 1920 × 1080. At 125% the bot misses buttons (section 9).
• The LedgerPro shortcut is named exactly LedgerPro and sits on your Desktop or on the Public Desktop. Otherwise the run stops at once (E01).
• The folders logs and data\output exist next to LedgerBot.exe. If logs is missing the bot does not start; if data\output is missing the bot does all the posting and then cannot save the result file (E07).
• Bank statement Excel layout - the bot reads only the first sheet:
  • Row 1 is a header; data starts at row 2.
  • Column A = reference, column B = amount. Other columns are ignored.
  • Amount must be a real number cell. Good: 1234.50. Bad: 1,234.50 USD, $1234.50 typed as text, or an empty amount cell. One bad amount stops the whole run before anything is compared (E06).
  • A row with an empty reference is skipped silently.
  • Each reference only once. If the same reference appears twice, the bot keeps only the last one and the other line is not in the result file at all.
  • The reference must be spelled exactly as it will appear in LedgerPro (REF-1001 and REF 1001 are different references).
• Amounts are compared to the cent: a difference of more than 0.01 is a Mismatch.
• Note the version: see section 10.

4. During a run

• Hands off the mouse and keyboard. The bot types into whatever window has focus. If you click elsewhere, the reference and amount get typed into that window.
• Keep LedgerPro maximised and visible, with nothing on top of it. No other window may show something that looks like LedgerPro's buttons (for example a screenshot or a second LedgerPro).
• Do not lock the screen and do not let the screen saver start - the bot can only click what is visible.
• To stop the bot: close the LedgerBot console window (or end LedgerBot.exe in Task Manager). Moving the mouse into the top-left corner of the screen also stops it. Closing LedgerPro does not stop it - the bot keeps looking for buttons and then stops with an error. Whichever way you stop it, no result file is written, so treat the run as in section 7, E07.
• How long it waits: about 25 seconds to open LedgerPro and export, then up to 20 seconds per button. If nothing moves on screen for more than a minute, the bot has stopped or is stuck - check whether the LedgerBot window is still open.

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 your run. No new file = the run did not finish (E07).
Which lines failed?	Result file → filter column Result = Error (and review Mismatch).
Why did one line fail?	Result file → column Note. Then logs\ledger_<date>.log, search for the reference.
What did the screen look like?	logs\notfound_<button>.png (only the latest one per button - older ones are overwritten).
Why did the whole run stop?	The LedgerBot console window, if it is still open - the reason is shown there only. It is not in the log file (see section 13).
Did the bot already retry?	It never retries. Every Error is final for that run.
Which version is running?	Not shown anywhere today (see section 10 and section 13).

6. Statuses

The result file has no colours. These are all the values the bot writes in Result and Note:

Result	Note	Meaning	What ops does
OK	(empty)	LedgerPro already has this reference with the same amount.	nothing
Missing	Posted	The reference was not in LedgerPro. The bot typed it in and clicked Save. "Missing" here means "was missing, bot added it" - it is the normal outcome of a post. The bot does not check that LedgerPro accepted the save.	Spot-check a few in LedgerPro. If one is not there, see E05.
Mismatch	LedgerPro has <amount>	LedgerPro has this reference but with a different amount. The bot changes nothing.	Needs follow-up: compare with the statement and correct LedgerPro by hand.
Error	Button new_entry.png not found on screen	The bot could not find LedgerPro's New Entry button. Nothing was typed for this line.	E03
Error	Button save_btn.png not found on screen	The bot typed reference and amount but could not find Save. The entry is not saved, and the half-filled entry form may still be open.	E04

A value you will never see but which the code mentions: Note Not in LedgerPro - posting is always replaced by Posted or by an error text before the file is saved.

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	Bot stops at once, LedgerPro never opens; console shows "LedgerPro shortcut not found on the Desktop"	It looks for a shortcut named LedgerPro on your Desktop and the Public Desktop	Console window only. No result file.	System	Ops	Put the LedgerPro shortcut on the Desktop with that exact name. Run again.	The shortcut is there and it still fails
E02	LedgerPro opens but nothing is clicked; bot stops after ~20 s; console shows "Button export_excel.png not found on screen"	It searches the screen for 20 s for a picture of the Export to Excel button	Console window; logs\notfound_export_excel.png. No result file.	System	Ops, then Dev	Check display scaling is 100%, LedgerPro is maximised and fully loaded (on a slow day it can take longer than 15 s to open). Run again.	Fails twice with scaling at 100% - send the screenshot
E03	Result = Error, Note Button new_entry.png not found on screen	Searches 20 s for the New Entry button	Result file; log line; logs\notfound_new_entry.png	System	Ops	Check LedgerPro: nothing was entered for this reference. Look at the screenshot: a popup or dialog in LedgerPro usually explains it - close it. Run again with the same statement; lines already posted now show OK.	More than one line per run, or it repeats on the re-run
E04	Result = Error, Note Button save_btn.png not found on screen	Clicked New Entry and typed, then searched 20 s for Save	Result file; log line; logs\notfound_save_btn.png	System	Ops	In LedgerPro, check the entry for this reference: it is usually not saved and a half-filled entry form may still be open - cancel it. The next line may also have been typed into that open form, so check the next reference too. Then run again.	It happens on every line, or scaling is already 100% (this was the 125% scaling incident)
E05	Result = Missing / Posted, but the entry is not in LedgerPro (or has wrong text in it)	The bot only clicks Save; it does not check for a "saved" message	Nothing - the row looks normal	System	Ops	Add the entry in LedgerPro by hand, or run again (the line then comes out Missing again and is re-posted). Check LedgerPro before re-running so you do not post twice.	It happens more than once a week
E06	Bot stops right after the export; console shows an error about converting a value to a number (for example "could not convert string to float")	It turns every amount in column B (statement and LedgerPro export) into a number; a text or empty amount stops the run	Console window only. No result file. Nothing was posted yet.	Business	Ops	Fix the amount column in the statement (real numbers, no currency signs, no empty amounts). Run again. If the statement is fine, the bad value is in LedgerPro's export - escalate.	The statement is clean and it still stops
E07	No new result file after the run (bot window closed, or stopped half-way)	Any stop in the middle (button not found before posting, mouse in the corner, window closed, data\output missing, crash)	Only the log lines for lines already handled. The console message is lost once the window closes.	System	Ops, then Dev	Lines in today's log were handled - Missing lines there were posted. Do not run again blindly: first check that data\output exists and that LedgerPro is closed, then run again. Posted lines will now show OK.	Twice in a row, or the console message is not one of E01-E06
E08	Result file shows Missing for references that are already in LedgerPro, or OK for ones that are not	The bot reads data\ledger_export.xlsx. If today's export did not save there, it reads an older export without noticing	Nothing - looks like a normal run	System	Ops, then Dev	Before a run, check the date of data\ledger_export.xlsx changes when the bot exports. If it did not, stop the bot and escalate - re-running would post duplicates.	Always - the export path needs a dev fix (section 13)
E09	A statement line is missing from the result file	Duplicate reference in the statement: the bot keeps only the last one; or an empty reference cell: skipped	Nothing	Business	Ops	Make every reference unique in the statement; fill empty references.	Never - input fix
E10	Version did not change after an update, or the bot starts but behaves like an older build	The launcher gives up silently if the update server is unreachable or its certificate is not trusted	Nothing	System	Dev	Report the machine name and what version you expected.	Always

What to send for every "Dev" escalation (in #rpa-support): the exception ID (E02…), the date and time of the run, the statement file name (not its content), logs\ledger_<date>.log, any logs\notfound_*.png - check the screenshot shows no client names or amounts first, or crop it - and a photo or copy of the console message if the window is still open.

8. What the bot recovers by itself

Problem	What the bot does	Limit	After the limit
Button not on screen yet	Looks again every second	20 s per button	Export button: run stops (E02). New Entry / Save: line = Error, next line (E03/E04)
LedgerPro slow to open	Fixed wait, no check	15 s, then the 20 s button search	E02
Export slow to save	Fixed wait, no check	10 s	Reads whatever export file is there (E08)
Anything else	Nothing. No retries, no restarts, no resume.	-	Run stops, no result file (E07)

There is no watchdog and no automatic re-run. A run either finishes with a result file or stops; you never need to wait for the bot to "try again".

9. Known incidents

When / version	What ops saw	Cause	What to do now	Ops could handle?
2026-10-23 (fix recorded), 3.2.0	Bot started but could not find any button in the exe build	Button pictures were not packed into the exe	Fix recorded in git; see section 13 item 3. If every button fails on a fresh install, escalate (E02).	No
2026-10-23 (fix recorded)	Save clicked in the wrong place / missed on some laptops	Laptops at 125% display scaling; button pictures taken at 100%	Keep display scaling at 100% (section 3)	Yes
2026-10-23 (fix recorded)	Two laptops never got the new version	Launcher silently ignored the update server's untrusted (self-signed) certificate and kept starting the old build	Compare the version after every release (section 10); escalate E10	Partly
2026-09-05 (log)	One line Error "Button save_btn.png not found on screen"	Matches the 125% scaling incident	E04	Yes

10. Releases and version check

• How an update arrives: start the bot through launcher.exe, never LedgerBot.exe directly. The launcher downloads and unpacks the new build before starting the bot.
• How to confirm it applied: today you cannot see the version on screen - the bot has no window title or About box. Until the dev team adds one (section 13), ask in #rpa-support for the expected release date and compare the date of LedgerBot.exe in the program folder.
• If the version did not change: the launcher failed silently (no internet, or the update server's certificate is not trusted on this machine). Escalate E10 with the machine name. Do not copy files between laptops yourself.

11. Escalating to dev

Send in Teams #rpa-support: exception ID from section 7, date and time of the run, machine name, logs\ledger_<date>.log, the logs\notfound_*.png screenshot (cropped of client names and amounts), and the console message if still visible. Never send: passwords, the .env settings file, the bank statement itself, or client names and amounts in chat.

12. Failure-class check

• F1 Missing prerequisite - covered in section 3 (shortcut, folders, scaling) and E01, E07; section 13 items 3, 7.
• F2 Wrong window / focus - covered in section 4 (hands off, LedgerPro maximised, nothing on top) and E04 (typing into the wrong form).
• F3 Target app slower or different - covered in E02-E04, section 8 (15 s / 10 s fixed waits, 20 s per button), section 3 (100%, 1920 × 1080); section 13 item 5.
• F4 Input read differently - covered in section 3 input rules and E06, E09.
• F5 Marked done when nothing was done - covered in E08 (stale export read as current); section 13 item 4.
• F6 Action happened but not confirmed - covered in E05 and E04; section 13 item 2.
• F7 Business exception shown as success - covered in section 6 (Missing = posted; Mismatch needs follow-up); section 13 item 6.
• F8 Endless re-runs / watchdog - not applicable: the bot has no re-run loop and no watchdog; every wait has a fixed limit (section 8).
• F9 Stopping the wrong way - covered in section 4 (close the console window; closing LedgerPro does not stop it) and E07.
• F10 One stuck item blocks the queue - not applicable: there is no batch, queue or lock; each run is independent and an Error line does not block anything.
• F11 Cause hidden from ops - covered in section 5 (console-only messages) and section 13 items 1, 8.
• F12 Update did not arrive - covered in section 10 and E10; section 13 items 9, 10.

13. Fix before handover (dev team)

#	Gap	Why it hurts ops	Where (file:line)
1	A run that stops writes no result file: the workbook is saved only after the last line, and nothing catches errors outside post_entry. Lines already posted are only in the log.	Ops cannot tell which entries were posted; risk of double posting on re-run	app.py:86-96
2	No confirmation after Save: post_entry returns as soon as Save is clicked; the note "Posted" is written without checking LedgerPro accepted it. After a Save-not-found error the half-filled form stays open and the next line types into it.	Silent missing or corrupted entries (E04, E05)	app.py:65-70, app.py:88-92
3	The "fix" commits only added comments. ledgerbot.spec is entirely commented out (the datas line is a comment), and the files in assets/ are 16-byte placeholders, not real button pictures - the 100%-scaling recapture is not in the repo.	A fresh build may again have no button images	ledgerbot.spec:2-3, assets/*.png, commits 2ade1d3, 158175d
4	Stale export: bot clicks Export and reads data/ledger_export.xlsx after a fixed 10 s, with no check that the file is new (and nothing tells LedgerPro to save to that path).	An old export makes the bot re-post entries already in LedgerPro (E08)	app.py:77-79
5	Fixed waits (15 s start, 10 s export) instead of waiting for a screen. Also: newer pyautogui raises an exception instead of returning nothing when an image is not found, which would skip the 20 s retry loop entirely; requirements.txt does not pin versions.	Run stops on a slow day; behaviour depends on which library version was packed	app.py:39-41, app.py:76-78, requirements.txt
6	Result "Missing" is kept for lines that were successfully posted (Note "Posted"); summary counts them as Missing.	Ops reads a successful post as a problem	app.py:86-93
7	logs/ and data/output/ are not created by the code. Missing logs stops the bot on start; missing data/output fails after all posting.	Posted entries with no result file	app.py:24, app.py:96
8	Run-stopping errors and the summary counts go to the console only (print), not to the log file.	Cause lost when the window closes	app.py:97, app.py:101
9	Launcher still swallows every update error (except Exception: return None) - the SSL-incident "fix" is only a comment. A download or unzip failure is not caught and stops the launcher, so the bot never starts. Version check is !=, so an older version on the server downgrades every machine.	Machines silently stay on, or roll back to, old builds	launcher.py:15-20, launcher.py:25-29, commit 0085285
10	Version is not shown anywhere (the comment says "window title" but there is no window); launcher compares against its own built-in copy of the version, so after an update it may download again on every start.	Ops cannot confirm an update applied	app.py:15, launcher.py:9
11	notfound_<button>.png is overwritten each time and is a full-screen screenshot that can contain client names and amounts.	Evidence lost; screenshots need cropping before sharing	app.py:45
12	.env is committed to git (the code does not read it).	Possible secrets in the repo history	.env, commit cd9e04d
13	Duplicate references in the statement collapse silently (dict keeps the last).	A real bank line disappears from the result	app.py:81
14	The 2026-09-05 log has a Mismatch line with a party name in brackets that the current code does not write. Either the deployed build differs from this source, or names reach the log.	Ops may be running code nobody can read; client names in a file ops share	logs/ledger_20260905.log:3 vs app.py:60
15	No popup handling: any LedgerPro dialog (login prompt, Save As on export, warning) blocks every button search.	Run stops with "not found" and no hint that a dialog was the cause	app.py:37-46, app.py:77