Rpa_Skills/rpa-run-tab/SKILL.md

name, description

name

description

rpa-run-tab

Adds a Tebra-style Run tab to a desktop RPA bot in about 5 minutes. The Run tab is a PyQt6 window (or a tab in an existing PyQt web page) with a Trigger button, an Excel input card (drop zone, sheet tabs, preview with masked passwords, sample download), a progress bar with a timer, a step list, a friendly live log, checkpoint boxes with time limits, and green/amber/red endings. It also wires the real bot to the page. Use when the user asks for a "Run tab", "run screen", "trigger screen", "start/run page for my bot", or "the Tebra run tab" for an RPA or automation project. For a whole dashboard (KPIs, report table), use rpa-dashboard-no-ai.

RPA Run tab

Build the Run tab, wire the real bot to it and check it with the fake bot. The whole job should take about 5 minutes. The look is fixed. It is Tebra Auto Post's Run tab, and only the colours change. Everything needed is in templates/. Never read the original Tebra projects.

File	What it is
templates/run_tab.html	The page. Its config comes from run_tab.py, and its theme is between THEME:START and THEME:END. Each part is fenced with RUN-TAB:CSS, TOPBAR, MARKUP and JS markers.
templates/run_tab.py	The PyQt6 window and bridge. It is also the bot's process (--run-bot, which loads no Qt). It holds the CONFIG block you fill in and --selfcheck.
templates/runner.py	Qt-free. It starts the bot, reads its log file every 0.2 s, turns lines into events, kills stuck runs and decides the ending.
templates/rt.py	The protocol helpers the bot calls: checkpoint, checkpoint_done, ui, result, summary.
templates/fake_bot.py	Prints the protocol for the endings complete, partial, stuck and crash. Used only by the self-check.
templates/palette.py	Theme: sky, teal or a brand hex. Use --write to put it into the page. It checks contrast.

The rules come from the repo's ADRs. Keep to them:

• One checkpoint list drives the steps, the boxes and the progress %.
• The bot talks only through tagged lines in a log file.
• A stuck checkpoint kills the run, and the run fails.
• There is no auto-restart and no Stop or Pause button.
• There is no database, no resume and no roles.

1. Scan (about 1 minute, ask nothing yet)

Never run the bot. Real bots act on live systems.

1. Bot entry point.
   • Look for a main(...) function, an if __name__ == "__main__" script, or a run_* function.
   • Note its loop over input rows or items. Those become the summary's total and failed.
   • Note its big stages, such as sign in, open a page, process rows, export. Those become the checkpoints.
2. Input.
   • Does the bot read an Excel file (openpyxl, pandas.read_excel, xlrd)?
   • If yes, note the sheet names and column names it reads, for SAMPLE_SHEETS.
   • No Excel file means HAS_INPUT = False.
3. Host. Search for QWebEngineView, setHtml or a .html page loaded by PyQt, or an rpa-dashboard-no-ai dashboard.html. If you find one, the Run tab becomes a tab in it (step 4b). Otherwise it gets its own window (step 4a).
4. Processes. Note any extra programs the bot starts and that must die with it, such as chromedriver.exe or a desktop app. These go in KILL_ALSO.

2. Ask once (one message, at most 3 questions)

Send the scan result and these questions in one message, then wait:

1. Colour:
   • 1. Tebra Sky (blue)
   • 2. TVL Teal (green)
   • 3. Custom: send one brand hex
2. Checkpoints: propose 3–8, each with a name of 2–3 plain words and a time limit, for example Sign in, max 5 min. Use no limit for long loops over rows. The user confirms or edits the list.
3. Input: "Excel input, or no input file?" Skip this question when the scan already answered it.

Default the title and subtitle from the project name, for example Run automation and Upload the input Excel and start <project>. Don't ask about them.

3. Build

