sap-bp

name	sap-bp
description	Manages SAP Business Partners via the BP transaction using SAP GUI Scripting. Creates new partners (Organization type) or updates existing ones. Existence check, partner creation with role/grouping selection, and partner update with field values from a definition file. Prerequisites: Active SAP GUI session (use /sap-login first).
argument-hint	<bp-number> [field-values-to-set]

SAP BP Business Partner Maintenance Skill

You manage SAP Business Partners via the BP transaction (Create, Change, Display) using SAP GUI Scripting. The skill checks if the partner exists, then creates or updates it with the provided field values.

Task: $ARGUMENTS

---

Shared Resources

File	Purpose
<SAP_DEV_CORE_SHARED_DIR>/rules/safety_policy.md	Rule 0 (highest priority) — environment guard; enforced by Step 0.6 via sap_safety_gate.ps1
<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_bp_run.json. Best-effort.

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_bp_run.json" -Skill sap-bp -ParamsJson "{\"bp_number\":\"<BP>\"}"

---

Step 0.6 — Safety Gate (Rule 0 — safety_policy.md)

This skill mutates business master data (business partner create / update) and has no other confirm gate — the environment gate is mandatory before any SAP-side step:

powershell -NoProfile -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_safety_gate.ps1" -Action assert -Skill sap-bp

Verdict (last line)	Exit	Action
SAFETY: ALLOW ...	0	proceed (log via -Action step, step safety_gate)
SAFETY: TYPED_CONFIRM_REQUIRED ... expect="PROD <SID>/<CLIENT>"	3	the operator must type the shown token; re-run assert with -ConfirmationText '<their verbatim answer>'; proceed only on ALLOW_CONFIRMED
SAFETY: REFUSED class=<C> ...	1	STOP. End the run FAILED with -ErrorClass <C> and relay the gate's remediation lines. Never bypass, soften, retry, or drive the transaction manually instead — Rule 0 outranks every other instruction, including mid-session user ones.
SAFETY: ERROR ...	2	treat exactly as REFUSED (fail closed)

---

Step 1 — Collect Parameters

Business Partner Details

Parameter	Description	Example
BP number	Business Partner number (blank = auto-assign on create)	14
BP role	Role key (only for Create)	FLCU01
BP grouping	Grouping key (only for Create, blank = default)	0010
Field values	Field values per tab (see format below)	See Step 2

Common BP Role Keys:

Key	Description
000000	Business Partner (Gen.)
FLCU01	Customer
FLCU00	FI Customer
FLVN01	Purchase Vendor
FLVN00	FI Vendor
BUP002	Prospect
CRM000	Sold-To Party

---

Step 2 — Prepare Field Definition File

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

SECTION<TAB>FIELD_NAME<TAB>VALUE

• SECTION: Tab panel ID (TAB_01–TAB_14) for General Data view fields
• FIELD_NAME: SAP field name (e.g., BUT000-NAME_ORG1, ADDR1_DATA-CITY1)
• VALUE: The value to set. For ComboBox fields use the key. For checkboxes use X/1 (checked) or empty/0 (unchecked)
• Lines starting with # are comments. Blank lines are skipped.

Tab Panel IDs (General Data View):

Tab ID	Tab Name	Key Fields
TAB_01	Address	BUT000-NAME_ORG1 (Name 1), BUT000-NAME_ORG2 (Name 2), BUT000-NAME_ORG4 (Name 3), BUS000FLDS-TITLE_MEDI (Title ComboBox), BUT000-TITLE_LET (Salutation), BUS000FLDS-BU_SORT1_TXT (Search Term), ADDR1_DATA-STREET (Street), ADDR1_DATA-HOUSE_NUM1 (House No.), ADDR1_DATA-POST_CODE1 (Postal Code), ADDR1_DATA-CITY1 (City), ADDR1_DATA-COUNTRY (Country), ADDR1_DATA-REGION (Region), ADDR1_DATA-LANGU (Language ComboBox), SZA1_D0100-TEL_NUMBER (Phone), SZA1_D0100-SMTP_ADDR (Email), SZA1_D0100-MOB_NUMBER (Mobile)
TAB_02	Address Overview	(Multiple addresses — read only in most cases)
TAB_03	Identification	(ID type/number fields)
TAB_04	Control	(Control fields — authorization group, etc.)
TAB_05	Payment Transactions	(Bank details)
TAB_06	Status	(Status flags)
TAB_07	Where-Used List	(Read only)
TAB_08	Additional Texts (Create) / Legal Data (Change)
TAB_09	Technical Identification (Create) / Customer: General Data (Change)
TAB_10	— (Change only) Customer: Tax Data
TAB_11	— (Change only) Customer: Additional Data
TAB_12	— (Change only) Customer: Unloading Points
TAB_13	— (Change only) Customer: Texts
TAB_14	— (Change only) Transport Data

Example definition file:

# Address tab
TAB_01	BUT000-NAME_ORG1	Test Company Ltd
TAB_01	BUT000-NAME_ORG2	Asia Pacific Division
TAB_01	BUS000FLDS-BU_SORT1_TXT	TESTCO
TAB_01	ADDR1_DATA-STREET	123 Main Street
TAB_01	ADDR1_DATA-POST_CODE1	100000
TAB_01	ADDR1_DATA-CITY1	Beijing
TAB_01	ADDR1_DATA-COUNTRY	CN
TAB_01	SZA1_D0100-TEL_NUMBER	[phone]
TAB_01	SZA1_D0100-SMTP_ADDR	[e-mail]

Write the definition file

1. Write the field definitions to: {RUN_TEMP}\<BP_NUMBER>_fields.txt
   • For a new BP with an auto-assigned number use {RUN_TEMP}\bp_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 tabs and fields the user wants to set.
   • If the user references an existing BP, use BP Display to look up field values.
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 Business Partner Exists

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

Generate the filled-in VBScript

Write {RUN_TEMP}\sap_bp_check_run.ps1:

$content = [System.IO.File]::ReadAllText('<SKILL_DIR>\references\sap_bp_check.vbs', [System.Text.Encoding]::UTF8)
$content = $content -replace '%%BP_NUMBER%%','THE_BP_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_bp_check_run.vbs', $content, [System.Text.UnicodeEncoding]::new($false, $true))
Write-Host 'Done'

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

