Rpa_Skills/tests/evals/results/handoff/h-packaged-desktop-full-r2.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 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	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 "	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