Rpa_Skills/tests/evals/results/handoff/h-packaged-desktop-screens-r2.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 reconciles the day's bank statement against LedgerPro, the desktop accounting app. You give it the bank statement Excel. It opens LedgerPro, exports LedgerPro's entries to Excel, and compares each reference and amount in the statement with that export. When a statement entry is not in LedgerPro, the bot creates it in LedgerPro (New Entry → reference → amount → Save). When the amounts differ, it only reports the difference. The output is one Excel file per run, Reconcile_<date>_<time>.xlsx, in the output folder. The bot runs once per statement, whenever ops starts it. It drives one app: LedgerPro. It finds LedgerPro's buttons by matching pictures of them on the screen.

2. How it works

launcher.exe (what you start)
   ├─ checks for an update → installs it into the bot folder
   └─ starts → LedgerBot.exe ──drives (mouse + keyboard)──> LedgerPro
                    │                                   (do not touch while it runs)
                    ├─ reads  → your bank statement Excel
                    ├─ reads  → LedgerPro's export file
                    └─ writes → data\output\Reconcile_<date>_<time>.xlsx (at the very end only)

• launcher.exe checks the update server for a new version, installs it if there is one, then starts the bot. It does not wait for the bot or tell you whether the bot succeeded.
• LedgerBot.exe is the bot itself. It has no window of its own: no screen, no progress bar, no Stop button. All you see is LedgerPro being driven.
• LedgerPro is the accounting app. The bot clicks its buttons and types into its forms, so the mouse and keyboard belong to the bot during a run.
• The output file is written only when the bot has gone through every row. If no new file appears, the run did not finish.

One run, step by step:

1. The launcher checks for an update and starts the bot.
2. The bot opens LedgerPro from the LedgerPro shortcut on the Desktop, then waits 15 seconds.
3. It clicks LedgerPro's Export to Excel button, then waits 10 seconds for the export.
4. It reads the export and your bank statement.
5. It goes through the statement row by row: matching amount → OK; different amount → Mismatch; not in LedgerPro → it posts the entry.
6. It writes the output file to the output folder.

3. Before a run

• Windows display scaling is 100% and the screen resolution is 1920 x 1080 (Settings → System → Display). The button pictures were taken at that setting. At 125% the bot cannot find the buttons. Nothing checks this for you.
• LedgerPro's shortcut, named exactly LedgerPro, is on your Desktop or the Public Desktop. Without it, LedgerPro never opens (E01).
• LedgerPro opens fully within 15 seconds on this machine, with no login box, update prompt or popup in front. The bot does not handle popups.
• LedgerPro's export saves to the bot's usual export location (as set up by dev). The bot does not check that the export file is from today (E08).
• Only one monitor is in use, or LedgerPro is on the main monitor. The bot only looks at the main screen.
• Bank statement Excel, first sheet:
  • Row 1 is a header. Data starts on row 2.
  • Column A = reference, column B = amount. Nothing else is read.
  • Every row with a reference must have an amount, as a real number. An empty amount or text like 1,200.00 CR stops the whole run (E09). Bad: TX-1001 | (blank) · Good: TX-1001 | 1200.00
  • Each reference once. If a reference appears twice, only the last row is used and the other is silently dropped.
  • Type references as text, exactly as LedgerPro shows them. A reference typed as a plain number can be read as 1001.0 and will not match LedgerPro's 1001. Bad: 1001 stored as a number · Good: 1001 stored as text (or TX-1001)
  • Use only plain English letters, digits and punctuation in references. The bot cannot type accented or other special characters.
• Start the run by dragging the statement Excel onto launcher.exe (or the shortcut ops was given). Starting it without a file does nothing visible and produces no output.
• Version check: the bot has no screen that shows its version today (see section 10). Ask dev to confirm the version after each release.

4. During a run

• Hands off the mouse and keyboard for the whole run. The bot types into whatever window has focus. If you click elsewhere, it types references and amounts into that window.
• Do not open or move other windows over LedgerPro. A window covering a button makes the bot fail that row.
• Do not move the mouse into a corner of the screen. That is the emergency stop: the bot stops at once and writes no output file, but anything it already posted stays posted in LedgerPro.
• To stop the bot: there is no Stop button. Move the mouse into a corner of the screen, or end LedgerBot.exe in Task Manager. Closing LedgerPro does not stop the bot. After stopping, do the checks in E07 before running again.
• How long a run takes: about 30 seconds of start-up, then a few seconds per posted entry. Every row that fails costs an extra 20 seconds or more. If one Save fails, the following rows often fail too (E04), so a run with many failures can take a long time. There is no watchdog. If LedgerPro has shown no movement for more than 2 minutes and no output file has appeared, stop the bot as above and follow E07.

5. Where to look when something goes wrong