1. Copy run_tab.html, run_tab.py, runner.py and fake_bot.py into <project>/run_tab/.
2. Copy rt.py there and next to the bot's entry file.
3. Fill the CONFIG block at the top of run_tab/run_tab.py:
   • TITLE, SUBTITLE
   • BOT: "bot.py" relative to the project root, or "package.module:function"
   • HAS_INPUT, INPUT_HINT
   • CHECKPOINTS
   • SAMPLE_SHEETS
   • KILL_ALSO
   • APP_ID: the project name, no spaces
4. Apply the theme: python <skill>/templates/palette.py <sky|teal|#hex> --write <project>/run_tab/run_tab.html.
   • It must print PASS for every row.
   • If a row fails, tell the user and suggest a darker hex.
5. Make sure openpyxl, PyQt6 and PyQt6-WebEngine are in the project's requirements.

4. Wire the bot

Keep the bot's logic as it is. Only add these lines:

import rt

def main(excel_path):                # BOT = "bot:main"; the Run tab passes the Excel path
    rt.checkpoint(1); rt.ui("Signing in"); ...; rt.ui("Signed in", "ok"); rt.checkpoint_done(1)
    failed = []
    rt.checkpoint(2)
    for i, row in enumerate(rows, start=2):
        try: process(row)
        except Exception as e: failed.append((f"Row {i}", str(e))); rt.ui(f"Row {i} failed", "warn")
    rt.checkpoint_done(2)
    return rt.result(total=len(rows), failed=failed)

• Checkpoint numbers are 1-based positions in CHECKPOINTS. A loop may go back to an earlier checkpoint for the next item; the later boxes reset and the bar never moves back.
• Returning a summary. A plain script with no entry function prints rt.summary(total, failed) as its last line instead. If no summary arrives, the run counts as failed.
• What the operator sees. Only [UI] lines and error lines reach the screen. Everything else goes only to logs/run_<time>.log.
  • Keep [UI] text to progress words and row numbers.
  • Never put patient or customer names, amounts, account numbers, passwords or other PHI or secrets on screen, or in the failed reasons.
• Bot output. Leave the bot's existing prints. They go to the run log.

4a. Its own window

There is nothing more to do. Start it with python run_tab/run_tab.py.

4b. A tab in an existing PyQt page

Copy the four fenced parts of run_tab.html into the host page:

• RUN-TAB:CSS, RUN-TAB:TOPBAR, RUN-TAB:MARKUP, RUN-TAB:JS
• the THEME block, if the host has no tokens of its own

Then wire the host:

• Page config: add const CFG = ... to the host page; page_html() in run_tab.py shows its shape.
• Messages: route the host's Python→page messages through one window.__pyMsg, and merge the handlePyMessage branches.
• Bridge: give the host's bridge the Bridge slots from run_tab.py. They are browse_file, process_dropped_path, read_sheet, download_sample_input, start_automation and set_dark.
• Window: add the close guard from RunTabWindow.closeEvent.
• Don't connect js_message in the page as well as using __pyMsg. Doing both shows every message twice.

5. Verify with the fake bot

python run_tab/run_tab.py --selfcheck

It runs the fake bot through the real runner four times:

• complete → green
• partial → amber
• stuck → red, with box 2 marked stuck
• crash → red

Each line must print ok. It then saves the window as logs/selfcheck_complete_light.png, logs/selfcheck_partial_dark.png and logs/selfcheck_stuck_light.png. Look at all three. Check:

• the Tebra layout
• your colours, readable in both themes
• the checkpoint names
• no horizontal scroll

Never press Trigger on the real bot yourself. Tell the user to start the first real run.

6. Hand over (two lines)

Tell the user:

• how to start it (python run_tab/run_tab.py)
• where raw run logs go (logs/)

If the project ships as a PyInstaller exe:

• the entry point is run_tab/run_tab.py
• add run_tab/run_tab.html as data
• add the bot module as a hidden import, because the exe starts itself with --run-bot