sap-va01

name	sap-va01
description	Manages SAP sales orders via VA01/VA02/VA03 using SAP GUI Scripting. Creates new sales orders or updates existing ones. Existence check (VA03 Display), order creation (VA01) with header/item handling, order update (VA02), and save. Field values are provided as tab-separated section/field/value triples in a definition file. By default an order that SAP reports as INCOMPLETE at save time is NOT saved (fail-loud); pass --allow-incomplete to save it anyway. Prerequisites: Active SAP GUI session (use /sap-login first).
argument-hint	<order-number-or-action> [field-values-to-set] [--allow-incomplete]

SAP VA01 Sales Order Maintenance Skill

You manage SAP sales orders via VA01 (Create), VA02 (Change), and VA03 (Display) using SAP GUI Scripting. The skill checks if an order exists, then creates or updates it with the provided field values.

Task: $ARGUMENTS

---

Shared Resources

File	Purpose
<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md	Mandatory operating rules
<SAP_DEV_CORE_SHARED_DIR>/rules/language_independence_rules.md	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

---

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 <SAP_DEV_CORE_SHARED_DIR>/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 cross-plugin paths: 3 levels up from <SKILL_DIR>, then into sap-dev-core\settings.json and (if present) sap-dev-core\settings.local.json. Read custom_url.

Setting	Default if blank
work_dir	C:\sap_dev_work
custom_url	{work_dir}\custom

Set {WORK_TEMP} = {work_dir}\temp

Ensure the temp directory 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

