/sap-sp02

name: sap-sp02
description: |
  Downloads a SAP spool request to a local text file via transaction
  SP02 (Output Controller — own spool requests). Drives the GUI in
  three steps: locate the spool by number on the SP02 list (matched
  across all columns, so the driver adapts to whatever column the
  layout uses), open its contents via the Display-contents button,
  then Save to local file — picking the export format radio (default
  Unconverted = plain text) and entering the target path/filename.
  Works for any list-style spool that SP02 can render (executable
  reports, ALV grids printed to spool, etc.). Format defaults to
  Unconverted plain text but accepts Spreadsheet / Rich text / HTML
  via the FORMAT_INDEX argument.
  Prerequisites: Active SAP GUI session (use /sap-login first), and
  the target spool must belong to the logged-in user (or appear in
  the user's default SP02 selection).
argument-hint: "<SPOOL_NUMBER> <OUTPUT_PATH> [--format=text|csv|rtf|html] [--row=<N>]"

SAP SP02 — Spool Download Skill

You download a SAP spool request to a local text file using SP02 GUI scripting. The spool number is the SAP-assigned `TSP01-RQIDENT` (e.g. `397`) — the same number ABAP reports print to the joblog as "Spool request <NNN> created."

Task: $ARGUMENTS

---

Shared Resources

| File | Token | Purpose | |---|---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | *(rule)* | Mandatory operating rules | | `<SAP_DEV_CORE_SHARED_DIR>/rules/language_independence_rules.md` | *(rule)* | GUI-scripting language independence — identify by component ID + DDIC field name, status-bar checks via `MessageType` codes (S/W/E/I/A), VKey instead of menu-text, no branching on `.Text`/`.Tooltip`/window titles | | `<SKILL_DIR>/references/sap_sp02_download.vbs` | many | SP02 driver: list scan + F2 + tbar[1]/btn[48] + format radio + DY_PATH/DY_FILENAME | | `<SAP_DEV_CORE_SHARED_DIR>/rules/sap_gui_security_handling.md` | *(rule)* | SAP GUI Security dialog handling — the spool **download to a local file** (Step 3, via DY_PATH/DY_FILENAME) is SAP-GUI-side file IO, so it can raise the modal "SAP GUI Security" dialog (which suspends the Scripting API and hangs cscript). Pre-check + OS-level watcher wrap that download. | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_gui_security_precheck.ps1` | *(script)* | Read-only allow-list pre-check (`saprules.xml`) — `ALLOWED` (exit 0) / `NOT_COVERED` (exit 1). Used by Step 3 before the spool download. | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_gui_security_sidecar.ps1` | *(script)* | OS-level (Win32) watcher that auto-dismisses the SAP GUI Security dialog (ticks Remember + clicks Allow). Launched as a background process before the Step 3 download. |

---

Step 0 — Resolve Work Directory

**Resolve `work_dir` via the env-aware helper** — do NOT take `work_dir` from a direct `settings.json` read (that ignores the `SAPDEV_AI_WORK_DIR` env var and `userconfig.json`). Use the `WORK_DIR=` value printed by:

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_settings_lib.ps1'; . '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('WORK_DIR=' + (Get-SapWorkDir))"

The settings note below still applies to the OTHER keys.

**Settings reads/writes follow `shared/rules/settings_lookup.md`** — merge per-key on the `.value` field (env var → `settings.local.json` → `userconfig.json` → `settings.json`); non-per-connection writes go to `userconfig.json`. Resolve sap-dev-core paths: 2 levels up from `<SKILL_DIR>` to the plugin root, then `settings.json` and (if present) `settings.local.json`. | Setting | Default if blank | |---|---| | `work_dir` | `C:\sap_dev_work` |

Set `{WORK_TEMP}` = `{work_dir}\temp`. Ensure it exists:

cmd /c if not exist "{WORK_TEMP}" mkdir "{WORK_TEMP}"

Set `{RUN_TEMP}` = the per-run scratch dir (`Get-SapRunTemp` mints + creates `{work_dir}\temp\run_<id>`):

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('RUN_TEMP=' + (Get-SapRunTemp))"

Per the CLAUDE.md "Two-bucket temp model" write this skill's generated scratch (`*_run.ps1` / `*_run.vbs` and the `_run.json` state) under `{RUN_TEMP}`; keep `{WORK_TEMP}` (base) only for `Get-SapCurrentSessionPath -WorkTemp`.

---

Step 0.5 — Start Logging

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_sp02_run.json" -Skill sap-sp02 -ParamsJson "{\"spool\":\"<SPOOL_NUMBER>\"}"

State file: `{RUN_TEMP}\sap_sp02_run.json`. Best-effort.

---

Step 1 — Parse Arguments

| Arg | Required | Notes | |---|---|---| | `SPOOL_NUMBER` | yes (or `--row=<N>`) | SAP spool request number, numeric, e.g. `397`. Matches `TSP01-RQIDENT`. | | `OUTPUT_PATH` | yes | Full local path, e.g. `C:\Temp\SP02_397.txt`. The skill splits this into `OUTPUT_DIR` (parent + trailing `\`) and `OUTPUT_FILE` (basename). | | `--format=<fmt>` | no | `text` (default = Unconverted, index 0), `csv` (Spreadsheet, index 1), `rtf` (Rich text, index 2), `html` (HTML, index 3). The exact mapping depends on SAP GUI version — verify with a one-time recording on a new release. | | `--row=<N>` | no | Bypass the label match and tick row `<N>` directly (0-based on the user-area). Use when you already know the row from a probe. | | `--col=<N>` | no | Restrict the spool-number match to one column index. **Default: match the number in any column** — the driver adapts to whatever column the layout uses (col 3 on S/4HANA 400, col 4 elsewhere). Set only to disambiguate a list where another cell could equal the number. |

**Validation:**

• `SPOOL_NUMBER`: numeric, no leading zeros (the VBS list-scan trims

whitespace before comparing).

• `OUTPUT_PATH`: parent directory must exist on the local machine. If it

doesn't, create it with `cmd /c mkdir <dir>` first.

• `OUTPUT_FILE