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

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 "	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)