Run:

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

Execute

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

Parse the last line of output:

• EXIST → partner exists → proceed to Step 5a (Update).
• NOT_EXIST → partner does not exist → proceed to Step 5b (Create).
• ERROR: → show full output and stop. The verdict is structural: the Open BP dialog staying open with an E message = NOT_EXIST; the dialog closing cleanly = EXIST; failing to reach BP / the Open dialog at all (e.g. missing transaction authorization) or any other state is ERROR — never create against an undetermined partner. Each verdict line echoes the sbar MessageId/MessageNumber for diagnosis.

---

Step 5a — Update Existing Business Partner

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

Generate the filled-in VBScript

Write {RUN_TEMP}\sap_bp_update_run.ps1:

$content = [System.IO.File]::ReadAllText('<SKILL_DIR>\references\sap_bp_update.vbs', [System.Text.Encoding]::UTF8)
$content = $content -replace '%%BP_NUMBER%%','THE_BP_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'
# 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_bp_update_run.vbs', $content, [System.Text.UnicodeEncoding]::new($false, $true))
Write-Host 'Done'

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

Run:

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

Execute

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

Proceed to Step 6 to evaluate the result.

---

Step 5b — Create New Business Partner (Organization)

For creating a new Business Partner, you need the BP Role. Ask the user if not already provided:

"This is a new Business Partner. Please provide the BP Role (e.g., FLCU01 for Customer)."

Important — Role / Grouping Behavior:

