| 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 +86-10-12345678
TAB_01 SZA1_D0100-SMTP_ADDR info@testcompany.com
Write the definition file
- 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.
- 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 numberTHE_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.