Start a structured log run. State file: {RUN_TEMP}\sap_va01_run.json. Best-effort.

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_va01_run.json" -Skill sap-va01 -ParamsJson "{\"order\":\"<VBELN>\"}"

---

Step 1 — Collect Parameters

Sales Order Details

Parameter	Description	Example
Order number	Sales order number (for update/check; blank for new)	1659
Order type	Sales document type key (for Create only)	ZTA
Sales organization	Sales organization (for Create only)	BX01
Distribution channel	Distribution channel (for Create only)	00
Division	Division (for Create only)	00
Field values	Header, sales, and item fields (see format below)	See Step 2
--allow-incomplete	Optional flag: save even when SAP raises the incomplete-document popup. Default (flag absent): the script chooses the non-save option, backs out, and fails with ERROR: INCOMPLETE_DOCUMENT	(omit)

Common Order Type Keys:

Key	Description
OR	Standard Order
ZTA	Standard Order (custom)
RE	Returns
SO	Rush Order
CS	Cash Sales

---

Step 2 — Prepare Field Definition File

The field definition file is a tab-separated text file that specifies which fields to fill. Format:

SECTION<TAB>FIELD_NAME<TAB>VALUE

• SECTION: HEADER for header fields, SALES for Sales tab fields, or ITEM_NN for item rows
• FIELD_NAME: SAP ABAP field name (e.g., KUAGV-KUNNR, RV45A-MABNR)
• VALUE: The value to set. For checkboxes use X/1 (checked) or empty/0 (unchecked)
• Lines starting with # are comments. Blank lines are skipped.

Header Fields (HEADER section):

Field Name	Description	Example
KUAGV-KUNNR	Sold-To Party	20000000
KUWEV-KUNNR	Ship-To Party	20000000
VBKD-BSTKD	Customer Reference	PO-REF-001
VBKD-BSTDK	Customer Ref. Date	2026.04.01

Sales Tab Fields (SALES section):

Field Name	Description	Example
RV45A-KETDAT	Requested Delivery Date	2026.04.15
RV45A-DWERK	Delivering Plant	BX01
VBKD-PRSDT	Pricing Date	2026.04.01
VBKD-ZTERM	Payment Terms	BX01
VBKD-INCO1	Incoterms	EXW
VBKD-INCO2_L	Incoterms Location 1	Shanghai
VBAK-AUGRU	Order Reason (ComboBox key)	001
VBAK-LIFSK	Delivery Block (ComboBox key)
VBAK-FAKSK	Billing Block (ComboBox key)
VBAK-AUTLF	Complete Delivery (checkbox)	X

Item Table Fields (ITEM_NN sections):

Item rows are numbered ITEM_01, ITEM_02, etc. Each maps to table row 0, 1, etc.

Field Name	Description	Example
RV45A-MABNR	Material Number	500070
RV45A-KWMENG	Order Quantity	5
VBAP-WERKS	Plant	BX01
VBAP-VRKME	Sales Unit	PC
VBAP-PSTYV	Item Category	TAN
VBAP-KDMAT	Customer Material Number

Example definition file (Create):

# Header
HEADER	KUAGV-KUNNR	20000000
HEADER	VBKD-BSTKD	PO-REF-001
# Sales tab
SALES	RV45A-KETDAT	2026.04.15
SALES	VBKD-ZTERM	BX01
# Item line 1
ITEM_01	RV45A-MABNR	500070
ITEM_01	RV45A-KWMENG	5
# Item line 2
ITEM_02	RV45A-MABNR	500070
ITEM_02	RV45A-KWMENG	10

Example definition file (Update — change customer reference):

HEADER	VBKD-BSTKD	PO-REF-002-UPDATED

Write the definition file

1. Write the field definitions to: {RUN_TEMP}\va01_<ORDER_NUMBER>_fields.txt
   • For new orders use a descriptive name: {RUN_TEMP}\va01_new_fields.txt
   • The per-run directory keeps concurrent sessions from clobbering each other's files.
   • Write the file as UTF-8 (the VBS reads it via ADODB.Stream Charset="utf-8", so JA/ZH values survive intact).
   • Use the tab-separated format above.
   • Include only the fields the user wants to set.
2. Confirm the file by reading it back.

---

Step 3 — Ensure SAP GUI Login

This skill requires an active SAP GUI session. If not already logged in, use the /sap-login skill first, then return here.

---

Step 4 — Check if Order Exists (Update only)

Skip this step if creating a new order.

The check VBScript template is at ./references/sap_va01_check.vbs.

Generate the filled-in VBScript

Write {RUN_TEMP}\sap_va01_check_run.ps1:

$content = [System.IO.File]::ReadAllText('<SKILL_DIR>\references\sap_va01_check.vbs', [System.Text.Encoding]::UTF8)
$content = $content -replace '%%ORDER_NUMBER%%','THE_ORDER_NUMBER'
# Phase 3.5 session-attach plumbing.
$sessionPath = ''
$content = $content -replace '%%SESSION_PATH%%', $sessionPath
$content = $content -replace '%%ATTACH_LIB_VBS%%','<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_attach_lib.vbs'
. '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'
$env:SAPDEV_SESSION_PATH = Get-SapCurrentSessionPath -WorkTemp '{WORK_TEMP}'
[System.IO.File]::WriteAllText('{RUN_TEMP}\sap_va01_check_run.vbs', $content, [System.Text.UnicodeEncoding]::new($false, $true))
Write-Host 'Done'

Replace THE_ORDER_NUMBER with the actual order number and <SKILL_DIR> with the absolute path to this skill directory.

Run:

powershell -ExecutionPolicy Bypass -File "{RUN_TEMP}\sap_va01_check_run.ps1"

Execute

C:\Windows\SysWOW64\cscript.exe //NoLogo {RUN_TEMP}\sap_va01_check_run.vbs

Parse the last line of output:

• EXIST → order exists → proceed to Step 5a (Update via VA02).
• NOT_EXIST → order does not exist → tell user the order was not found.
• ERROR: → show full output and stop. The check reports NOT_EXIST only for the known VA03 not-found message (V1 302, matched via the locale-independent MessageId/MessageNumber); any other error state (authorization, lock, unexpected screen/popup) is ERROR.

---

Step 5a — Update Existing Order (VA02)

The update VBScript template is at ./references/sap_va01_update.vbs.

Generate the filled-in VBScript

Write {RUN_TEMP}\sap_va01_update_run.ps1:

$content = [System.IO.File]::ReadAllText('<SKILL_DIR>\references\sap_va01_update.vbs', [System.Text.Encoding]::UTF8)
$content = $content -replace '%%ORDER_NUMBER%%','THE_ORDER_NUMBER'
$content = $content -replace '%%DEFINITION_FILE%%','THE_DEFINITION_FILE'
$content = $content -replace '%%SESSION_LOCK_VBS%%','<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_session_lock.vbs'
# Incomplete-document policy: '' (default) = abort unsaved on the incompletion
# popup; 'X' ONLY when the user passed --allow-incomplete.
$allowIncomplete = ''
$content = $content -replace '%%ALLOW_INCOMPLETE%%', $allowIncomplete
# Phase 3.5 session-attach plumbing.
$sessionPath = ''
$content = $content -replace '%%SESSION_PATH%%', $sessionPath
$content = $content -replace '%%ATTACH_LIB_VBS%%','<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_attach_lib.vbs'
. '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'
$env:SAPDEV_SESSION_PATH = Get-SapCurrentSessionPath -WorkTemp '{WORK_TEMP}'
[System.IO.File]::WriteAllText('{RUN_TEMP}\sap_va01_update_run.vbs', $content, [System.Text.UnicodeEncoding]::new($false, $true))
Write-Host 'Done'

Replace THE_ORDER_NUMBER, THE_DEFINITION_FILE (absolute path with backslashes), and <SKILL_DIR>.

Run:

powershell -ExecutionPolicy Bypass -File "{RUN_TEMP}\sap_va01_update_run.ps1"

Execute

C:\Windows\SysWOW64\cscript.exe //NoLogo {RUN_TEMP}\sap_va01_update_run.vbs

Proceed to Step 6 to evaluate the result.

---

Step 5b — Create New Order (VA01)

For creating a new order, you need the Order Type and Sales Area (Sales Org, Distribution Channel, Division). Ask the user if not already provided.

The create VBScript template is at ./references/sap_va01_create.vbs.

Generate the filled-in VBScript

Write {RUN_TEMP}\sap_va01_create_run.ps1:

$content = [System.IO.File]::ReadAllText('<SKILL_DIR>\references\sap_va01_create.vbs', [System.Text.Encoding]::UTF8)
$content = $content -replace '%%ORDER_TYPE%%','THE_ORDER_TYPE'
$content = $content -replace '%%SALES_ORG%%','THE_SALES_ORG'
$content = $content -replace '%%DIST_CHANNEL%%','THE_DIST_CHANNEL'
$content = $content -replace '%%DIVISION%%','THE_DIVISION'
$content = $content -replace '%%DEFINITION_FILE%%','THE_DEFINITION_FILE'
$content = $content -replace '%%SESSION_LOCK_VBS%%','<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_session_lock.vbs'
# Incomplete-document policy: '' (default) = abort unsaved on the incompletion
# popup; 'X' ONLY when the user passed --allow-incomplete.
$allowIncomplete = ''
$content = $content -replace '%%ALLOW_INCOMPLETE%%', $allowIncomplete
# Phase 3.5 session-attach plumbing.
$sessionPath = ''
$content = $content -replace '%%SESSION_PATH%%', $sessionPath
$content = $content -replace '%%ATTACH_LIB_VBS%%','<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_attach_lib.vbs'
. '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'
$env:SAPDEV_SESSION_PATH = Get-SapCurrentSessionPath -WorkTemp '{WORK_TEMP}'
[System.IO.File]::WriteAllText('{RUN_TEMP}\sap_va01_create_run.vbs', $content, [System.Text.UnicodeEncoding]::new($false, $true))
Write-Host 'Done'

Replace all THE_* placeholders and <SKILL_DIR>.

Run:

powershell -ExecutionPolicy Bypass -File "{RUN_TEMP}\sap_va01_create_run.ps1"

Execute

C:\Windows\SysWOW64\cscript.exe //NoLogo {RUN_TEMP}\sap_va01_create_run.vbs

Proceed to Step 6 to evaluate the result.

---

Step 6 — Report Result

On success (output contains SUCCESS:):

• Tell the user the sales order was created/updated.
• Parse the machine-readable ORDER: <number> line (echoed right before SUCCESS:) for the saved order number. If it is missing (extraction warning), look the number up via VA03 / the echoed status text.
• If the output also contains WARNING: INCOMPLETE_DOCUMENT_SAVED, tell the user the order was saved with an unresolved incompletion log (--allow-incomplete was in effect).
• Show the full script output as a code block.

On failure (output contains ERROR:):

• Show the full output and diagnose using this table:

Error message	Cause	Fix
Order type ... has not been defined	Invalid order type for sales area	Check order type key and sales area
does not exist in TVAK	Order type key doesn't exist	Verify order type key
is not in the database or has been archived	Order not found (Update)	Check order number
Failed to reach the create overview screen	Initial screen error	Check order type and sales area values
Failed to reach the change overview screen	Order can't be opened for change	Check order status/authorization
Header validation failed	Required header field missing	Ensure Sold-To Party is set
Item validation failed	Invalid item data	Check material number, quantity
Item table not found	Screen structure issue	Contact support
Item column not found	Wrong field name for item	Verify field name (see table below)
INCOMPLETE_DOCUMENT	SAP raised the incompletion popup at save; the order was NOT saved (default policy)	Add the missing data (see the incompletion log in VA01/VA02), or re-run with --allow-incomplete to save anyway
Unexpected popup while saving	Unknown modal at save time — the script refuses to blind-dismiss; nothing was saved	Resolve the popup manually in SAP GUI, then re-run
Could not confirm the save	Save ended without an S status (warning left standing, empty status)	Read the echoed status text; verify via Step 4 whether the order was saved before retrying
No SAP GUI session found	Not logged in	Run login step first
Definition file not found	Wrong path	Verify file path and re-run Step 2

---

Step 7 — Clean Up

Delete the temporary files this run created — only the exact definition file written in Step 2 (va01_<ORDER_NUMBER>_fields.txt or va01_new_fields.txt), never a wildcard over a shared directory:

cmd /c del {RUN_TEMP}\sap_va01_check_run.vbs & del {RUN_TEMP}\sap_va01_check_run.ps1 & del {RUN_TEMP}\sap_va01_create_run.vbs & del {RUN_TEMP}\sap_va01_create_run.ps1 & del {RUN_TEMP}\sap_va01_update_run.vbs & del {RUN_TEMP}\sap_va01_update_run.ps1 & del {RUN_TEMP}\va01_<ORDER_NUMBER>_fields.txt

---

Final — Log End

Log the run-end record. Best-effort.

On success:

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action end -StateFile "{RUN_TEMP}\sap_va01_run.json" -Status SUCCESS -ExitCode 0

On failure:

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action end -StateFile "{RUN_TEMP}\sap_va01_run.json" -Status FAILED -ExitCode 1 -ErrorClass <CLASS> -ErrorMsg "<short>"

Suggested <CLASS>: VA01_FAILED, GUI_TIMEOUT.