Ops can open the output folder and the output files only. The bot has no screens of its own, and the log folder is not open to ops (see Fix before handover).

Question	Where to look
Did the run finish?	Output folder data\output\: is there a new Reconcile_<date>_<time>.xlsx with the time of this run? No new file = the run did not finish (E01, E02, E07, E09).
Which items failed?	The output file, Result column = Error. Also check Mismatch rows: they need a person.
Why did one item fail?	The output file, Note column of that row. Then look at LedgerPro itself.
Was an entry really posted?	Only LedgerPro can tell you. The bot writes Posted after clicking Save, without checking (E05).
Did the bot already retry?	It never retries an item or a run. It only searches for a button for 20 seconds before giving up on that row.
Which version is running?	Not visible to ops today. Ask dev (section 10).

6. Statuses

The output file has no colours. Statuses are the text in the Result and Note columns.

Result	Note	Meaning	What ops does
OK	(empty)	The reference is in LedgerPro with the same amount (within 1 cent).	Nothing.
Missing	Posted	The reference was not in LedgerPro, and the bot entered it and clicked Save. Despite the word "Missing", the bot believes it posted the entry. It did not check that the save worked.	Spot-check a few in LedgerPro. Check all of them if any Save-related errors appear in the same run (E04, E05).
Mismatch	LedgerPro has <amount>	The reference exists in LedgerPro with a different amount. The bot changed nothing.	Needs follow-up. Investigate and correct by hand in LedgerPro (E06).
Error	Button new_entry.png not found on screen	The bot could not find LedgerPro's New Entry button. Nothing was entered for this row.	E03.
Error	Button save_btn.png not found on screen	The bot typed the entry but could not find the Save button. The entry is most likely not saved, and the form may still be open.	E04.
(no output file)	-	The run stopped before the end. Nothing is recorded for any row, even rows already posted.	E07.