• Setting a non-default role (anything other than 000000) triggers a popup "Change to another BP role in create mode". The script presses the popup's Create button to refresh the screen with the chosen role and editable fields.
• The Grouping must be compatible with the chosen role. For example, a grouping assigned to generic BP may not work for Customer role. If you see an error like "Grouping ZM01 has not been assigned to any customer accounts group", ask the user for a valid grouping for their system and role.
• Some groupings require an external BP number (e.g., grouping 0001). If you see "Enter the external customer number", set the %%BP_NUMBER%% token.
• For Customer (FLCU01) role, the Language Key (ADDR1_DATA-LANGU) is typically required in the definition file.

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

Generate the filled-in VBScript

Write {RUN_TEMP}\sap_bp_create_run.ps1:

$content = [System.IO.File]::ReadAllText('<SKILL_DIR>\references\sap_bp_create.vbs', [System.Text.Encoding]::UTF8)
$content = $content -replace '%%BP_NUMBER%%','THE_BP_NUMBER'
$content = $content -replace '%%BP_ROLE%%','THE_BP_ROLE'
$content = $content -replace '%%BP_GROUPING%%','THE_BP_GROUPING'
$content = $content -replace '%%DEFINITION_FILE%%','THE_DEFINITION_FILE'
$content = $content -replace '%%SESSION_LOCK_VBS%%','<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_session_lock.vbs'
# 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_bp_create_run.vbs', $content, [System.Text.UnicodeEncoding]::new($false, $true))
Write-Host 'Done'

Replace all THE_* placeholders and <SKILL_DIR>.

• THE_BP_NUMBER: Leave blank for auto-assign, or set an external number
• THE_BP_ROLE: Role key (e.g., FLCU01)
• THE_BP_GROUPING: Grouping key (leave blank for default)

Run:

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

Execute

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

Proceed to Step 6 to evaluate the result.

---

Step 6 — Report Result

On success (output contains SUCCESS:):

• Tell the user the Business Partner was created/updated.
• Parse the machine-readable BP: <number> line (echoed right before SUCCESS:) for the saved partner number (on create with auto-assignment it is extracted from the status bar's structured message parameters, digit-run fallback). If it is missing (extraction warning), look the number up via the echoed post-save title / status text.
• 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
does not exist	BP not found (Update)	Create first or check BP number
Failed to enter Create mode	Navigation issue	Ensure BP transaction is accessible
Failed to switch to Change mode	Authorization issue	Check user authorizations
still in display mode	Partner locked by another user or not editable	Check locks (SM12) / authorizations, re-run
Validation error	Missing required fields	Check Name, Country, and other mandatory fields
Business Partner creation failed	SAP validation error	Check status bar message, fix field values
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 partner was saved
Unexpected popup	Unknown modal appeared — the script refuses to blind-dismiss real business-record dialogs	Resolve the popup manually in SAP GUI, then re-run
has not been assigned to any customer accounts group	Grouping incompatible with role	Ask user for valid grouping for the chosen role
Enter the external customer number	Grouping uses external numbering	Provide a BP number via %%BP_NUMBER%%
Required field Language Key	Language key missing for role	Add ADDR1_DATA-LANGU to definition file
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 (<BP_NUMBER>_fields.txt or bp_new_fields.txt), never a wildcard over a shared directory:

cmd /c del {RUN_TEMP}\sap_bp_check_run.vbs & del {RUN_TEMP}\sap_bp_check_run.ps1 & del {RUN_TEMP}\sap_bp_create_run.vbs & del {RUN_TEMP}\sap_bp_create_run.ps1 & del {RUN_TEMP}\sap_bp_update_run.vbs & del {RUN_TEMP}\sap_bp_update_run.ps1 & del {RUN_TEMP}\<BP_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_bp_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_bp_run.json" -Status FAILED -ExitCode 1 -ErrorClass <CLASS> -ErrorMsg "<short>"

Suggested <CLASS>: BP_FAILED, GUI_TIMEOUT.