/sap-data-workbook

name: sap-data-workbook
description: Create SAP Data Workbooks (.sapwb) for SAP data analysis. Use when the user asks to analyze SAP data, create data quality checks, build reports, compare tables or systems, profile data, or any multi-step SAP data exploration. Workbooks have ABAP SQL cells (queries against SAP) and JavaScript cells (process and display results). Cells can be named, can run on different SAP systems, can show formatted tables/markdown/html/json/xml, and the workbook can be exported. They save as files and can be re-run.
argument-hint: '[what data to analyze or report to build]'
user-invocable: true
disable-model-invocation: false

SAP Data Workbook — SAP Data Analysis Made Reproducible

You create `.sapwb` files — VS Code notebooks with ABAP SQL and JavaScript cells that query SAP and process results. The user opens the file and clicks "Run All."

When To Create a Workbook

Create a workbook when the user wants to:

• Analyze SAP data (multi-table, aggregations, comparisons)
• Build a data quality check or report
• Profile table data (row counts, distributions, outliers)
• Compare data across criteria (e.g., "vendors with vs without recent orders") or **across SAP systems** (e.g., DEV vs QAS)
• Any task requiring multiple queries where later queries depend on earlier results

How to Create the File

You (GitHub Copilot in VS Code) create and edit workbooks with your notebook tools. Follow these rules exactly:

1. **Create the whole workbook in ONE `create_file` call**, inside the workspace. Write the cells in your own notebook cell format, NOT the on-disk JSON shown under *File Format* (on-disk JSON written this way ends up as empty or Python cells):

   <VSCode.Cell language="markdown">
   # Title
   What the workbook does.
   </VSCode.Cell>
   <VSCode.Cell language="abap-sql">
   SELECT mandt, mtext FROM t000
   </VSCode.Cell>
   <VSCode.Cell language="javascript">
   return cells[1].result.length
   </VSCode.Cell>

The JSON form with `cell_type`, `metadata.language` and `source` also works. Languages are exactly `abap-sql` (NOT `sql`), `javascript` and `markdown`.

2. **Read the workbook back** with your notebook read tool and check that every cell is there, with its content and the right language. A file that is valid but has empty cells, missing cells or Python cells is a failure: fix it before you tell the user it is done.

3. **Set systems, row limits and names with `abapfs_workbook_cell_settings`** (see below), in one call, after all cells exist.

4. **One edit at a time.** Wait for each notebook edit to finish before you start the next; never run edits in parallel (for example inserting a query while changing another cell fails). Read the workbook back after a series of edits.

5. **Never rewrite an existing workbook** (no `create_file` over it, no replacing all cells, no converting it with a generic notebook writer). Notebook tools cannot carry a cell's `name`, `system` or `maxRows`, so a rewrite silently deletes them. Change only the cells that need changing, one at a time.

Cell Names, Systems and Row Limits

These are stored with each cell. Your notebook tools can neither see nor set them; the **`abapfs_workbook_cell_settings`** tool does both.

**Read** the current settings: pass only `filePath`. You get one line per cell: index, language, name, own or inherited system (and whether it is connected), row limit and first line. Do this before changing an existing workbook, and whenever you are unsure which index a cell has.

**Change** settings: pass `filePath` and `cells`, one entry per cell, with `index` (0-based, counting markdown cells: the N of `cells[N]`) and at least one of:

| Field | Effect | |---|---| | `system` | System marker: this ABAP SQL cell and every following SQL cell run on that connection id, until the next marker. SQL cells only. | | `clearSystem: true` | Remove the marker; the cell inherits the marker above. | | `maxRows` | Row limit of this ABAP SQL cell, 1 to 100000. Leave it out unless the user needs more than 1000 rows. | | `name` | Cell name (letters, digits, `_`, unique); other cells can then use `cells.<name>`. | | `clearName: true` | Remove the name. |

{
  "filePath": "C:/work/workbooks/clients.sapwb",
  "cells": [
    { "index": 1, "system": "SYS1" },
    { "index": 2, "system": "SYS2" },
    { "index": 3, "system": "SYS3", "maxRows": 5000 }
  ]
}

Rules:

• Make **one call with all settings, after the last cell insert or move**: indexes shift when cells move. If cells moved, read the settings again first.
• If the tool returns an error, **nothing was changed**: fix every listed problem and call it again.
• Pass on its **warnings** to the user: a system that is not connected must be connected before Run All; cells that still reference a renamed cell must be updated.
• Use connection ids from `abapfs_get_connected_systems`, or exactly what the user named.
• **Reference earlier cells by position** (`cells[N]`) when you write the cells. Name cells only when the user asks or the workbook will be edited a lot; once a cell has a name, `cells.<name>` keeps working when cells move.
• If `abapfs_workbook_cell_settings` is not available, tell the user what to set instead, as a short list at the end of your answer: *"Click the system in the status bar of cell #1 and pick SYS1, cell #2 → SYS2"*, *"Click `Rows: 1000` on cell #2 and set 50000"*.

File Format

For reference (reading a `.sapwb` file, or tools that write plain files and have no notebook tools), `.sapwb` files are JSON on disk:

{
  "version": 1,
  "title": "Descriptive Title",
  "cells": [
    { "type": "markdown", "content": "# Title\nExplanation" },
    { "type": "abap-sql", "content": "SELECT matnr, mtart FROM mara WHERE mtart = 'FERT'", "name": "materials" },
    { "type": "javascript", "content": "// first finished material\nconst rows = cells.materials.result;\nconst out = rows.map(r => ({ MATNR: r.MATNR, MTART: r