Not in LedgerPro - posting is a note the bot sets internally before posting. It is always replaced, so you will never see it in the output.

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	LedgerPro never opens; no output file appears	It looks for a shortcut named LedgerPro on your Desktop and the Public Desktop. If neither has one, it stops at once.	Nowhere ops can see. No output file.	System	Ops	Put the LedgerPro shortcut on the Desktop (exact name), then run again.	The shortcut is there and LedgerPro still does not open.
E02	LedgerPro opens, but nothing is clicked; no output file appears	After 15 s it looks for the Export to Excel button for 20 s. If it never matches the button picture, it stops the run.	Nowhere ops can see. No output file.	System	Ops, then Dev	Check scaling is 100% and resolution 1920 x 1080; close any popup or login box in LedgerPro; make sure LedgerPro is maximised on the main screen; run again.	It still happens with the right settings, or it happens on a fresh install or right after an update (the button pictures may be missing from the build, see incident #3).
E03	Result Error, Note Button new_entry.png not found on screen	When posting, it looks for the New Entry button for 20 s and gives up on that row.	Output file, Result and Note	System	Ops	Check scaling and popups as in E02. Check in LedgerPro that the reference is not there, then run again with the statement.	Several runs in a row fail this way with correct settings.
E04	Result Error, Note Button save_btn.png not found on screen, often followed by more Errors on later rows	It clicked New Entry and typed the reference and amount, then looked for Save for 20 s and gave up. It does not close the half-filled form, so later rows may type into the wrong place.	Output file, Result and Note	System	Ops	1. In LedgerPro, close any open New Entry form without saving. 2. Search LedgerPro for each Error reference and for the Missing / Posted rows after it, to see what was really saved. 3. Fix or delete stray entries by hand. 4. Run again.	It happens again after a clean restart with correct settings.
E05	Result Missing, Note Posted, but the entry is not in LedgerPro or has the wrong amount	The bot writes Posted as soon as it clicks Save. It does not check for a save confirmation, a validation message, or that the typed text landed in the right fields.	Output file says Posted; the truth is only in LedgerPro	System	Ops	Check in LedgerPro before re-running. Enter or correct the entry by hand, or run again with a statement holding only the missing rows.	More than one or two per run, or wrong amounts typed. Send the output file.
E06	Result Mismatch, Note LedgerPro has <amount>	The reference is in LedgerPro, but the amounts differ by more than 1 cent.	Output file, Result and Note	Business	Ops	Find out which amount is right (statement or LedgerPro) and correct it by hand. The bot never changes existing entries.	Never for dev, unless the amounts are clearly read wrongly (e.g. every row mismatches).
E07	The run stops midway: LedgerPro stops moving and no output file appears	Any unexpected problem stops the whole run: the mouse touched a screen corner, an amount could not be read, an unexpected error in LedgerPro. Nothing is recorded.	Nowhere. No output file, even for rows already posted.	System	Ops, then Dev	1. Do not re-run straight away. 2. In LedgerPro, close any open form. 3. Check which statement references are already in LedgerPro. 4. Check the statement against the input rules in section 3. 5. Run again.	It stops again with a clean statement and nobody touching the machine.
E08	Many rows Missing / Posted that were already in LedgerPro, or duplicate entries in LedgerPro after a run	The bot reads the last export file 10 s after clicking Export. If the export was slower, or saved elsewhere, it reads an older export without noticing.	Output file looks normal; duplicates only show in LedgerPro	System	Dev	Remove the duplicate entries in LedgerPro by hand. Do not run again until dev has checked the export.	Always.
E09	No output file, right after LedgerPro exports	The bot could not read the statement: an empty or text amount, no file given, or the file is not an Excel workbook.	Nowhere. No output file.	Business	Ops	Fix the statement as per section 3 (every amount a number, one reference per row), then run again.	The statement is clean and it still fails.
E10	A row you expected is missing from the output file	The statement had the same reference twice. The bot keeps only the last one.	Not recorded	Business	Ops	Remove duplicates from the statement, or post the dropped row by hand.	-
E11	Text appears in another window; references or amounts typed in the wrong place	Someone used the mouse or keyboard, or another window came in front. The bot types into whatever has focus.	Not recorded	System	Ops	Undo the stray typing. Check LedgerPro for half-entered entries. Run again hands-off.	-
E12	After a release, this machine behaves like the old version	The launcher could not reach the update server (offline, or the server's certificate is not trusted on this machine). It ignores the problem and starts the old version.	Not recorded	System	Dev	Raise a ticket so dev can check the version and update this machine.	Always, after every release where behaviour does not change.
E13	Double-clicking the launcher does nothing; the bot never starts	The update download or install failed, and the launcher stopped before starting the bot.	Not recorded	System	Dev	Raise a ticket. Do not copy files into the bot folder yourself.	Always.

8. What the bot recovers by itself

Very little. Ops should not expect it to fix anything on its own.

Problem	What the bot does	Limit	After the limit
A button is not on screen yet	Looks for it once a second	20 s per button	Export button: the whole run stops (E02). New Entry or Save: that row is Error, next row (E03, E04).
LedgerPro is slow to open	Nothing; it simply waits	Fixed 15 s	Same as above.
Export is slow	Nothing; it simply waits	Fixed 10 s	Reads whatever export file is there (E08).
Update server unreachable	Starts the old version without telling you	10 s	Old version keeps running (E12).
Anything else	No retry, no restart, no resume	-	Run stops with no output file (E07).

9. Known incidents

When / version	What ops saw	Cause	What to do now	Ops could handle?
Up to v3.2.0 (#3)	The packaged bot failed at its very first button on every machine	The button pictures were left out of the packaged build	Dev says this is fixed, but the current build file does not show it. If the bot fails at the first button on a fresh install or after an update, raise a ticket (E02).	No
Up to v3.2.0 (#2)	Rows Error "Button save_btn.png not found on screen" on some laptops	Laptops at 125% display scaling. The button pictures only match at 100%.	Keep scaling at 100% and resolution 1920 x 1080 (section 3). Check this first for any "not found" error.	Yes
Up to v3.2.0 (#1)	Two laptops stayed on the old version after a release; no error	The launcher could not trust the update server's certificate and quietly ran the old version	Still possible: the code still hides this. After each release, ask dev to confirm every machine's version (E12).	Partly

10. Releases and version check

• How an update arrives: each time you start launcher.exe, it asks the update server for the latest version. If it differs, it downloads it and installs it into the bot folder, then starts the bot.
• How to confirm it applied: ops cannot see the version today. The bot has no window or title bar. Ask dev to confirm through the RPA Support ticket after each release.
• If the version did not change (behaviour after a release is unchanged): raise a ticket (E12). Do not copy files into the bot folder by hand.
• All machines should run the same version, so that results from different machines are comparable.

11. Escalating to dev

Raise a ticket in the RPA Support queue. Send:

• the exception ID from section 7 (e.g. E04),
• the machine name and the date and time the run started,
• the file name of the bank statement used (not its contents in chat),
• the output file Reconcile_<date>_<time>.xlsx, if one was produced, or "no output file",
• the Result and Note of the failing rows,
• what LedgerPro showed at the time (a description, or a screenshot that shows no customer data).

Dev collects the bot's own log and "not found" screenshots from the machine; ops does not have access to them.

Never send: passwords, the bot's settings files, or customer or account data in chat.

12. Failure-class check

• F1 missing prerequisite: covered in section 3 (shortcut, scaling, single screen) and E01, E02, E13; required folders and build contents in Fix before handover #9, #11.
• F2 wrong window or focus: covered in section 4 (hands off, nothing over LedgerPro) and E11. The bot does not look for windows by title; it clicks wherever the button picture matches on the main screen.
• F3 target app slower or different: covered in E02, E03, E04, section 8 (fixed 15 s and 10 s waits, 20 s per button) and section 3 (scaling, resolution, popups); Fix before handover #2, #6.
• F4 input read differently: covered in section 3 input rules, E09, E10; Fix before handover #10.
• F5 marked done when nothing was done: covered in E05 and E08; Fix before handover #1, #2.
• F6 action happened but not confirmed: covered in E04, E05 and E07 (check in LedgerPro before re-running); Fix before handover #1, #5.
• F7 business exception shown as success: covered in section 6. Mismatch needs follow-up but has no colour, and posted rows keep the result Missing; Fix before handover #7.
• F8 endless re-runs or watchdog: covered in section 4. The bot has no re-runs and no watchdog, so a hung run has no time limit; Fix before handover #3.
• F9 stopping the wrong way: covered in section 4 (corner or Task Manager; closing LedgerPro does not stop it) and E07.
• F10 one stuck item blocks the queue: covered in E04. A failed Save leaves the form open and later rows fail too. There are no batches or locks between runs; Fix before handover #5.
• F11 cause hidden from ops: covered in section 5. Crash reasons, the log and the screenshots are not reachable by ops; Fix before handover #3, #4, #8.
• F12 update did not arrive: covered in section 10, E12, E13 and incident #1; Fix before handover #12, #13, #14.

13. Fix before handover (dev team)

#	Gap	Why it hurts ops	Where (file:line)
1	Posted is written as soon as Save is clicked; no save confirmation or check that the entry exists	Ops trusts entries that may not be in LedgerPro (E05)	app.py:65-70, app.py:89-90
2	Fixed sleeps for LedgerPro start (15 s) and export (10 s); the export file's date is never checked	A slow export means an old export is read, giving false Missing rows and duplicate posts (E08)	app.py:75-79
3	Output is written only at the end; a crash leaves no file and no reason anywhere; no watchdog	Ops cannot tell what was posted before a crash (E07)	app.py:82-96, app.py:100-101
4	Only one error type is caught per row; any other error (fail-safe corner, bad amount, image-library exception) ends the run	One bad row loses the whole run's results	app.py:91, app.py:52, app.py:81
5	After "Save not found" the half-filled form is left open; no reset before the next row	One failure spreads to later rows (E04)	app.py:65-70, app.py:88-92
6	No check of display scaling or resolution at start; images match only at 100% / 1920x1080	Wrong setting shows up as many 20 s failures	app.py:20
7	Rows the bot posted keep Result Missing; nothing in the file is coloured; Mismatch is not flagged as needing follow-up	Ops reads Missing as "not done" and may post twice	app.py:58, app.py:87-94
8	The log and "not found" screenshots are in the log folder, which ops cannot open. Screenshots overwrite each other (no time or reference in the name) and may show customer data. All lines are INFO, with no start, end or error lines. The run summary goes only to the console.	Ops has no way to see the cause beyond the Note column	app.py:24-25, app.py:45, app.py:95, app.py:97
9	logs\ and data\output\ must already exist; missing logs\ crashes at start, missing data\output\ crashes after all posting	All posting done, no record of it	app.py:24, app.py:96
10	Statement input not validated: empty or text amount crashes the run; duplicate references silently collapse; numeric references become 1001.0; no file argument crashes; non-ASCII cannot be typed	Silent skips and lost runs (E09, E10)	app.py:81, app.py:67, app.py:101
11	The build spec is only comments; the line that bundles the button pictures is commented out. The "assets missing" fix commit is not in the code.	A rebuild brings back incident #3	ledgerbot.spec:1-3
12	The launcher still hides every update error (offline, SSL, bad reply). The "SSL error" fix commit only added a comment.	Machines stay on old versions unnoticed (E12)	launcher.py:15-20, launcher.py:35
13	The launcher compares versions with "not equal" and its own version is fixed at build time, so it can reinstall on every start, or install an older version. No checksum on the download; update.zip is left behind.	Slow starts, wrong versions, launcher crash (E13)	launcher.py:9, launcher.py:25-29
14	No visible version. The comment says the window title shows "LedgerBot v3.2.0", but there is no window.	Ops cannot do a version check (section 10)	app.py:15
15	No guard against posting twice when a run is repeated after a crash or with an old export	Duplicate entries in LedgerPro	app.py:86-92
16	Library versions are not pinned; newer versions of the image library raise an error instead of "not found", which would crash runs on any missing button	A rebuild can change behaviour silently	requirements.txt
17	The marker file BOT_WAS_RUN is written at start but never read	None today; misleading if someone relies on it	app.py:74